AS/400e ÉÂÔ ILE RPG for AS/400 Programmer's Guide Version 4 SC09-2507-02
AS/400e ÉÂÔ ILE RPG for AS/400 Programmer's Guide Version 4 SC09-2507-02
Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page xi. Third Edition (May 1999) This edition applies to Version 4, Release 4, Modification 0, of IBM Application System/400 Integrated Language Environment RPG for AS/400 (Program 5769-RG1) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition applies only to reduced instruction set computer (RISC) systems.
Contents Notices . . . . . . . . . . . . . . . Programming Interface Information Trademarks and Service Marks . | | . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About This Guide . . . . . . . . . . . Who Should Use This Guide . . . . . Prerequisite and Related Information How to Send Your Comments . . . . What's New This Release? . . . . . . Changes to this Guide Since V4R2 ILE RPG Introduction . . . . . . . . . . . . . . . . . . . . . . . . . .
A Strategy to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4. Creating an Application Using Multiple Procedures A Multiple Procedures Module — Overview . . . . . . . . . . . . . Main Procedures and Subprocedures . . . . . . . . . . . . . . . Prototyped Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example of Module with Multiple Procedures . . . . . . . . . . . . . The Entire ARRSRPT Program . . . . . . . . . . . . . . . . . . .
Changing the Optimization Level Removing Observability . . . . Reducing an Object's Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 8. Creating a Service Program . . . Service Program Overview . . . . . . . . . . . . Strategies for Creating Service Programs . . . . Creating a Service Program Using CRTSRVPGM Changing A Service Program . . . . . . . . . Related CL commands . . . . . .
Using the Fixed-Form Call Operations . . . . . . . . . Examples of CALL and CALLB . . . . . . . . . . . Passing Parameters Using PARM and PLIST . . . Returning from a Called Program or Procedure . . . Returning from a Main Procedure . . . . . . . . . . Returning from a Subprocedure . . . . . . . . . . . Returning using ILE Bindable APIs . . . . . . . . . Using Bindable APIs . . . . . . . . . . . . . . . . . . . Examples of Using Bindable APIs . . . . . . . . . Calling a Graphics Routine . . . . . . . . . .
Displaying Attributes of a Field . . . . . . . . . . . . . . . Equating a Name with a Field, Expression, or Command Source Debug National Language Support for ILE RPG Sample Source for Debug Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 12. Handling Exceptions . . . . . . . . . . . . . . . . . Exception Handling Overview . . . . . . . . . . . . . . . . . . . . . ILE RPG Exception Handling . . . . . . . . . . . . . . .
SRTSEQ/ALTSEQ in an RPG Program versus a DDS File Chapter 16. Accessing Database Files . . Database Files . . . . . . . . . . . . . . . . . . Physical Files and Logical Files . . . . . . . Data Files and Source Files . . . . . . . . . Using Externally Described Disk Files . . . . . Record Format Specifications . . . . . . . . Access Path . . . . . . . . . . . . . . . . . . Valid Keys for a Record or File . . . . . . . Record Blocking and Unblocking . . . . . . Using Program-Described Disk Files . . . . . .
Using a Program-Described WORKSTN File without a Format Name Valid WORKSTN File Operations . . . . . . . . . . . . . . . . . . . . . EXFMT Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . READ Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WRITE Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple-Device Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 19. Example of an Interactive Application Database Physical File . .
Analyzing Your Conversion . . . . . . . . . . . Using the Conversion Report . . . . . . . . Using the Log File . . . . . . . . . . . . . . . Resolving Conversion Problems . . . . . . . . Compilation Errors in Existing RPG III Code Unsupported RPG III Features . . . . . . . Use of the /COPY Compiler Directive . . . Use of Externally Described Data Structures Run-time Differences . . . . . . . . . . . . . Appendix C. The Create Commands . . . . Using CL Commands . . . . . . . . . . . . . .
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. This information contains examples of data and reports used in daily business operations.
Registered trademarks and unregistered trademarks are denoted by and respectively.
xiv ILE RPG for AS/400 Programmer's Guide
About This Guide This guide provides information that shows how to use the ILE RPG for AS/400 compiler (ILE RPG) in the Integrated Language Environment. ILE RPG is an implementation of the RPG IV language on the AS/400 system with the Operating System/400 (OS/400) operating system. Use this guide to create and run ILE applications from RPG IV source.
Prerequisite and Related Information Use the AS/400 Information Center as your starting point for looking up AS/400 technical information. You can access the Information Center from the AS/400e Information Center CD-ROM (English version: SK3T-2027-01) or from one of these Web sites: http://www.as400.ibm.com/infocenter http://publib.boulder.ibm.com/pubs/html/as400/infocenter.
| What's New This Release? | | | | | The major enhancements to RPG IV since V4R2 are the support for running ILE RPG modules safely in a threaded environment, the new 3-digit and 20-digit signed and unsigned integer data types, and support for a new Universal Character Set Version 2 (UCS-2) data type and for conversion between UCS-2 fields and graphic or single-byte character fields.
| | | | | | – *SRCSTMT allows you to assign statement numbers for debugging from the source IDs and SEU sequence numbers in the compiler listing. (The statement number is used to identify errors in the compiler listing by the debugger, and to identify the statement where a run-time error occurs.) *NOSRCSTMT specifies that statement numbers are associated with the Line Numbers of the listing and the numbers are assigned sequentially.
| Table 1. Changed Language Elements Since V4R2 | Language Unit Element Description | | | | | | | | Control specification keywords OPTION(*{NO}SRCSTMT) *SRCSTMT allows you to request that the compiler use SEU sequence numbers and source IDs when generating statement numbers for debugging. Otherwise, statement numbers are associated with the Line Numbers of the listing and the numbers are assigned sequentially.
| Table 2 (Page 1 of 2). New Language Elements Since V4R2 Language Unit Element Description Control specification keywords CCSID(*GRAPH: *IGNORE | *SRC | number) Sets the default graphic CCSID for the module. This setting is used for literals, compile-time data and program-described input and output fields and definitions. The default is *IGNORE. | | | | | | CCSID(*UCS2: number) Sets the default UCS-2 CCSID for the module.
| Table 2 (Page 2 of 2). New Language Elements Since V4R2 | Language Unit Element Description | | | Operation codes EVALR Evaluates an assignment statement of the form result=expression. The result will be right-justified. | | | | | FOR Begins a group of operations and indicates the number of times the group is to be processed. The initial, increment, and limit values can be free-form expressions. | | ENDFOR ENDFOR ends a group of operations started by a FOR operation.
xxii ILE RPG for AS/400 Programmer's Guide
ILE RPG Introduction Before using ILE RPG to create a program, you must know certain aspects of the environment in which you will be using it. This part provides information on the following topics that you should know: ¹ Overview of RPG IV language ¹ Role of Integrated Language Environment components in RPG programming ¹ Integrated Language Environment program creation strategies ¹ Overview of coding a module with more than one procedure and prototyped calls Copyright IBM Corp.
2 ILE RPG for AS/400 Programmer's Guide
RPG IV Overview Chapter 1. Overview of the RPG IV Programming Language This chapter presents a high-level review of the features of the RPG IV programming language that distinguish RPG from other programming languages. You should be familiar and comfortable with all of these features before you program in the RPG IV language.
RPG IV Overview Cycle Programming When a system processes data, it must do the processing in a particular order. This logical order is provided by: ¹ The ILE RPG compiler ¹ The program code The logic the compiler supplies is called the program cycle. When you let the compiler provide the logic for your programs, it is called cycle programming. The program cycle is a series of steps that your program repeats until an end-of-file condition is reached.
RPG IV Overview .2/ RPG reads the next record and sets on the record identifying and control level indicators. .3/ RPG processes total calculations (conditioned by control level indicators L1 through L9, an LR indicator, or an L0 entry). .4/ RPG processes all total output lines (identified by a T in position 17 of the output specifications). .5/ RPG determines if the LR indicator is on. If it is on, the program ends. .
Example of an ILE RPG Program Each RPG IV indicator has a two-character name (for example, LR, 01, H3), and is referred to in some entries of some specifications just by the two-character name, and in others by the special name *INxx where xx is the two-character name. You can use several types of these indicators; each type signals something different. The positions on the specification in which you define an indicator determine the use of the indicator.
Example of an ILE RPG Program *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* A..........T.Name++++++RLen++TDpB......Functions++++++++++++++++++++* A R EMP_REC A EMP_NUMBER 5 TEXT('EMPLOYEE NUMBER') A EMP_NAME 16 TEXT('EXPLOYEE NAME') A EMP_RATE 5 2 TEXT('EXPLOYEE RATE') A K EMP_NUMBER Figure 2. DDS for Employee physical file The second file, TRANSACT, tracks the number of hours each employee worked for that week and any bonus that employee may have received.
Example of an ILE RPG Program ¹ The TRANSACT file is defined as the Input Primary file. The ILE RPG program cycle controls the reading of records from this file. ¹ The EMPLOYEE file is defined as the Input Full-Procedure file. The reading of records from this file is controlled by operations in the calculation specifications. ¹ The QSYSPRT file is defined as the Output Printer file. Definition Specifications *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+...
Example of an ILE RPG Program *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... OFilename++DF..N01N02N03Excnam++++B++A++Sb+Sa+........................... O..............N01N02N03Field+++++++++YB.End++PConstant/editword/DTformat OQSYSPRT H 1P 2 3 O 35 'PAYROLL REGISTER' O *DATE Y 60 O H 1P 2 O 60 Heading1 O H 1P 2 O 60 Heading2 O D N1PN99 2 O TRN_NUMBER 5 O EMP_NAME 24 O EMP_RATE L 33 O TRN_HOURS L 40 O TRN_BONUS L 49 O Pay 60 '$ 0.
Example of an ILE RPG Program P CalcPay B D CalcPay PI 8P 2 D Rate 5P 2 VALUE D Hours 10U 0 VALUE D Bonus 5P 2 VALUE D Overtime S 5P 2 INZ(0) * Determine any overtime hours to be paid. C IF Hours > 40 C EVAL Overtime = (Hours - 40) * Rate * 1.5 C EVAL Hours = 40 C ENDIF * Calculate the total pay and return it to the caller C RETURN Rate * Hours + Bonus + Overtime P CalcPay E The Entire Source Program The following figure combines all the specifications used in this program.
Example of an ILE RPG Program *------------------------------------------------------------------------* * Constant Declarations * *------------------------------------------------------------------------* D Heading1 C 'NUMBER NAME RATE HD OURS BONUS PAY ' D Heading2 C '______ ________________ ______ _D ____ _______ __________' *------------------------------------------------------------------------* * Prototype Definition for subprocedure CalcPay * *-------------------------------------------------------
Using the OS/400 System *------------------------------------------------------------------------* * Subprocedure -- calculates overtime pay. * *------------------------------------------------------------------------* P CalcPay B D CalcPay PI 8P 2 D Rate 5P 2 VALUE D Hours 10U 0 VALUE D Bonus 5P 2 VALUE D Overtime S 5P 2 INZ(0) * Determine any overtime hours to be paid. C IF Hours > 40 C EVAL Overtime = (Hours - 40) * Rate * 1.
AS/400 Tools Table 3.
AS/400 Tools ¹ Define a flexible environment where production, testing, and maintenance can be managed simultaneously ¹ Organize several developers working on the same application ¹ Build (or compile) an application quickly and easily, compiling only those components that need compiling ¹ Create and maintain several versions of an application Application Dictionary Services Application Dictionary Services is an impact analysis tool that speeds up the analysis of applications.
AS/400 Tools ¹ Program verification— performs, at the workstation, the full range of syntax and semantic checking that the compiler does, without generating object code ¹ Program conversion— performs, at the workstation, an OPM to ILE RPG conversion ¹ A windowed environment for submitting host compiles and binds ¹ Source-level debugging ¹ A DDS design utility—allows you to easily change screens, reports, and database files ¹ Access to Application Dictionary Services.
AS/400 Tools 16 ILE RPG for AS/400 Programmer's Guide
RPG Programming in ILE Chapter 2. RPG Programming in ILE ILE RPG is an implementation of the RPG IV programming language in the Integrated Language Environment. It is one of the family of ILE compilers available on the AS/400 system. ILE is a recent approach to programming on the AS/400 system. It is the result of major enhancements to the AS/400 machine architecture and the OS/400 operating system. The ILE family of compilers includes: ILE RPG, ILE C, ILE COBOL, ILE CL, and VisualAge for C++.
RPG Programming in ILE Alternatively, you may create a program using separate commands for compilation and binding. This two-step process allows you to reuse a module or update one module without recompiling the other modules in a program. In addition, because you can combine modules from any ILE language, you can create and maintain mixed-language programs. In the two-step process, you create a module object using the Create RPG Module (CRTRPGMOD) command.
RPG Programming in ILE step process, see Chapter 7, “Creating a Program with the CRTRPGMOD and CRTPGM Commands” on page 73. For more information on service programs, see Chapter 8, “Creating a Service Program” on page 91. Program Management ILE provides a common basis for: ¹ Managing program flow ¹ Sharing resources ¹ Using application program interfaces (APIs) ¹ Handling exceptions during a program's run time It gives RPG users much better control over resources than was previously possible.
RPG Programming in ILE procedure names are resolved at bind time (that is, when you create the program), static calls are faster than dynamic calls. Static calls also allow ¹ Operational descriptors ¹ Omitted parameters ¹ The passing of parameters by value ¹ The use of return values ¹ A greater number of parameters to be passed Operational descriptors and omitted parameters can be useful when calling bindable APIs or procedures written in other ILE languages.
RPG Programming in ILE ¹ CEEDOD – Decompose Operational Descriptor Note: You cannot use these or any other ILE bindable APIs from within a program created with DFTACTGRP(*YES). This is because bound calls are not allowed in this type of program. For more information on these ILE bindable APIs, see Chapter 9, “Running a Program” on page 103 and also the System API Reference. | Multithreaded Applications | | | | | | The AS/400 now supports multithreading.
RPG Programming in ILE 22 ILE RPG for AS/400 Programmer's Guide
OPM-Compatible Application Chapter 3. Program Creation Strategies There are many approaches you can take in creating programs using an ILE language. This section presents three common strategies for creating ILE programs using ILE RPG or other ILE languages. 1. Create a program using CRTBNDRPG to maximize OPM compatibility. 2. Create an ILE program using CRTBNDRPG. 3. Create an ILE program using CRTRPGMOD and CRTPGM. The first strategy is recommended as a temporary one.
OPM-Compatible Application Example of OPM-Compatible Program Figure 6 shows the run-time view of a sample application where you might want an OPM-compatible program. The OPM application consisted of a CL program and two RPG programs. In this example, one of the RPG programs has been moved to ILE; the remaining programs are unchanged. Job Default Activation Group *PGM(X) OPM CL *PGM(Y) ILE RPG *PGM(Z) OPM RPG Figure 6.
ILE Program Using CRTBNDRPG Related Information Converting to RPG IV “Converting Your Source” on page 382 One-step creation process Chapter 6, “Creating a Program with the CRTBNDRPG Command” on page 57 ILE static binding Chapter 10, “Calling Programs and Procedures” on page 127; also ILE Concepts Exception handling differences “Differences between OPM and ILE RPG Exception Handling” on page 222 Strategy 2: ILE Program Using CRTBNDRPG Strategy 2 results in an ILE program that can take advantage of I
ILE Program Using CRTBNDRPG Example of ILE Program Using CRTBNDRPG Figure 7 shows the run-time view of an application in which an ILE CL program calls an ILE RPG program that is bound to a supplied service program. The application runs in the named activation group XYZ. Job XYZ Activation Group *PGM(X) ILE CL *PGM(Y) ILE RPG *SRVPGM(Z) Supplied Service Program Figure 7.
ILE Application Using CRTRPGMOD with programs in different activation groups. If you want to share a file across activation groups, you must open it at the job level by specifying SHARE(*YES) on an override command or create the file with SHARE(*YES). Errors When you call an ILE RPG program or procedure in the same activation group, if it gets an exception that would previously have caused it to display an inquiry message, now your calling program will see that exception first.
ILE Application Using CRTRPGMOD ¹ An advanced application The effect of ILE is the same as described in “Effect of ILE” on page 26. You may want to read about the basic ILE concepts in ILE Concepts before using this approach. Method Because this approach is the most flexible, it includes a number of ways in which you might create an ILE application. The following list describes the main steps that you may need to perform: 1.
ILE Application Using CRTRPGMOD Job XY Activation Group *PGM(X) RPG *PGM(Y) RPG *MODULE(Y1) RPG *MODULE(Y2) RPG *MODULE(Y3) RPG *MODULE(Y4) Figure 8. Single-Language Application Using CRTRPGMOD and CRTPGM The call from program X to program Y is a dynamic call. The calls among the modules in program Y are static calls. See “Effect of ILE” on page 26 for details on the effects of ILE on the way your application handles calls, data, files and errors.
ILE Application Using CRTRPGMOD Job Y Activation Group *PGM(Y) CL *MODULE(Y1) RPG *MODULE(Y2) C *MODULE(Y3) Default Activation Group *PGM(QUSCRTUS) RPG *MODULE(Y4) Figure 9. Mixed-Language Application The call from program Y to the OPM API is a dynamic call. The calls among the modules in program Y are static calls. See “Effect of ILE” on page 26 for details on the effects of ILE on the way your application handles calls, data, files and errors.
A Strategy to Avoid Job XYZ Activation Group *PGM(X) CL *MODULE(X1) *SRVPGM(Y) RPG *MODULE(X2) RPG *SRVPGM(Z) C *MODULE(Z1) CL *MODULE(Z2) Figure 10. Advanced Application The calls from program X to service programs Y and Z are static calls. See “Effect of ILE” on page 26 for details on the effects of ILE on the way your application handles calls, data, files and errors.
A Strategy to Avoid Job Default Activation Group *PGM(X) CL QILE Activation Group *PGM(Y) RPG *SRVPGM(Z) RPG Figure 11. Scenario to Avoid. An application is split between the OPM default activation group and a named activation group. When split across the default activation group and any named activation group, you are mixing OPM behavior with ILE behavior. For example, programs in the default activation group may be expecting the ILE programs to free their resources when the program ends.
Multiple Procedures Module Chapter 4. Creating an Application Using Multiple Procedures The ability to code more than one procedure in an ILE RPG module greatly enhances your ability to code a modular application. This chapter discusses why and how you might use such a module in your application.
Multiple Procedures Module Subprocedures offer another feature. You can pass parameters to a subprocedure by value, and you can call a subprocedure in an expression to return a value. Figure 12 on page 34 shows what a module might look like with multiple procedures.
Multiple Procedures Module ¹ The number and nature of the parameters ¹ Which parameters must be passed, and which are optionally passed ¹ Whether operational descriptors are passed (for a procedure) ¹ The data type of the return value, if any (for a procedure) The prototype is used by the compiler to call the program or procedure correctly, and to ensure that the caller passes the correct parameters.
Example of Module with Multiple Procedures In order to format the name and address properly, FmtCust calls NumToChar to convert the customer number to a character field. Because FmtCust wants to use the return value, the call to NumToChar is made in an expression. Figure 16 on page 36 shows the call.
Example of Module with Multiple Procedures ARRSRPT MODULE Main Procedure Open file, read record, write output records, close files InArrears Subprocedure to determine if customer record is in arrears FmtCust Subprocedure to format customer data into report form Figure 17. Components of the ARRSRPT Module Now consider the first subprocedure, InArrears, which is shown in Figure 18. InArrears is called by the main procedure to determine if the current record is in arrears.
Example of Module with Multiple Procedures .1/ All subprocedures begin and end with procedure specifications. .2/ After the Begin-Procedure specification (B in position 24 of the procedure specification), you code a procedure interface definition. The return value, if any, is defined on the PI specification. Any parameters are listed after the PI specification. .3/ Any variables or prototypes that are used by the subprocedure are defined after the procedure interface definition. .
Example of Module with Multiple Procedures *--------------------------------------------------------------* * FmtCust formats CUSTNAME, CUSTNUM, STREETNAME etc into * readable forms * * Parameters: Name (output) * Address (output) * Globals: CUSTNAME, CUSTNUM, STREETNUM, STREETNAME, CITY STATE, ZIP * Returns: (none) *--------------------------------------------------------------* P FmtCust B D FmtCust PI D Name 100A D Address 100A D ZipChar S 5A *------------------------------------------------------------
Example of Module with Multiple Procedures *=================================================================* * Source for module CVTPROCS. This module does not have a * main procedure, as indicated by the keyword NOMAIN. *=================================================================* H NOMAIN *-----------------------------------------------------------------* * The prototype must be available to EACH module containing * a prototyped procedure. The /COPY pulls in the prototype * for NumToChar.
Example of Module with Multiple Procedures The Entire ARRSRPT Program The ARRSRPT program consists of two modules: ARRSRPT and CVTPROCS. Figure 21 shows the different pieces of our mini-application. ARRSRPT *PGM /COPY member CVTPROCP ARRSRPT *MODULE Main Procedure InArrears CUSTFILE DDS FmtCust CVTPROCS *MODULE NOMAIN NumToChar CUSTRPT DDS Figure 21. The ARRSRPT Application Figure 22 shows the source for the entire ARRSRPT module.
Example of Module with Multiple Procedures *--------------------------------------------------------------* * P R O T O T Y P E S *--------------------------------------------------------------* /COPY QRPGLE,CVTPROCP *--------------------------------------------------------------* * InArrears returns '1' if the customer is in arrears *--------------------------------------------------------------* D InArrears PR 1A *--------------------------------------------------------------* * FmtCust formats CUSTNAME,
Example of Module with Multiple Procedures * Body of procedure C *ISO MOVE DUEDATE DateDue C CurDate SUBDUR DateDue DaysLate:*D C IF DaysLate > 60 AND C AMOUNT > 100.
Example of Module with Multiple Procedures Sample output for the program ARRSRPT is shown in Figure 23 on page 44. Customer number: 00001 ABC Electronics (Customer number 1) 15 Arboreal Way, Treetop MN 12345 Amount outstanding: $1234.56 Due date: 1995-05-01 Customer number: 00152 A&P Electronics (Customer number 152) 27 Garbanzo Avenue, Smallville MN 51423 Amount outstanding: $26544.50 Due date: 1995-02-11 Figure 23.
Coding Considerations A*================================================================* A* FILE NAME : CUSTRPT A* RELATED PGMS : ARRSRPT A* DESCRIPTIONS : THIS IS THE PRINTER FILE CUSTRPT. IT HAS A* ONE RECORD FORMAT CALLED ARREARS.
Coding Considerations Program Creation ¹ If you specify that a module does not have a main procedure then you cannot use the CRTBNDRPG command to create the program. (A module does not have a main procedure if the NOMAIN keyword is specified on a control specification.) This is because the CRTBNDRPG command requires that the module contain a program entry procedure and only a main procedure can be a program entry procedure.
For Further Information The automatic storage that is associated with earlier invocations is unaffected by later invocations. All invocations share the same static storage, so later invocations can affect the value held by a variable in static storage. Recursion can be a powerful programming technique when properly understood. ¹ The run-time behavior of a subprocedure differs somewhat from that of a main procedure, because there is no cycle code for the subprocedure.
For Further Information Prototyped Call 48 Topic See Free-form call “Using a Prototyped Call” on page 133 General Information ILE RPG for AS/400 Reference, Chapter 24 Passing parameters “Passing Prototyped Parameters” on page 135 Prototypes Chapter on defining data and prototypes in the ILE RPG for AS/400 Reference ILE RPG for AS/400 Programmer's Guide
Creating and Running an ILE RPG Application This section provides you with the information that is needed to create and run ILE RPG programs. It describes how to: ¹ Enter source statements ¹ Create modules ¹ Read compiler listings ¹ Create programs ¹ Create service programs ¹ Run programs ¹ Pass parameters ¹ Manage the run time ¹ Call other programs or procedures Many Integrated Language Environment terms and concepts are discussed briefly in the following pages.
50 ILE RPG for AS/400 Programmer's Guide
Chapter 5. Entering Source Statements This chapter provides the information you need to enter RPG source statements. It also briefly describes the tools necessary to complete this step. To enter RPG source statements into the system, use one of the following methods: ¹ Interactively using SEU ¹ Interactively using CODE/400 Initially, you may want to enter your source statements into a file called QRPGLESRC. New members of the file QRPGLESRC automatically receive a default type of RPGLE.
Using SEU Using the Source Entry Utility (SEU) You can use the Source Entry Utility (SEU) to enter your source statements. SEU also provides prompting for the different specification templates as well as syntax checking. To start SEU, use the STRSEU (Start Source Entry Utility) command. For other ways to start and use SEU, refer to the ADTS for AS/400: Source Entry Utility manual.
Using SEU Columns . . .
Using SEU *===============================================================* * MODULE NAME: EMPRPT * RELATED FILES: EMPMST (PHYSICAL FILE) * QSYSPRT (PRINTER FILE) * DESCRIPTION: This program prints employee information * from the file EMPMST.
Using SQL Statements A***************************************************************** A* DESCRIPTION: This is the DDS for the physical file EMPMST. * A* It contains one record format called EMPREC. * A* This file contains one record for each employee * A* of the company.
Using SQL Statements ...+....1....+....2....+....3....+....4....+....5....+....6....+....7.. C C (ILE RPG calculation operations) C C/EXEC SQL (the starting delimiter) C+ C+ (continuation lines containing SQL statements) C+ . . . C/END-EXEC (the ending delimiter) C C (ILE RPG calculation operations) C Figure 30. SQL Statements in an ILE RPG Program You must enter a separate command to process the SQL statements.
Using the CRTBNDRPG Command Chapter 6. Creating a Program with the CRTBNDRPG Command This chapter shows you how to create an ILE program using RPG IV source with the Create Bound RPG Program (CRTBNDRPG) command. With this command you can create one of two types of ILE programs: 1. OPM-compatible programs with no static binding 2.
Using the CRTBNDRPG Command command. For more information see Chapter 7, “Creating a Program with the CRTRPGMOD and CRTPGM Commands” on page 73. You can use the CRTBNDRPG command interactively, in batch, or from a Command Language (CL) program. If you are using the command interactively and require prompting, type CRTBNDRPG and press F4 (Prompt). If you need help, type CRTBNDRPG and press F1 (Help). Table 5 summarizes the parameters of the CRTBNDRPG command and shows their default values.
Using the CRTBNDRPG Command Table 5 (Page 2 of 2).
Using the CRTBNDRPG Command Figure 31 on page 60 shows the screen which appears after entering the above command. Program: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Display Module Source EMPRPT Library: MYLIB Module: EMPRPT *==============================================================* * MODULE NAME: EMPRPT * RELATED FILES: EMPMST (PHYSICAL FILE) * QSYSPRT (PRINTER FILE) * DESCRIPTION: This program prints employee information * from the file EMPMST.
Using the CRTBNDRPG Command Note: DFTACTGRP must be set to *NO in order for you to enter a value for the ACTGRP and BNDDIR parameters. For more information on service programs, see Chapter 8, “Creating a Service Program” on page 91. Creating an OPM-Compatible Program Object In this example you use the CRTBNDRPG command to create an OPM-compatible program object from the source for the payroll program, shown in Figure 32 on page 62. 1.
Using the CRTBNDRPG Command *------------------------------------------------------------------------* * DESCRIPTION: This program creates a printed output of employee's pay * * for the week.
Using a Compiler Listing Using a Compiler Listing This section discusses how to obtain a listing and how to use it to help you: ¹ Fix compilation errors ¹ Fix run-time errors ¹ Provide documentation for maintenance purposes. See Appendix D, “Compiler Listings” on page 423 for more information on the different parts of the listing and for a complete sample listing. Obtaining a Compiler Listing To obtain a compiler listing specify OUTPUT(*PRINT) on either the CRTBNDRPG command or the CRTRPGMOD command.
Using a Compiler Listing *SHOWSKP Source lines excluded by conditional compilation directives (appear in source section of listing) *EXPDDS Key field information (separate section) *XREF List of Cross references (separate section) *EXT List of External references (separate section) *SECLVL Second-level message text (appear in message summary section) Note: Except for *SECLVL and *SHOWSKP, all of the above values reflect the default settings on the OPTION parameter for both create commands.
Using a Compiler Listing ¹ Select one of the following time separators: *SYSVAL, *BLANK, colon (:), comma (,) or period (.) Anywhere a date or time field appears in the listing, these values are used. Customizing the Spacing Each section of a listing usually starts on a new page; Each page of the listing starts with product information, unless the source member contains a /TITLE directive. If it does, the product information appears on the second line and the title appears on the first line.
Using a Compiler Listing Line Number 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 <--------------------- Source Specifications ----------------------------------------------><---- Comments ----> Src Seq ....1....+....2....+<-------- 26 - 35 -------->....4....+....5....+....6....+....7....+....8....+....9....+...
Using a Compiler Listing Lists the start and end positions along with the literal text or field names. Use this to check for errors in your output specifications. ¹ Compile-time data ALTSEQ and FTRANS records and tables are listed. NLSS information and tables are listed. Tables and arrays are explicitly identified. Use this to confirm that you have specified the compile-time data in the correct order, and that you have specified the correct values for the SRTSEQ and LANGID parameters to the compiler.
Using a Compiler Listing Using Additional-Diagnostic Messages The Additional Diagnostic Messages section identifies errors which arise when one or more lines of code are viewed collectively. These messages are not placed within the code where the problem is; in general, the compiler does not know at the time of checking that portion of the source that a problem exists.
Using a Compiler Listing Coordinating Listing Options with Debug View Options Correcting run-time errors often involves debugging a program. The following considerations may help you when you go to debug your program: ¹ If you use the source debugger to debug your program you have a choice of debug views: *STMT, *SOURCE, *LIST, *COPY, *ALL. | | | | ¹ If you plan to use a compiler listing as an aid while debugging, then you can obtain one by specifying OUTPUT(*PRINT).
Accessing the RETURNCODE Data Area ¹ *SHOWSKP allows you to see the statements that are ignored by the compiler as a result of /IF, /ELSEIF, /ELSE, OR /EOF directives. ¹ *XREF allows you to check the use of files, fields, and indicators within the module/program. ¹ *EXT allows you to see which procedures and fields are imported or exported by the module/program. It also identifies the actual files which were used for generating the descriptions for externally described files and data structures.
Accessing the RETURNCODE Data Area 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-329 Not set. Always blank 330-334 Total elapsed compile time to the nearest 10th of a second 335 Not set. Always blank 336-340 Elapsed compile time to the nearest 10th of a second 341-345 Elapsed translator time to the nearest 10th of a second 346-379 Not set.
Accessing the RETURNCODE Data Area 72 ILE RPG for AS/400 Programmer's Guide
Creating a Module Object Chapter 7. Creating a Program with the CRTRPGMOD and CRTPGM Commands The two-step process of program creation consists of compiling source into modules using CRTRPGMOD and then binding one or more module objects into a program using CRTPGM. With this process you can create permanent modules. This in turn allows you to modularize an application without recompiling the whole application. It also allows you to reuse the same module in different applications.
Creating a Module Object ¹ Reuse pieces of code. This generally results in smaller programs. Smaller programs give you better performance and easier debugging capabilities. ¹ Maintain shared code with little chance of introducing errors to other parts of the overall program. ¹ Manage large programs more effectively. Modules allow you to divide your old program into parts that can be managed separately. If the program needs to be enhanced, you only need to recompile those modules which have been changed.
Creating a Module Object Table 6 (Page 2 of 2).
Creating a Module Object You bind a module containing NOMAIN to another module using one of the following commands: a. CRTPGM command b. CRTSRVPGM command c. CRTBNDRPG command where the NOMAIN module is included in a binding directory. 2. Once it is bound, this module object can be debugged using a statement view. A compiler listing for the module is also produced. 3. Type one of the following CL commands to see the compiler listing.
Creating a Module Object *-----------------------------------------------------------------* Subprocedure Trans_Inc *-----------------------------------------------------------------P Trans_Inc B EXPORT D Trans_Inc PI 11P 2 D ProdNum 10P 0 VALUE D Quantity 5P 0 VALUE D Discount 2P 2 VALUE D Factor S 5P 0 * C SELECT C WHEN ProdNum = 1 C EVAL Factor = 1500 C WHEN ProdNum = 2 C EVAL Factor = 3500 C WHEN ProdNum = 5 C EVAL Factor = 20000 C WHEN ProdNum = 8 C EVAL Factor = 32000 C WHEN ProdNum = 12 C EVAL Facto
Creating a Module Object * Prototype for Trans_Inc Trans_Inc PR Prod Quantity Discount 11P 10P 5P 2P 2 0 0 2 VALUE VALUE VALUE * Prototype for Prod_Name Prod_Name PR Prod 40A 10P 0 VALUE D D D D D D Figure 37. Source for TRANSP /COPY member Creating a Module for Source Debugging In this example, you create an ILE RPG module object that you can debug using the source debugger. The module TRANSRPT contains a main procedure which drives the report processing.
Creating a Module Object *=================================================================* * MODULE NAME: TRANSRPT * RELATED FILES: TRNSDTA (PF) * RELATED SOURCE: TRANSSVC (Transaction services) * EXPORTED PROCEDURE: TRANSRPT * The procedure TRANSRPT reads every tranasction record * stored in the physical file TRNSDTA. It calls the * subprocedure Trans_Inc which performs calculations and * returns a value back. Then it calls Prod_Name to * to determine the product name.
Creating a Module Object A***************************************************************** A* RELATED FILES: TRNSRPT * A* DESCRIPTION: This is the physical file TRNSDTA. It has * A* one record format called TRNSREC. * A***************************************************************** A* PARTS TRANSACTION FILE -- TRNSDTA A R TRNSREC A PROD 10S 0 TEXT('Product') A QTY 5S 0 TEXT('Quantity') A DISCOUNT 2S 2 TEXT('Discount') Figure 39.
Binding Modules into a Program Binding Modules into a Program Binding is the process of creating a runnable ILE program by combining one or more modules and optional service programs, and resolving symbols passed between them. The system code that does this combining and resolving is called a binder on the AS/400 system. As part of the binding process, a procedure must be identified as the startup procedure, or program entry procedure.
Binding Modules into a Program In addition to binding modules together, you can also bind them to service programs (type *SRVPGM). Service programs allow you to code and maintain modules separately from the program modules. Common routines can be created as service programs and if the routine changes, the change can be incorporated by binding the service program again. The programs that use these common routines do not have to be recreated.
Binding Modules into a Program terminate when the program does. Whether or not you set on LR, your program will have a fresh copy of its data the next time you call it. For more information on activation groups see “Specifying an Activation Group” on page 110. To create a program object using the CRTPGM command, perform the following steps: 1. Enter the CRTPGM command. 2. Enter the appropriate values for the command parameter. Table 7 lists the CRTPGM command parameters and their default values.
Binding Modules into a Program 9. Once all the imports have been resolved, the binding process completes and the program object is created. Note: If you have specified that a variable or procedure is to be exported (using the EXPORT keyword), it is possible that the variable or procedure name will be identical to a variable or procedure in another procedure within the bound program object. In this case, the results may not be as expected. See ILE Concepts for information on how to handle this situation.
Using a Binder Listing Product name -----------------------------Large Super Super Large Super Jumbo Incredibly Large Super Jumbo ***Unknown*** Total: 4,247,250.00 Quantity -------245 15 0 123 15 12 Income -----------330,750.00 52,500.00 .00 2,952,000.00 912,000.00 .00 Figure 41. File QSYSPRT for TRPT Additional Examples For additional examples of creating programs, see: ¹ “Binding to a Program” on page 98, for an example of binding a module and a service program.
Changing a Module or Program Table 8. Sections of the Binder Listing based on DETAIL Parameter Section Name *BASIC *EXTENDED *FULL Command Option Summary X X X Brief Summary Table X X X Extended Summary Table X X Binder Information Listing X X Cross-Reference Listing X Binding Statistics X The information in this listing can help you diagnose problems if the binding was not successful, or give feedback about what the binder encountered in the process.
Changing a Module or Program Note: In the remainder of this section the term 'object' will be used to refer to either an ILE module or ILE program. Using the UPDPGM Command In general, you can update a program by replacing modules as needed. For example, if you add a new procedure to a module, you recompile the module object, and then update the program. You do not have to re-create the program. This is helpful if you are supplying an application to other sites.
Changing a Module or Program level again afterwards to improve the program efficiency as you get the program ready for production. To determine the current optimization level of a program object, use the DSPPGM command. Display 3 of this command indicates the current level. To change the optimization level of a program, use the CHGPGM command. On the Optimize program parameter you can specify one the following values: *FULL, *BASIC, *NONE.
Changing a Module or Program An alternative is to compress the object, using the Compress Object (CPROBJ) command. A compressed object takes up less system storage than an uncompressed one. If the compressed program is called, the part of the object containing the runnable code is automatically decompressed. You can also decompress a compressed object by using the Decompress Object (DCPOBJ) command. For more information on these CL commands, see the CL Reference (Abridged). Chapter 7.
Changing a Module or Program 90 ILE RPG for AS/400 Programmer's Guide
Service Program Overview Chapter 8. Creating a Service Program This chapter provides: ¹ An overview of the service program concept ¹ Strategies for creating service programs ¹ A brief description of the CRTSRVPGM command ¹ An example of a service program Service Program Overview A service program is a bound program (type *SRVPGM) consisting of a set of procedures that can be called by procedures in other bound programs.
Creating a Service Program Using CRTSRVPGM Strategies for Creating Service Programs When creating a service program, you should keep in mind: 1. Whether you intend to update the program at a later date 2. Whether any updates will involve changes to the interface (namely, the imports and exports used). If the interface to a service program changes, then you may have to re-bind any programs bound to the original service program.
Creating a Service Program Using CRTSRVPGM Table 9.
Sample Service Program Sample Service Program The following example shows how to create a service program CVTTOHEX which converts character strings to their hexadecimal equivalent. Two parameters are passed to the service program: 1. a character field (InString) to be converted 2. a character field (HexString) which will contain the 2-byte hexadecimal equivalent The field HexString is used to contain the result of the conversion and also to indicate the length of the string to be converted.
Sample Service Program *=================================================================* * CvtToHex - convert input string to hex output string *=================================================================* H COPYRIGHT('(C) Copyright MyCompany 1995') D/COPY RPGGUIDE/QRPGLE,CVTHEXPR *-----------------------------------------------------------------* * Main entry parameters * 1. Input: string character(n) * 2.
Sample Service Program *-----------------------------------------------------------------* * Use the operational descriptors to determine the lengths of * * the parameters that were passed.
Sample Service Program *=================================================================* * CvtToHex - convert input string to hex output string * * Parameters * 1. Input: string character(n) * 2. Output: hex string character(2 * n) *=================================================================* D CvtToHex PR OPDESC D InString 16383 CONST OPTIONS(*VARSIZE) D HexString 32766 OPTIONS(*VARSIZE) Figure 43.
Sample Service Program Note that a binding directory is not required here because all modules needed to create the service program have been specified with the MODULE parameter. The service program CVTTOHEX will be created in the library MYLIB. It can be debugged using a statement view; this is determined by the default DBGVIEW parameter on the CRTRPGMOD command. No binder listing is produced.
Sample Service Program *----------------------------------------------------------------* * Program to test Service Program CVTTOHEX * * * * 1. Use a 7-character input string * * 2. Convert to a 10-character hex string (only the first five * * input characters will be used because the result is too * * small for the entire input string) * * 3.
Sample Service Program Updating the Service Program Because of the binder language, the service program could be updated and the program CVTHEXPGM would not have to be re-compiled. For example, there are two ways to add a new procedure to CVTTOHEX, depending on whether the new procedure goes into the existing module or into a new one. To add a new procedure to an existing module, you would: 1. Add the new procedure to the existing module. 2. Recompile the changed module. 3.
Sample Service Program Create Program 5769SS1 V4R4M0 990521 23:24:00 Program . . . . . . . . . . . Library . . . . . . . . . . Program entry procedure module Library . . . . . . . . . . Activation group . . . . . . . Creation options . . . . . . . Listing detail . . . . . . . . Allow Update . . . . . . . . . User profile . . . . . . . . . Replace existing program . . . Authority . . . . . . . . . . Target release . . . . . . . . Allow reinitialization . . . . Text . . . . . . . . . . . . .
Sample Service Program 102 ILE RPG for AS/400 Programmer's Guide
Running a Program Using the CL CALL Command Chapter 9. Running a Program This chapter shows you how to: ¹ Run a program and pass parameters using the CL CALL command ¹ Run a program from a menu-driven application ¹ Run a program using a user-created command ¹ Manage activation groups ¹ Manage run-time storage. In addition, you can run a program using: ¹ The Programmer Menu. The CL Programming, SC41-5721-02 manual contains information on this menu.
Running a Program Using the CL CALL Command Passing Parameters using the CL CALL Command You use the PARM option of the CL CALL command to pass parameters to the ILE program when you run it. CALL PGM(program-name) PARM(parameter-1 parameter-2 ... parameter-n) You can also type the parameters without specifying any keywords: CALL library/program-name (parameter-1 parameter-2 ...
Running a Program Using the CL CALL Command *===============================================================* * PROGRAM NAME: EMPRPT2 * * RELATED FILES: EMPMST (PHYSICAL FILE) * * PRINT (PRINTER FILE) * * DESCRIPTION: This program prints employee information * * stored in the file EMPMST if the password * * entered is correct. * * Run the program by typing "CALL library name/ * * EMPRPT2 (PSWORD)" on the command line, where * * PSWORD is the password for this program.
Running a Program From a Menu-Driven Application A***************************************************************** A* DESCRIPTION: This is the DDS for the physical file EMPMST. * A* It contains one record format called EMPREC. * A* This file contains one record for each employee * A* of the company.
Running a Program From a Menu-Driven Application A* Free Form Menu: PAYROL A* A DSPSIZ(24 80 *DS3 A 27 132 *DS4) A CHGINPDFT A INDARA A PRINT(*LIBL/QSYSPRT) A R PAYROL A DSPMOD(*DS3) A LOCK A SLNO(01) A CLRL(*ALL) A ALWROL A CF03 A HELP A HOME A HLPRTN A 1 34'PAYROLL DEPARTMENT MENU' A DSPATR(HI) A 3 2'Select one of the following:' A COLOR(BLU) A 5 7'1.' A 6 7'2.' A 7 7'3.' A* CMDPROMPT Do not delete this DDS spec.
Replying to Run-Time Inquiry Messages Running a Program Using a User-Created Command You can create a command to run a program by using a command definition. A command definition is an object (type *CMD) that contains the definition of a command (including the command name, parameter descriptions, and validitychecking information), and identifies the program that performs the function requested by the command.
Managing Activation Groups where sequence-no is a number from 1-9999, which reflects where in the list the entry is being added, and message-id is the message number you want to add. Repeat this command for each message you want to add. Use the Change Job (CHGJOB) command (or other CL job command) to indicate that your job uses the reply list for inquiry messages. To do this, you should specify *SYSRPYL for the Inquiry Message Reply (INQMSGRPY) attribute.
Managing Activation Groups programs activated within one activation group are developed as one cooperative application. You identify the activation group that your ILE program will run in at the time of program creation. The activation group is determined by the value specified on the ACTGRP parameter when the program object was created. (OPM programs always run in the default activation group; you cannot change their activation group specification.
Managing Activation Groups If you create an ILE RPG program with ACTGRP(*NEW), you can then call the program as many times as you want without returning from earlier calls. With each call, there is a new copy of the program. Each new copy will have its own data, open its files, etc.. However, you must ensure that there is some way to end the calls to 'itself'; otherwise you will just keep creating new activation groups and the programs will never return.
Managing Activation Groups Deleting an Activation Group When an activation group is deleted, its resources are reclaimed. The resources include static storage and open files. A *NEW activation group is deleted when the program it is associated with returns to its caller. Named activation groups (such as QILE) are persistent activation groups in that they are not deleted unless explicitly deleted or unless the job ends.
Managing Dynamically-Allocated Storage For more information on the RCLRSC command, refer to the CL Reference (Abridged). For more information on the RCLRSC and activation groups, refer to ILE Concepts. Managing Dynamically-Allocated Storage ILE allows you to directly manage run-time storage from your program by managing heaps. A heap is an area of storage used for allocations of dynamic storage.
Managing Dynamically-Allocated Storage Note: Although the ALLOC operation code works only with the default heap, the REALLOC and DEALLOC operation codes work with both the default heap and user-created heaps. Figure 52 shows an example of how the memory management operation codes can be used to build a linked list of names.
Managing Dynamically-Allocated Storage *-----------------------------------------------------------------* * S U B P R O C E D U R E S * *-----------------------------------------------------------------* *-----------------------------------------------------------------* * AddName - add a name to the end of the list * *-----------------------------------------------------------------* P AddName B D AddName pi D name 40A *-----------------------------------------------------------------* * Allocate a new e
Managing Dynamically-Allocated Storage *-----------------------------------------------------------------* * * * After: Now the names name@, name_len and next@ refer * * to storage in the new element * * * * .-------------. .--------------. * * | | .------>| | * * | *--->abc | | name * | * * | 3 | | | name_len | * * | *----------' | next * | * * | | | | * * '-------------' '--------------' * * * * Now set the values of the new element.
Managing Dynamically-Allocated Storage *-----------------------------------------------------------------* * Display - display the list * *-----------------------------------------------------------------* P Display B D saveElem@ S * D dspName S 40A *-----------------------------------------------------------------* * Save the current elem pointer so the list can be restored after * * being displayed and set the list pointer to the beginning of * * the list.
Managing Dynamically-Allocated Storage *-----------------------------------------------------------------* * Free - release the storage used by the list * *-----------------------------------------------------------------* P Free B D prv@ S * *-----------------------------------------------------------------* * Loop through the elements of the list until the next pointer is * * *NULL, starting from the first real element in the list * *-----------------------------------------------------------------* C EV
Managing Dynamically-Allocated Storage *-----------------------------------------------------------------* * Heap Storage Misuse * *-----------------------------------------------------------------* D Fld1 S 25A BASED(Ptr1) D Fld2 S 5A BASED(Ptr2) D Ptr1 S * D Ptr2 S * .... C ALLOC 25 Ptr1 C DEALLOC Ptr1 *-----------------------------------------------------------------* * After this point, Fld1 should not be accessed since the * basing pointer ptr1 no longer points to allocated storage.
Managing Dynamically-Allocated Storage procedures in the module DYNARRAY dynamically allocate storage for a practically unbounded packed array. The procedures in the module perform the following actions on the array: ¹ Initialize the array ¹ Add an element to the array ¹ Return the value of an element ¹ Release the storage for the array.
Managing Dynamically-Allocated Storage *================================================================= * DYNARRAY : Handle a (practically) unbounded run-time * Packed(15,0) array. This module contains * procedures to allocate the array, return or set * an array value and deallocate the array. *================================================================= H NOMAIN *----------------------------------------------------------------* Prototypes for the procedures in this module.
Managing Dynamically-Allocated Storage *----------------------------------------------------------------* Interface to the CEEDSHP API (Discard Heap). * 1) HeapId = Id of the heap. * 2) *OMIT = The feedback parameter. Specifying *OMIT here * means that we will receive an exception from * the API if it cannot satisfy our request. * Since we do not monitor for it, the calling * procedure will receive the exception.
Managing Dynamically-Allocated Storage *================================================================= * DYNA_INIT: Initialize the array. * * Function: Create the heap and allocate an initial amount of * storage for the run time array. *================================================================= P DYNA_INIT B EXPORT *----------------------------------------------------------------* Local variables.
Managing Dynamically-Allocated Storage *================================================================= * DYNA_SET: Set an array element. * * Function: Ensure the array is big enough for this element, * and set the element to the provided value. *================================================================= P DYNA_SET B EXPORT *----------------------------------------------------------------* Input parameters for this procedure.
Managing Dynamically-Allocated Storage * * * * * * C C C C C Calculate the new number of elements. If the index is greater than the current number of elements in the array plus the new allocation, then allocate up to the index, otherwise, add a new allocation amount onto the array. IF Z-ADD ELSE ADD ENDIF Index > NumElems + SUBSALLOC Index NumElems SUBSALLOC NumElems * * Calculate the new size of the array * C EVAL Size = NumElems * %SIZE(DynArr) * * Reallocate the storage.
Managing Dynamically-Allocated Storage The logic of the subprocedures is as follows: 1. DYNA_INIT creates the heap using the ILE bindable API CEECRHP (Create Heap), storing the heap Id in a global variable HeapId. It allocates heap storage based on initial value of the array (in this case 100) by calling the ILE bindable API CEEGTST (Get Heap Storage). 2. DYNA_TERM destroys the heap using the ILE bindable API CEEDSHP (Discard Heap). 3. DYNA_SET sets the value of an element in the array.
Program/Procedure Call Overview Chapter 10. Calling Programs and Procedures In ILE, it is possible to call either a program or procedure. Furthermore, ILE RPG provides the ability to call prototyped or non-prototyped programs and procedures. (A prototype is an external definition of the call interface that allows the compiler to check the interface at compile time.) The recommended way to call a program or procedure is to use a prototyped call.
Program/Procedure Call Overview ¹ Recursion ¹ Parameter passing considerations Calling Programs You can call OPM or ILE programs by using program calls. A program call is a call that is made to a program object (*PGM). The called program's name is resolved to an address at run time, just before the calling program passes control to the called program for the first time. For this reason, program calls are often referred to as dynamic calls.
Program/Procedure Call Overview ples of using procedure pointers, see the section on the procedure pointer data type in ILE RPG for AS/400 Reference. You use the CALLP or both the CALLB and PARM operations to make a procedure call. You can also call a prototyped procedure with an expression if the procedure returns a value. If you use the CALLB and PARM operations, then the compiler cannot perform type checking on the parameters, which may result in run-time errors.
Program/Procedure Call Overview Recursive Calls Recursive calls are only allowed for subprocedures. A recursive call is one where procedure A calls itself or calls procedure B which then calls procedure A again. Each recursive call causes a new invocation of the procedure to be placed on the call stack. The new invocation has new storage for all data items in automatic storage, and that storage is unavailable to other invocations because it is local.
Program/Procedure Call Overview PGM X PRC_A PRC_B PRC_C PRC_A Recursive Call Call Stack (bottom entry is most recent) Figure 60. Recursive Call Stack To Be Avoided So while subprocedures can be called recursively, if you are not aware that recursion is occurring, you may exhaust system resources. Attention! Unconditional recursive calls can lead to infinite recursion which leads to excessive use of system resources. Infinite recursion can be avoided with proper programming.
Program/Procedure Call Overview Sometimes you may not be sure of the exact format of the data that is being passed to you. In this case you may request that operational descriptor be passed to provide additional information regarding the format of the passed parameters. ¹ Number of parameters In general, you should pass the same number of parameters as expected by the called program or procedure.
Using a Prototyped Call Table 10.
Using a Prototyped Call To call a prototyped program or procedure follow these general steps: 1. Include the prototype of the program or procedure to be called in the definition specifications. 2. Enter the prototype name of the program or procedure in the extended Factor-2 field, followed by the parameters if any, within parentheses. Separate the parameters with a colon (:). Factor 1 must be blank.
Passing Prototyped Parameters Examples of Free-Form Call For examples of using the CALLP operation, see: ¹ Figure 22 on page 41 ¹ Figure 43 on page 97 ¹ Figure 105 on page 212 ¹ Figure 70 on page 144 ¹ Figure 117 on page 242 For examples of calling by using an expression, see: ¹ Figure 4 on page 10 ¹ Figure 19 on page 39 ¹ Figure 38 on page 79 ¹ Figure 105 on page 212 Passing Prototyped Parameters When you pass prototyped parameters: ¹ The compiler verifies, when compiling both the caller and the callee,
Passing Prototyped Parameters Passing by Value With a prototyped procedure, you can pass a parameter by value instead of by reference. When a parameter is passed by value, the compiler passes the actual value to the called procedure. Note: OS/400 program calls require that parameters be passed by reference. Consequently, you cannot pass a parameter by value to a program. Passing by value allows you to: ¹ Pass literals and expressions as parameters.
Passing Prototyped Parameters *------------------------------------------------------------* The procedure returns a value of a 10-digit integer value. * The 3 parameters are all 5-digit integers passed by value. *------------------------------------------------------------D MyFunc PR 10I 0 EXTPROC('DO_CALC') D 5I 0 VALUE D 5I 0 VALUE D 5I 0 VALUE .... Figure 63.
Passing Prototyped Parameters To pass a parameter by read-only reference, specify the keyword CONST on the definition specification of the parameter definition in the prototype. Figure 65 on page 138 shows an example of a prototype definition for the ILE CEE API CEETSTA (Test for omitted argument). | | | | | | | | | | | | | | | | *-----------------------------------------------------------------* CEETSTA (Test for omitted argument) -- ILE CEE API * 1. Presence flag Output Binary(4) * 2.
Passing Prototyped Parameters are then built by the calling procedure and passed as hidden parameters to the called procedure. Operational descriptors will not be built for omitted parameters. You can retrieve information from an operational descriptor using the ILE bindable APIs Retrieve Operational Descriptor Information (CEEDOD) and Get Descriptive Information About a String Argument (CEESGI). Note that operational descriptors are only allowed for bound calls.
Passing Prototyped Parameters Passing *OMIT You can pass *OMIT for a prototyped parameter if the called procedure is aware that *OMIT might be passed. In other words, you can pass *OMIT if the keyword OPTIONS(*OMIT) is specified on the corresponding parameter definition in the prototype. When *OMIT is specified, the compiler will generate the necessary code to indicate to the called procedure that the parameter has been omitted. Note: *OMIT can only be specified for parameters passed by reference.
Passing Prototyped Parameters Checking for the Number of Passed Parameters At times it may be necessary to check for the number of parameters that are passed on a call. Depending on how the procedure has been written, this number may allow you to avoid references to parameters that are not passed. For example, suppose that you want to write a procedure which will sometimes be passed three parameters and sometimes four parameters. This might arise when a new parameter is required.
Passing Prototyped Parameters 2. Correct the street number for printing using the subroutine GetStreet#. 3. Concatenate the complete address. 4. Return. *=================================================================* * FMTADDR - format an address * * Interface parameters * 1. Address character(70) * 2. Street number packed(5,0) * 3. Street name character(20) * 4. City character(15) (some callers do not pass) * 5.
Passing Prototyped Parameters *=================================================================* * SUBROUTINE: GetStreet# * Get the character form of the street number, left-adjusted * * and padded on the right with blanks. * *=================================================================* C GetStreet# BEGSR C MOVEL Street# CStreet# 10 *-----------------------------------------------------------------* * Find the first non-zero.
Passing Prototyped Parameters *=================================================================* * PRTADDR - Print an address * Calls FmtAddr to format the address *=================================================================* FQSYSPRT O F 80 PRINTER *-----------------------------------------------------------------* * Prototype for FmtAddr *-----------------------------------------------------------------* DFmtAddr PR D addr 70 D strno 5 0 D st 20 D cty 15 OPTIONS(*NOPASS) D prov 15 OPTIONS(*NOPASS)
Passing Prototyped Parameters *-----------------------------------------------------------------* * 'Program 2'- Use of FMTADDR before province parameter was added.* *-----------------------------------------------------------------* C DO 2 X 5 0 C CALLP FMTADDR (Address:Street#2(X): C StreetNam2(X):City2(X)) C EXCEPT C ENDDO *-----------------------------------------------------------------* * 'Program 3' - Use of FMTADDR after province parameter was added.
Passing Prototyped Parameters Figure 71 on page 146 shows the prototype for QCMDEXC, where the first parameter is defined with OPTIONS(*VARSIZE) meaning that you can pass parameters of different lengths for the first parameter. Note that OPTIONS *VARSIZE can only be specified for a character field, a graphic field, or an array. *------------------------------------------------------------* This prototype for QCMDEXC defines three parameters.
Table 11.
Using the Fixed-Form Call Operations | | | For ILE C, declare the returned value as a struct with a subfield of type char. (The RPG return value can also be declared as a 3-digit unsigned integer, since that is the way that ILE C defines a 1-byte character.) | | | | | | | | | | | typedef struct { char c; } RPGCHAR; RPGCHAR RPGPROC(int i); void fn() { RPGCHAR ret; ret = RPGPROC(3); /* The returned character is ret.c */ } | 2.
Using the Fixed-Form Call Operations 2. Optionally code an error indicator (positions 73 and 74) or an LR indicator (positions 75 and 76) or both. When a called object ends in error the error indicator, if specified, is set on. Similarly, if the called object returns with LR on, the LR indicator, if specified, is set on. 3. To pass parameters to the called object, either specify a PLIST in the Result field of the call operation or follow the call operation immediately by PARM operations.
Using the Fixed-Form Call Operations For more information on operational descriptors, see “Using Operational Descriptors” on page 138. ¹ There are further restrictions that apply when using the CALL or CALLB operation codes. For a detailed description of these restrictions, see the ILE RPG for AS/400 Reference. Examples of CALL and CALLB For examples of using the CALL operation, see: ¹ “Sample Source for Debug Examples” on page 211, for example of calling an RPG program.
Using the Fixed-Form Call Operations If insufficient parameters are specified when calling a procedure, an error occurs when an unresolved parameter is used by the called procedure. To avoid the error, you can either: ¹ Check %PARMS to determine the number of parameters passed. For an example using %PARMS, see “Checking for the Number of Passed Parameters” on page 141. ¹ Specify *OMIT in the result field of the PARM operations of the unpassed parameters.
Returning from a Called Program or Procedure Multiple PLISTs can appear in a procedure. However, only one *ENTRY PLIST can be specified, and only in the main procedure. For examples of the PLIST operation see Figure 47 on page 105 and Figure 116 on page 239. Returning from a Called Program or Procedure When a program or procedure returns, its call stack entry is removed from the call stack. (If it is a program, the program entry procedure is removed as well.
Returning from a Called Program or Procedure ¹ The RETURN operation (with a blank factor 2) is processed, the H1 through H9 indicators are not on, and the LR indicator is on. ¹ The RT indicator is on, the H1 through H9 indicators are not on, and the LR indicator is on. When a main procedure ends normally, the following occurs: ¹ The Factor-2-to-Result-field move of a *ENTRY PARM operation is performed.
Returning from a Called Program or Procedure ¹ All files that are open are closed. ¹ Any data areas locked by the procedure are unlocked. ¹ If the main procedure ended because of a cancel reply to an inquiry message, then it was a function check that caused the abnormal end. In this case, the function check is percolated to the caller. If it ended because of an error subroutine ending with '*CANCL', then escape message RNX9001 is issued directly to the caller.
Using Bindable APIs A subprocedure ends abnormally and control returns to the calling procedure when an unhandled exception occurs. Again, no further actions occur until the main procedure ends. If the main procedure is never called (and therefore cannot end) then any files, data areas, etcetera, will not be closed. If you think this might arise for a subprocedure, you should code a termination procedure that gets called when the subprocedure ends.
Calling a Graphics Routine You access ILE bindable APIs using the same call mechanisms used by ILE RPG to call procedures, that is, the CALLP operation or the CALLB operation. If the API returns a value and you want to use it, call the API in an expression. For the information required to define a prototype for an API see the description of the API in the System API Reference. Figure 72 shows a sample 'call' to a bindable API. D CEExxxx D parm1 D ... C PR EXTPROC('CEExxxx') ...
Multithreading Considerations ¹ The name of the graphics routine you want to run. ¹ The appropriate parameters for the specified graphics routine. These parameters must be of the data type required by the graphics routine and cannot have a float format. The procedure that processes the CALL does not implicitly start or end OS/400 graphics routines. For more information on OS/400 Graphics, graphics routines and parameters, see the GDDM Programming Guide manual and the GDDM Reference.
Multithreading Considerations | | | | | | | | | | | THREAD(*SERIALIZE) will protect most of your variables and all your internal control structures from being accessed improperly by multiple threads. The thread safe module will be locked when a procedure in the module is entered and unlocked when no procedure in the module is still running. This serialized access, ensures that only one thread is active in any one module, within an activation group, at any one time.
Multithreading Considerations | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | *----------------------------------------------------------------------------------* .---------------. * | | * | some storage |<---------------- pointer to shared storage * | | (called MyPtr in module A) * '---------------' (saved as a static variable in module B) * Module A * Global variables in Module A D MyPtr S * D SomeStorage S 10A based(MyPtr) C eval SomeStorage = 'Init value' C callp ProcB(MyPtr) .
Multithreading Considerations | | | complete their calls, since each module will be locked by the thread in the other module. This type of problem can occur even with serialization of calls to a module and is referred to as deadlock. | Figure 74. Deadlock Example | | This example shows that you cannot access more than one procedure in the same module at the same time using ILE RPG synchronization techniques.
Debugging and Exception Handling This section describes how to: ¹ Debug an Integrated Language Environment application by using the Integrated Language Environment source debugger ¹ Write programs that handle exceptions ¹ Obtain a dump Copyright IBM Corp.
162 ILE RPG for AS/400 Programmer's Guide
The ILE Source Debugger Chapter 11. Debugging Programs Debugging allows you to detect, diagnose, and eliminate run-time errors in a program. You can debug ILE and OPM programs using the ILE source debugger.
The ILE Source Debugger ¹ Equate a shorthand name with a field, expression, or debug command Before you can use the source debugger, you must select a debug view when you create a module object or program object using CRTRPGMOD or CRTBNDRPG. After starting the debugger you can set breakpoints and then call the program. When a program stops because of a breakpoint or a step command, the pertinent module object's view is shown on the display at the point where the program stopped.
The ILE Source Debugger STEP Allows you to run one or more statements of the procedure being debugged. | | TBREAK Permits you to enter either an unconditional or conditional breakpoint in the current thread at a position in the program being tested. | | THREAD Allows you to display the Work with Debugged Threads display or change the current thread. WATCH Allows you to request a breakpoint when the contents of a specified storage location is changed from its current value.
Preparing a Program for Debugging 7. From the help panel which appears, you can select a number of topics pertaining to RPG, such as displaying variables, displaying table, and displaying multiple-occurrence data structures. Preparing a Program for Debugging A program or module must have debug data available if you are to debug it. Since debug data is created during compilation, you specify whether a module is to contain debug data when you create it using CRTBNDRPG or CRTRPGMOD.
Preparing a Program for Debugging Table 13.
Preparing a Program for Debugging Creating a COPY Source View A COPY source view contains text from the root source member, as well as the text of all /COPY members expanded into the text of the source. When you use the COPY view, you can debug the root source member of the program using the root source view and the /COPY members of the program using the COPY source view. The view of the root source member generated by DBGVIEW(*COPY) is the same view generated by DBGVIEW(*SOURCE).
Preparing a Program for Debugging members into the module object. There is no dependency on the source members upon which it is based, once the listing view is created.
Starting the ILE Source Debugger If the default values for either create command have been changed, you must explicitly specify DBGVIEW(*STMT) and OUTPUT(*PRINT). Starting the ILE Source Debugger Once you have created the debug view (statement, source, COPY, or listing), you can begin debugging your application. To start the ILE source debugger, use the Start Debug (STRDBG) command. Once the debugger is started, it remains active until you enter the End Debug (ENDDBG) command.
Starting the ILE Source Debugger STRDBG Example To start a debug session for the sample debug program DEBUGEX and a called OPM program RPGPGM, type: STRDBG PGM(MYLIB/DEBUGEX MYLIB/RPGPGM) OPMSRC(*YES) The Display Module Source display appears as shown in Figure 75. DEBUGEX consists of two modules, an RPG module DBGEX and a C module cproc. See “Sample Source for Debug Examples” on page 211 for the source for DBGEX, cproc, and RPGPGM.
Adding/Removing Programs from a Debug Session Changing the debug options using the SET debug command affects the value for the corresponding parameter, if any, specified on the STRDBG command. You can also use the Change Debug (CHGDBG) command to set debug options. However, the OPMSRC option can not be changed by the CHGDBG command. OPMSRC can only be changed by the debug SET command.
Adding/Removing Programs from a Debug Session Example of Adding a Service Program to a Debug Session In this example you add the service program CVTTOHEX to the debug session which already previously started. (See “Sample Service Program” on page 94 for a discussion of the service program). 1. If the current display is not the Display Module Source display, type: DSPMODSRC The Display Module Source display appears. 2.
Viewing the Program Source Work with Module List System: Type options, press enter.
Viewing the Program Source Viewing a Different Module To change the module object that is shown on the Display Module Source display, use option 5 (Display module source) on the Work with Module List display. You access the Work with Module List display from the Display Module Source display by pressing F14 (Work with Module List). If you use this option with an ILE program object, the entry module with a root source, COPY, or listing view is shown (if it exists).
Viewing the Program Source Program: 1 2 3 4 5 6 7 8 9 10 11 12 13 Display Module Source DEBUGEX Library: MYLIB #include #include #include extern char EXPORTFLD[6]; Module: CPROC char *c_proc(unsigned int size, char *inzval) { char *ptr; ptr = malloc(size); memset(ptr, *inzval, size ); printf("import string: %6s.\n",EXPORTFLD); return(ptr); } Bottom Debug . . .
Setting and Removing Breakpoints Display Module Source .............................................................................. : Select View : : : : Current View . . . : ILE RPG Copy View : : : : Type option, press Enter. : : 1=Select : : : : Opt View : : 1 ILE RPG Listing View : : ILE RPG Source View : : ILE RPG Copy View : : : : Bottom : : F12=Cancel : : : :............................................................................: More... Debug . . .
Setting and Removing Breakpoints is shown with the source positioned at the line where the breakpoint occurred. This line is highlighted. At this point, you can evaluate fields, set more breakpoints, and run any of the debug commands. You should know the following characteristics about breakpoints before using them: ¹ When a breakpoint is set on a statement, the breakpoint occurs before that statement is processed.
Setting and Removing Breakpoints display. A list of options appear which allow you to set or remove breakpoints. If you select 4 (Clear), a job breakpoint is removed from the line. An alternate method of setting and removing unconditional job breakpoints is to use the BREAK and CLEAR debug commands. To set an unconditional job breakpoint using the BREAK debug command, type: BREAK line-number on the debug command line.
Setting and Removing Breakpoints Program: 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 Display Module Source DEBUGEX Library: MYLIB Module: DBGEX *--------------------------------------------------------------* Move 'a's to the data structure DS2. After the move, the * first occurrence of DS2 contains 10 character 'a's.
Setting and Removing Breakpoints The current thread is the thread that is currently being debugged. Debug commands are issued to this thread. When a debug stop occurs, such as a breakpoint, the current thread is set to the thread where the debug stop happened. The debug THREAD command and the 'Work with Debugged Threads' display can be used to change the current thread. To remove an unconditional thread breakpoint use the CLEAR debug command.
Setting and Removing Breakpoints is encountered. The relational operators supported for conditional breakpoints are noted at the beginning of this section. In non-numeric conditional breakpoint expressions, the shorter expression is implicitly padded with blanks before the comparison is made. This implicit padding occurs before any National Language Sort Sequence (NLSS) translation. See “National Language Sort Sequence (NLSS)” on page 183 for more information on NLSS.
Setting and Removing Breakpoints 5. After the breakpoint is set, press F12 (Cancel) to leave the Work with Module Breakpoints display. Press F3 (End Program) to leave the ILE source debugger. Your breakpoint is not removed. 6. Call the program. When a breakpoint is reached, the program stops, and the Display Module Source display is shown again. At this point you can step through the program or resume processing.
Setting and Removing Breakpoints This corresponds to the RPG graphic data type. NLSS applies only to non-numeric conditional breakpoint expressions of type Char-8. See Table 14 on page 185 for the possible combinations of non-numeric conditional breakpoint expressions. The sort sequence table used by the source debugger for expressions of type Char-8 is the sort sequence table specified on the SRTSEQ parameter for the CRTRPGMOD or CRTBNDRPG commands.
Setting and Removing Breakpoints Table 14.
Setting and Removing Breakpoints | | | | | | Line <--------------------- Source Specifications ----------------------------------------------><---- Comments ----> Src Seq Number ....1....+....2....+<-------- 26 - 35 -------->....4....+....5....+....6....+....7....+....8....+....9....+...10 Id Number S o u r c e L i s t i n g 1 C MOVE '123' BI_FLD1 000100 2 C SETON LR---000200 * * * * * E N D O F S O U R C E * * * * * | Figure 84.
Setting and Removing Breakpoints | | | | | | | | | | | | | | | | | | | | | | | | | | | Figure 87.
Setting and Removing Watch Conditions To remove a conditional thread breakpoint using the Work with Module Breakpoints display: 1. Type 4 (Clear) in the Opt field next to the breakpoint you want to remove. 2. Press Enter. Using the TBREAK or CLEAR Debug Commands You use the same syntax for the TBREAK debug command as you would for the BREAK debug command.
Setting and Removing Watch Conditions Characteristics of Watches You should know the following characteristics about watches before working with them: ¹ Watches are monitored system-wide, with a maximum number of 256 watches that can be active simultaneously. This number includes watches set by the system. Depending on overall system use, you may be limited in the number of watch conditions you can set at a given time.
Setting and Removing Watch Conditions Setting Watch Conditions Before you can set a watch condition, your program must be stopped under debug, and the expression or variable you want to watch must be in scope: ¹ To watch a global variable, you must ensure that the program in which the variable is defined is active before setting the watch condition. ¹ To watch a local variable, you must step into the procedure in which the variable is defined before setting the watch condition.
Setting and Removing Watch Conditions Work with Watch .......................................................... : Display Watch : : : : Watch Number ....: 1 : : Address .........: 080090506F027004 : : Length ..........: 4 : : Number of Hits ..: 0 : : : : Scope when watch was set: : : Program/Library/Type: PAYROLL ABC *PGM : : : : Module...: PAYROLL : : Procedure: PAYROLL : : Variable.: SALARY : : : : F12=Cancel : : : ..........................................................
Setting and Removing Watch Conditions Displaying Active Watches To display a system-wide list of active watches and show which job set them, type: DSPDBGWCH on a debug command line. This command brings up the Display Debug Watches display shown below.
Example of Setting a Watch Condition Example of Setting a Watch Condition In this example, you watch a variable SALARY in program MYLIB/PAYROLL. To set the watch condition, type: WATCH SALARY on a debug line, accepting the default value for the watch-length. If the value of the variable SALARY changes subsequently, the application stops and the Display Module Source display is shown, as illustrated in Figure 91.
Stepping Through the Program Object Display Module Source (Source not available) F3=End program F12=Resume F14=Work with module list F21=Command entry F22=Step into F23=Display output Watch number 1 at instruction 18, variable: SALARY F18=Work with watch Figure 92.
Stepping Through the Program Object on the debug command line, the next five statements of your program object are run, then the program object is stopped again and the Display Module Source display is shown. When a call statement to another program or procedure is encountered in a debug session, you can: ¹ Step over the call statement, or ¹ Step into the call statement.
Stepping Through the Program Object Stepping Into Call Statements You can step into a call statement by using: ¹ F22 (Step into) on the Display Module Source display ¹ The STEP INTO debug command You can use F22 (Step into) on the Display Module Source display to step into a called program or procedure in a debug session.
Stepping Through the Program Object Example of Stepping Into an OPM Program Using F22 In this example, you use the F22 (Step Into) to step into the OPM program RPGPGM from the program DEBUGEX. 1. Ensure that the Display Module Source display shows the source for DBGEX. 2. To set an unconditional breakpoint at line 102, which is the last runnable statement before the CALL operation, type Break 102 and press Enter. 3. Press F3 (End program) to leave the Display Module Source display. 4. Call the program.
Stepping Through the Program Object Program: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 Display Module Source RPGPGM Library: MYLIB *=============================================================== * RPGPGM - Program called by DEBUGEX to illustrate the STEP * functions of the ILE source debugger. * * This program receives a parameter InputParm from DEBUGEX, * displays it, then returns.
Stepping Through the Program Object Display Module Source Library: MYLIB Program: DEBUGEX Module: DBGEX 141 142 *============================================================= 143 * Define the subprocedure Switch. 144 *============================================================= 145 P Switch B 146 D Switch PI 147 D Parm 1A 148 *--------------------------------------------------------149 * Define a local variable for debugging purposes.
Stepping Through the Program Object on the debug command line. The variable field-name is the name of the field, data structure, or array that you want to display or evaluate. The value is shown on the message line if the EVAL debug command is entered from the Display Module Source display and the value can be shown on a single line. Otherwise, it is shown on the Evaluate Expression display. Figure 96 shows an example of using the EVAL debug command to display the contents of a subfield LastName.
Stepping Through the Program Object | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Scalar Fields RPG Definition > EVAL String 6A INZ('ABCDEF') STRING = 'ABCDEF' > EVAL Packed1D0 5P 2 INZ(-93.4) PACKED1D0 = -093.40 > EVAL ZonedD3D2 3S 2 INZ(-3.21) ZONEDD3D2 = -3.21 > EVAL Bin4D3 4B 3 INZ(-4.321) BIN4D3 = -4.
Stepping Through the Program Object Displaying the Contents of an Array Specifying an array name with EVAL will display the full array. To display one element of an array, specify the index of the element you wish to display in parentheses. To display a range of elements use the following range notation: EVAL field-name (n...m) The variable field-name is the name of the array, the variable n is a number representing the start of the range, and the variable m is a number representing the end of the range.
Stepping Through the Program Object 3 DIM(3) CTDATA Compile-time data: > EVAL TableA TABLEA = 'aaa' ** Show value at current index > EVAL TableA(1) TABLEA(1) = 'aaa' > EVAL TableA(2) TABLEA(2) = 'bbb' > EVAL _QRNU_TABI_TableA _QRNU_TABI_TABLEA = 1 > EVAL TableA(1..
Stepping Through the Program Object ** Note that you can enter the data structure name or a subfield name. ** > EVAL DS3 TITLE OF DS3 = 'Mr. ' 5A INZ('Mr. ') LASTNAME OF DS3 = 'Jones ' 10A INZ('Jones ') FIRSTNAME OF DS3 = 'Fred ' 10A INZ('Fred ') > EVAL LastName LASTNAME = 'Jones ' > EVAL DS1 OCCURS(3) FLD1 OF DS1 = 'ABCDE' 5A INZ('ABCDE') FLD1A OF DS1(1) = 'A' 1A DIM(5) OVERLAY(Fld1) FLD1A OF DS1(2) = 'B' 5B 2 INZ(123.45) FLD1A OF DS1(3) = 'C' FLD1A OF DS1(4) = 'D' FLD1A OF DS1(5) = 'E' FLD2 OF DS1 = 123.
Stepping Through the Program Object > EVAL IN02 Identifier does not exist. > EVAL *IN02 *IN02 = '1' > EVAL *IN(02) *IN(02) = '1' > EVAL *INLR *INLR = '0' > EVAL *IN(LR) Identifier does not exist. > EVAL *IN(1..6) ** To display a range of indicators ** *IN(1) = '0' *IN(2) = '1' *IN(3) = '0' *IN(4) = '1' *IN(5) = '0' *IN(6) = '1' Figure 101. Sample EVAL commands for an Array Displaying Fields as Hexadecimal Values You can use the EVAL debug command to display the value of fields in hexadecimal format.
Stepping Through the Program Object | | | | | Displaying UCS-2 Data | | | | | | | Displaying Variable-Length Fields The value displayed for UCS-2 fields has been translated into readable characters. For example, if a UCS-2 field has been set to %UCS2('abcde'), then the value displayed for that field would be 'abcde'. You can display UCS-2 data in any field by using the :u suffix for EVAL. When you use EVAL fldname for a variable length field, only the data portion of the field is shown.
Stepping Through the Program Object The %SUBSTR built-in function allows you to substring a string variable. The first parameter must be a string identifier, the second parameter is the starting position, and the third parameter is the number of single-byte or double-byte characters. In addition. the second and third parameters must be positive, integer literals. Parameters are delimited by one or more spaces.
Changing the Value of Fields Use the %VARS debug built-in function when the variable name conflicts with any of the debug command names. For example, EVAL %VAR(EVAL) can be used to evaluate a variable named EVAL, whereas EVAL EVAL would be a syntax error. Changing the Value of Fields You can change the value of fields by using the EVAL command with an assignment operator (=). The scope of the fields used in the EVAL command is defined by using the QUAL command.
Changing the Value of Fields When assigning literals to fields, the normal RPG rules apply: ¹ Character literals should be in quotes. ¹ Graphic literals should be specified as G'oDDDDi', where o is shift-out and i is shift-in. ¹ Hexadecimal literals should be in quotes, preceded by an 'x'. ¹ Numeric literals should not be in quotes. Note: You cannot assign a figurative constant to a field using the EVAL debug command. Figurative constants are not supported by the EVAL debug command.
Equating a Name with a Field, Expression, or Command Displaying Attributes of a Field You can display the attributes of a field using the Attribute (ATTR) debug command. The attributes are the size (in bytes) and type of the variable as recorded in the debug symbol table. Figure 104 shows some examples of displaying field attributes based on the source in Figure 105 on page 212. Additional examples are also provided in the source debugger online help.
Sample Source for Debug Examples EQUATE shorthand-name definition on the debug command line. shorthand-name is the name that you want to equate with a field, expression, or debug command, and definition is the field, expression, or debug command that you are equating with the name. For example, to define a shorthand name called DC which displays the contents of a field called COUNTER, type: EQUATE DC EVAL COUNTER on the debug command line.
Sample Source for Debug Examples CRTRPGMOD MODULE(MYLIB/DBGEX) SRCFILE(MYLIB/QRPGLESRC) DBGVIEW(*ALL) TEXT('Main module for Sample Debug Program') DBGVIEW(*ALL) was chosen in order to show the different views available. 2. To create the C module using the source in Figure 107 on page 216, type: CRTCMOD MODULE(MYLIB/cproc) SRCFILE(MYLIB/QCLESRC) DBGVIEW(*SOURCE) TEXT('C procedure for Sample Debug Program') 3.
Sample Source for Debug Examples * D D D D D Pointers NullPtr BasePtr ProcPtr BaseString BaseOnNull S S S S S * * * 6A 10A INZ(*NULL) INZ(%ADDR(String)) ProcPtr INZ(%PADDR('c_proc')) BASED(BasePtr) BASED(NullPtr) * D Spcptr S * D SpcSiz C 8 * Date, Time, Timestamp D BigDate S D INZ(D'9999-12-31') D BigTime S T INZ(T'12.00.00') D BigTstamp S Z INZ(Z'9999-12-31-12.00.00.000000') * Array D Arry S 3S 2 DIM(2) INZ(1.
Sample Source for Debug Examples *=================================================================* * Now the operation to modify values or call other objects. *=================================================================* *-----------------------------------------------------------------* * Move 'a's to the data structure DS2. After the move, the * first occurrence of DS2 contains 10 character 'a's.
Sample Source for Debug Examples *-----------------------------------------------------------------* * After the following SETON operation, *IN02 = 1. *-----------------------------------------------------------------* C SETON 020406 C IF *IN02 = '1' C MOVE '1994-09-30' BigDate C ENDIF *-----------------------------------------------------------------* * Put a new value in the second cell of Arry.
Sample Source for Debug Examples #include #include #include extern char EXPORTFLD[6]; char *c_proc(unsigned int size, char *inzval) { char *ptr; ptr = malloc(size); memset(ptr, *inzval, size ); printf("import string: %6s.\n",EXPORTFLD); return(ptr); } Figure 107. Source for C Procedure cproc. cproc is called by DBGEX.
Exception Handling Overview Chapter 12. Handling Exceptions This chapter explains how ILE RPG exception handling works, and how to use: ¹ Exception handlers ¹ ILE RPG-specific handlers ¹ ILE condition handlers ¹ Cancel handlers ILE RPG supports the following types of exception handlers: ¹ RPG-specific handlers, for example, the use of an error indicator, an 'E' operation code extender, or a *PSSR or INFSR error subroutine.
Exception Handling Overview ¹ Optionally recovering from the exception by passing the exception information to a piece of code to take any necessary actions. When a run-time error occurs, an exception message is generated. An exception message has one of the following types depending on the error which occurred: *ESCAPE Indicates that a severe error has been detected. *STATUS Describes the status of work being done by a program.
Exception Handling Overview Pass 1 Call Stack OPM Program A Activation ILE Proc. P1 Percolate Unhandled Exception ILE Proc. P2 Exception Handlers for P2 ILE Proc. P3 exception occurs for P3 Pass 2 Call Stack OPM Program A Sending Terminating Exception CEE9901 Activation ILE Proc. P1 Percolate Function Check (CPF9999) ILE Proc. P2 Exception Handlers for P2 ILE Proc. P3 exception occurs for P3 Figure 108.
Exception Handling Overview tion. If it remains unhandled, then the entry is removed and the function check is percolated. The process repeats until the exception is handled. In ILE, an exception message is associated with the procedure which is active on the call stack. When the exception is percolated, it is not converted to a function check. Each call stack entry is given a chance to handle the original exception until the control boundary is reached.
Exception Handling Overview 2. If an 'E' operation code extender is present on the calculation specification and the exception is one that is expected for that operation: a. The return values for the built-in funtions %STATUS and %ERROR are set. Note: %STATUS is set when any exception occurs even if the 'E' extender is not specified. b. The exception is handled c. Control resumes with the next ILE RPG operation. 3.
Exception Handling Overview ¹ If there is no *PSSR and a function check occurs, the procedure is removed from the call stack and the exception is percolated to the caller. ¹ Since an inquiry message is never issued for an error in a subprocedure, you do not have access to the 'Retry' function available for some I/O errors. If you expect record-lock errors in a subprocedure, you should code an error indicator or an 'E' extender and check if the status is related to a record being locked.
Using Exception Handlers Using Exception Handlers Planning the exception handling capability of your application means making the following decisions: 1. Decide if you will use the RPG-specific means of handling errors (e.g., error indicator, 'E' extender, or error subroutine) or whether you will write a separate exception handling routine which you will register using the ILE API CEEHDLR. You might also choose to use both. 2.
Using Exception Handlers (when R is chosen). For example, any read operation will be retried if the read failed because of record locking. For other types of messages the exception is percolated up the call stack to the caller of the procedure. That procedure is presented with the exception and given a chance to handle it.
Using Exception Handlers Note: The same exception handling events described would apply to a procedure call (CALLB operation) as well. Example of Unhandled Function Check The following scenario describes the events which occur when a function check occurs in a main procedure and is not handled. This scenario has the following assumptions: 1. There are two programs, PGM1 and PGM2, each containing a procedure, PRC1 and PRC2 respectively. 2. PRC1 calls PGM2 dynamically and PRC2 receives control. 3.
The following then occurs: 1. Since there are no error indicators coded in PRC2, PRC2 cannot handle the function check, and so it is unhandled. 2. Since it is a function check, an inquiry message is issued describing the originating condition. 3. Depending on the response to the inquiry message, PRC2 may be terminated and the exception percolated to PRC1 (response is 'C') or processing may continue in PRC2 (response is 'G').
This section provides some examples of how to use each of these RPG constructs. The ILE RPG for AS/400 Reference provides more information on the *PSSR and INFSR error subroutines, on the EXSR operation code, and on the INFDS and PSDS data structures. Specifying Error Indicators or the 'E' Operation Code Extender Operation codes that allow an error indicator also allow the 'E' operation code extender. The CALLP operation also allows the 'E' extender although it does not allow an error indicator.
Table 15.
subroutine is called again. The procedure will loop unless you code the subroutine to avoid this problem. To see how to code an error subroutine to avoid such a loop, see “Avoiding a Loop in an Error Subroutine” on page 235. Using a File Error (INFSR) Subroutine To handle a file error or exception in a main procedure you can write a file error (INFSR) subroutine. When a file exception occurs: 1. The INFDS is updated. 2.
Note that the File specification for PRDMAS identifies both the INFDS and identifies the INFSR to be associated with it. The following is done for each record in the TRANSACT file: 1. The appropriate record in the product master file is located using the transaction product number. 2. If the record is found, then the quantity of the inventory is updated. 3. If an error occurs on the UPDATE operation, then control is passed to the INFSR error subroutine. 4.
*-----------------------------------------------------------------* * Access the product master file using the transaction product * * number. * *-----------------------------------------------------------------* C TRNPRDNO CHAIN PRDREC 10 *-----------------------------------------------------------------* * If the record is found, update the quantity in the master file.
Using a Program Error Subroutine To handle a program error or exception you can write a program error subroutine (*PSSR). When a program error occurs: 1. The program status data structure is updated. 2. If an indicator is not specified in positions 73 and 74 for the operation code, the error is handled and control is transferred to the *PSSR.
*-----------------------------------------------------------------* * Define relevant parts of program status data structure * *-----------------------------------------------------------------* D Psds SDS D Loc *ROUTINE D Err *STATUS D Parms *PARMS D Name *PROC *-----------------------------------------------------------------* * BODY OF CODE GOES HERE * An error occurs when division by zero takes place. * Control is passed to the *PSSR subroutine.
*-----------------------------------------------------------------* * Start of subprocedure definition *-----------------------------------------------------------------* P SubProc B D SubProc PI 5P 0 ... *-----------------------------------------------------------------* * Body of code goes here including recovery code.
*-----------------------------------------------------------------* * Start of subprocedure definition *-----------------------------------------------------------------* P SubProc B D SubProc PI 5P 0 ... *-----------------------------------------------------------------* * Body of code goes here including division operation.
*=================================================================* * NOLOOP: Show how to avoid recursion in a *PSSR subroutine.
5. The ENDSR operation receives control, and the procedure is canceled. The approach used here to avoid looping can also be used within an INFSR error subroutine. Specifying a Return Point in the ENDSR Operation When using an INFSR or *PSSR error subroutine in a main procedure, you can indicate the return point at which the program will resume processing, by entering one of the following as the Factor 2 entry of the ENDSR statement.
ILE Condition Handlers ILE Condition Handlers ILE condition handlers are exception handlers that are registered at run time using the Register ILE Condition Handler (CEEHDLR) bindable API. They are used to handle, percolate or promote exceptions. The exceptions are presented to the condition handlers in the form of an ILE condition. You can register more than one ILE condition handler. ILE condition handlers may be unregistered by calling the Unregister ILE Condition Handler (CEEHDLU) bindable API.
ILE Condition Handlers | pointer to a communication area between SHOWERR and RPGHDLR, and a field to contain the possible actions, resume or percolate. (RPGHDLR does not promote any exceptions). The basic logic of RPGHDLR is the following: 1. Test to see if it is an out-of-bounds error by testing the message ID | | ¹ If it is, and if SHOWERR has indicated that out-of-bounds errors maybe ignored, it writes 'Handling...' to QSYSPRT and then sets the action to 'Resume'.
ILE Condition Handlers | | | | | | D CondTok D MsgSev D MsgNo D D MsgPrefix D MsgKey DS | | | D CommArea D pPSDS D AllowError DS | | D PassedPSDS D ProcName DS | | | | | * * Action codes are: * D Resume C D Percolate C | | | | *-----------------------------------------------------------------* * Point to the input condition token * *-----------------------------------------------------------------* C EVAL pCondTok = %ADDR(InCondTok) | | | | | | | | | | | | | | | *-----------------------------
ILE Condition Handlers requires a definition for the error-prone array ARR1, and identification of the parameter lists used by the ILE bindable APIs CEEHDLR and CEEHDLU. The basic logic of the program is as follows: 1. Register the handler RPGHDLR using the subroutine RegHndlr. This subroutine calls the CEEHDLR API, passing it the procedure pointer to RPGHDLR. | | | 2.
ILE Condition Handlers | | | | | *=================================================================* * SHOWERR: Show exception handling using a user-defined * * exception handler. * *=================================================================* FQSYSPRT O F 132 PRINTER | | | | | | | | | | | | | | | | | *-----------------------------------------------------------------* * The following are the parameter definitions for the CEEHDLR * * API.
ILE Condition Handlers | | | | *-----------------------------------------------------------------* * Register the handler and generate errors * *-----------------------------------------------------------------* C EXSR RegHndlr | | | | | | | | | | | | | | *-----------------------------------------------------------------* * Generate a substring error * * This is an "allowed" error for this example (RPGHDLR * * handles the exception, allowing control to return to the * * next instruction after the error)
*=================================================================* * *PSSR: Error Subroutine for the procedure * *=================================================================* C *PSSR BEGSR C EXCEPT InPssr C EXCEPT Cancelling C ENDSR '*CANCL' *=================================================================* * Procedure Output * *=================================================================* OQSYSPRT E ImBack O 'I''m Back' OQSYSPRT E InPssr O 'In PSSR' OQSYSPRT E Cancelling O 'Cancelling...
handler remains in effect until the call stack entry is removed, or until CEEUTX is called to disable it. See the System API Reference for more information on these ILE bindable APIs. Figure 118 shows an example of enabling and coding a cancel handler for a subprocedure. (Cancel handlers can also be enabled for main procedures in the same way.) *----------------------------------------------------------------* Define the prototype for the cancel handler. This procedure is * a local procedure.
*----------------------------------------------------------------* Procedure Enabler. This procedure enables a cancel handler, * then gets an error which causes Enabler to be canceled.
*----------------------------------------------------------------* Define the cancel handler. The parameter is a pointer to the * 'communication area', a message to be displayed. *----------------------------------------------------------------P CanHdlr B D CanHdlr PI D pMsg * *----------------------------------------------------------------* Define a field based on the input pointer pMsg.
If you encounter this problem, you have two possible ways to avoid it: 1. Ensure that the caller is in a different activation group from the ILE RPG procedure. 2. Enable an ILE condition handler in the RPG procedure. In the handler, if the message is one that you want to ignore, indicate that the message should be handled. Otherwise, indicate that it should be percolated. You could also make this handler more generic, and have it ignore all messages with a severity of 0 (information) and 1 (warning).
*---------------------------------------------------------------* Handle information or warning messages, otherwise percolate *---------------------------------------------------------------C IF MsgSev <= Warning C EVAL Action = Handle C ELSE C EVAL Action = Percolate C ENDIF C RETURN Figure 121. How to Ignore Status and Notify Messages Chapter 12.
250 ILE RPG for AS/400 Programmer's Guide
Using the DUMP Operation Code Chapter 13. Obtaining a Dump This chapter describes how to obtain an ILE RPG formatted dump and provides a sample formatted dump. Obtaining an ILE RPG Formatted Dump To obtain an ILE RPG formatted dump (printout of storage) for a procedure while it is running, you can: ¹ Code one or more DUMP operation codes in the calculation specifications ¹ Respond to a run-time message with a D or F option. It is also possible to automatically reply to make a dump available.
Example of a Formatted Dump ¹ If a DUMP operation is bypassed by a GOTO operation, the DUMP operation does not occur. Example of a Formatted Dump The following figures show an example of a formatted dump of a module similar to DBGEX (see “Sample Source for Debug Examples” on page 211). In order to show how data buffers are handled in a formatted dump we added the output file QSYSPRT.
Example of a Formatted Dump .E/ ILE RPG routine in which the exception or error occurred. .F/ CPF or MCH for a machine exception. .G/ Information about the last file used in the program before an exception or error occurred. In this case, no files were used. .H/ Program information. '*N/A*' indicates fields for which information is not available in the program. These fields are only updated if they are included in the PSDS. Feedback Areas Chapter 13.
Example of a Formatted Dump INFDS FILE FEEDBACK .I/ File . . . . . . . . . . . . . File Open . . . . . . . . . . File at EOF . . . . . . . . . File Status . . . . . . . . . File Operation . . . . . . . . File Routine . . . . . . . . . Statement Number . . . . . . . Record Name . . . . . . . . . Message Identifier . . . . . . OPEN FEEDBACK .J/ ODP type . . . . . . . . . . . File Name . . . . . . . . . . Library . . . . . . . . . . Member . . . . . . . . . . . . Spool File . . . . . . . . . . Library . . . .
Example of a Formatted Dump .J/ This is the file open feedback information for the file. See the Data Management manual for a description of the fields. .K/ This is the common I/O feedback information for the file. See the Data Management manual for a description of the fields.
Example of a Formatted Dump ILE RPG FORMATTED DUMP Module Name. . . . . . . . . . . . . . : DBGEX2 Optimization Level . . . . . . . . . . : *NONE .L/ .
Example of a Formatted Dump DS1 OCCURRENCE(1) FLD1 FLD1A FLD2 OCCURRENCE(2) FLD1 FLD1A FLD2 OCCURRENCE(3) FLD1 FLD1A .R/ DS OCCURS(3) CHAR(5) CHAR(1) (1) (2) (3) (4) (5) BIN(5,2) '1BCDE' DIM(5) '1' 'B' 'C' 'D' 'E' 123.45 'F1C2C3C4C5'X CHAR(5) CHAR(1) (1) (2) (3) (4) (5) BIN(5,2) 'ABCDE' DIM(5) 'A' 'B' 'C' 'D' 'E' 123.
Example of a Formatted Dump 258 .N/ Beginning of user variables, listed in alphabetical order, and grouped by procedure. Data that is local to a subprocedure is stored in automatic storage and is not available unless the subprocedure is active. Note that the hexadecimal values of all variables are displayed. :nt Names longer than 131 characters, will appear in the dump listing split across multiple lines. The entire name will be printed with the characters '...' at the end of the lines.
Working with Files and Devices This section describes how to use files and devices in ILE RPG programs. Specifically, it shows how to: ¹ Associate a file with a device ¹ Define a file (as program-described or externally-described) ¹ Process files ¹ Access database files ¹ Access externally-attached devices ¹ Write an interactive application Note: The term 'RPG IV program' refers to an Integrated Language Environment program that contains one or more procedures written in RPG IV. Copyright IBM Corp.
260 ILE RPG for AS/400 Programmer's Guide
Associating Files with Input/Output Devices Chapter 14. Defining Files Files serve as the connecting link between a program and the device used for I/O. Each file on the system has an associated file description which describes the file characteristics and how the data associated with the file is organized into records and fields.
Associating Files with Input/Output Devices SPECIAL. Figure 126 on page 262 shows a file description specification for a display (WORKSTN) file FILEX. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FFILEX CF E WORKSTN Figure 126.
Types of File Descriptions RPG program FILEY File name - FILEY Device = SEQ File type = DEVICE Device type = PRINTER Figure 128. Associating a file name with a display file description Although the file name and file type are coded in the RPG program, in many cases you can change the type of file or the device used in a program without changing the program. To find out how, see “Overriding and Redirecting File Input and Output” on page 273.
Types of File Descriptions ¹ 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. ¹ Improved reliability.
Defining Externally Described Files .2/ An externally described file (that is, a file with field-level external description) is used as a program-described file in the program. A program-described file is identified by an F in position 22 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 at the record level to the operating system.
Defining Externally Described Files 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 keyword on the file description specifications for the externally described file as shown in Figure 130. The format is RENAME(old name:new name).
Defining Externally Described Files Once a record-format is ignored, it cannot be specified for any other keyword (SFILE, RENAME, or INCLUDE), or for another IGNORE. Ignored record-format names appear on the cross-reference listing, but they are flagged as ignored. To indicate that a record format from an externally described file, is to be ignored, enter the keyword and parameter IGNORE(record-format name) on the file description specification in the Keyword field.
Defining Externally Described Files with an indicator, and you then try to rename the field referencing the unprefixed name, you will get an error. Conversely, if you first rename the field to something other than the prefixed name, and you then use the prefixed name on a specification, you will get an error. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * IRcdname+++....In.........................................................* IMSTRITEM 01 .1/ I..............Ext-field+.....
Defining Externally Described Files field in positions 49 through 62 and assign a match-level value in positions 65 and 66. 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 16 of the recordidentification line.
Defining Externally Described Files ¹ 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 default values, which depend on the data format specified in the external description (for example: a blank for character fields; zero for numeric fields). *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+...
Data Management Operations and ILE RPG I/O Operations The RPG 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 manual. Defining 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. To use a programdescribed file in an RPG program you must: 1.
Data Management Operations and ILE RPG I/O Operations Table 17.
Overriding and Redirecting File Input and Output Chapter 15.
Overriding and Redirecting File Input and Output in the program. For example, if the RPG device name is PRINTER, and the actual file the program connects to is not a printer, the OS/400 system ignores the RPG 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.
File Locking Compile Time: Override File QTAPE to File FMT1 FMT1 RPG program File name = QTAPE Format = E Device = SEQ Execution Time: No Override QTAPE File type = DEVICE Device type = TAPE Figure 137. Redirecting File Input and Output Example File Locking 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 the execution of a job. Programs within a job are not affected by file lock states.
Record Locking Record Locking 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 IV programs, you use an update file to read records for update.
Sharing an Open Data Path included. These output operations can be processed by EXCEPT output, detail output, or total output. (There are exceptions to these rules when operating under commitment control. See “Using Commitment Control” on page 307 for more information.) Sharing an Open Data Path An open data path is the path through which all input and output operations for a file are performed. Usually a separate open data path is defined each time a file is opened.
Spooling ¹ 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 program are overridden to one shared file at run time, the file opening order is important.
SRTSEQ/ALTSEQ Output Spooling Output spooling is valid for batch or interactive jobs. The description of the file that is specified in the RPG program by the file name contains the specification for spooling as shown in the following diagram: Spooled File RPG program QPRINT SPOOL (*YES) QUEUE (QPRINT) File name = QPRINT Device = PRINTER Spooling Queue QPRINT Execution Time Start Printer writer Start Printer writer Time Device Figure 138.
SRTSEQ/ALTSEQ 280 ILE RPG for AS/400 Programmer's Guide
Database Files Chapter 16. Accessing Database Files You can access a database file from your program by associating the file name with the device DISK in the appropriate file specification. DISK files of an ILE RPG program also associate with distributed data management (DDM) files, which allow you to access files on remote systems as database files. Database Files Database files are objects of type *FILE on the AS/400.
Using Externally Described Disk Files Using Externally Described Disk Files Externally described DISK files are identified by an E in position 22 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.
Using Externally Described Disk Files *.. 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 139.
Using Externally Described Disk Files *.. 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) .
Using Externally Described Disk Files RPG 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. .
Using Externally Described Disk Files Valid Search Arguments You can specify a search argument in the ILE RPG operations CHAIN, DELETE, READE, READPE, 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.
Using Externally Described Disk Files ¹ 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.
Using Program-Described Disk Files no record blocking is done by the compiler, nor by data management. If the keyword BLOCK is not specified, then default blocking occurs as described above. The input/output and device-specific feedback of the file information data structure are not updated after each read or write (except for the RRN and Key information on block reads) for files in which the records are blocked and unblocked by the RPG compiler.
Using Program-Described Disk 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 ...+... * FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FORDDTLL IP F 118 3PIDISK KEYLOC(15) F* Figure 141.
Using Program-Described Disk Files On the file description specifications, the length of the key field is defined as 10 in positions 29 through 33 (the combined number of positions required for the ORDER and ITEM fields). The starting position of the key field is described as 15 using the keyword KEYLOC (starting in position 44). The starting position must specify the first position of the first key field. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+...
Methods for Processing Disk Files 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.
Methods for Processing Disk Files Table 19 on page 292 shows the valid entries for positions 28, 34, and 35 of the file description specification for the various file types and processing methods. The subsequent text describes each method of processing. Table 19. Processing Methods for DISK Files Processing Method Limits Processing (Pos. 28) Record Address Type (Pos. 34) File Organization (Pos.
Methods for Processing Disk Files If, in the same job or activation group, two logical files use the same physical file, and one file is processed consecutively and one is processed for random update, a record can 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.
Methods for Processing Disk Files A***************************************************************** A* DESCRIPTION: This is the DDS for the physical file EMPMST. * A* It contains one record format called EMPREC. * A* This file contains one record for each employee * A* of the company.
Methods for Processing Disk Files as the ENUM field plus the WEEKNO (week number) field, which is a composite key. ***************************************************************** * PROGRAM NAME: YTDRPT1 * * RELATED FILES: EMPL1 (Logical File) * * PRINT (Printer File) * * DESCRIPTION: This program shows an example of processing * * records using the sequential-by-key method. * * This program prints out each employee's * * information and weekly hours worked.
Methods for Processing Disk Files EXAMPLE PROGRAM 2 (Sequential-by-Key Using READ): This example is the same as the previous example except that the EMPL1 file is defined as a fullprocedural file, and the reading of the file is done by the READ operation code.
Methods for Processing Disk Files OPRINT O O O O O O O O O O O O O O O O O O H 1P 2 6 40 'EMPLOYEE WEEKLY WORKING ' 52 'HOURS REPORT' H 01 1 12 'EMPLOYEE: ' 32 ENAME H 01 1 12 'SERIAL #: ' 17 27 'DEPT: ' 30 40 'TYPE: ' 41 ENUM EDEPT ETYPE H 01 1 20 'WEEK #' 50 'HOURS WORKED' D 12 1 WEEKNO EHWRK 3 18 45 Figure 148 (Part 2 of 2). Sequential-by-Key Processing, Example 2 EXAMPLE PROGRAM 3 (Matching-Record Technique): In this example, the TRWEEK file is defined as a secondary input file.
Methods for Processing Disk Files C 01 Z-ADD 0 TOTHRS 5 1 C 01 Z-ADD 0 TOTOVT 5 1 C 01 SETOFF 12 C* C MR IF (*IN02='1') C ADD EHWRK TOTHRS C EHWRK SUB ENHRS OVTHRS 4 111 C 11 ADD OVTHRS TOTOVT C SETON 12 C ENDIF OPRINT H 1P 2 6 O 50 'YTD PAYROLL SUMMARY' O D 01 1 O 12 'EMPLOYEE: ' O ENAME 32 O D 01 1 O 12 'SERIAL #: ' O ENUM 17 O 27 'DEPT: ' O EDEPT 30 O 40 'TYPE: ' O ETYPE 41 O D 02 MR 1 O 8 'WEEK #' O WEEKNO 10 O 32 'HOURS WORKED = ' O EHWRK 3 38 * These 2 detail output lines are processed if *IN01 is on
Methods for Processing Disk Files Random-by-Key Processing For the random-by-key method of processing, a search argument that identifies the key of the record to be read is specified in factor 1 of the calculation specifications for the CHAIN operation. Figure 151 on page 300 shows an example of an externally described DISK file being processed randomly by key. The specified record can be read from the file either during detail calculations or during total calculations.
Methods for Processing Disk Files ***************************************************************** * PROGRAM NAME: EMSTUPD * * RELATED FILES: EMPMST (Physical File) * * CHANGE (Physical File) * * DESCRIPTION: This program shows the processing of records * * using the random-by-key method. The CHAIN * * operation code is used. * * The physical file CHANGE contains all the * * changes made to the EMPMST file. Its record * * format name is CHGREC.
Methods for Processing Disk Files 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. Examples of Sequential-within-Limits Processing Figure 152 on page 302 shows an example of an indexed file being processed sequentially within limits.
Methods for Processing Disk Files ***************************************************************** * PROGRAM NAME: ESWLIM1 * * RELATED FILES: EMPMST (Physical File) * * LIMITS (Physical File) * * PRINT (Printer File) * * DESCRIPTION: This program shows the processing of an * * indexed file sequentially within limits. * * This program prints out information for the * * employees whose employee numbers are within * * the limits given in the file LIMITS.
Methods for Processing Disk Files ***************************************************************** * PROGRAM NAME: ESWLIM2 * * RELATED FILES: EMPMST (Physical File) * * LIMITS (Physical File) * * PRINT (Printer File) * * DESCRIPTION: This program shows the processing of an * * externally described file sequentially * * within limits. * * This program prints out information for the * * employees whose employee numbers are within * * the limits given in the file LIMITS.
Valid File Operations 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 must be a valid existing record; for a new record, that place must be a deleted record. You can use the CL command INZPFM to initialize records for use by relative record number.
Valid File Operations Table 20.
Valid File Operations Table 21.
Using Commitment Control Using Commitment Control This section 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: ¹ all of the file operations are successful (a commit operation) ¹ none of the file operations has any effect (a rollback operation). In this way, you process a group of operations as a unit. To use commitment control, you do the following: ¹ On the AS/400: 1.
Using Commitment Control 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 activation group or job has finished processing files under commitment control. See the CL Reference (Abridged) for further information on the STRCMTCTL and ENDCMTCTL commands. Commitment Control Locks On the STRCMTCTL command, you specify a level of locking, either LCKLVL(*ALL), LCKLVL(*CHG), or LCKLVL(*CS).
Using Commitment Control The default scope for a commitment definition is to the activation group of the program issuing the STRCMTCTL command, that is, at the activation group level. Only programs that run within that activation group will use that commitment definition. OPM programs will use the *DFTACTGRP commitment definition. ILE programs will use the activation group they are associated with.
Using Commitment Control 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 activation group or job. A program does not have to operate all its files under commitment control, and to do so may adversely affect performance. The COMMIT and ROLBK operations have no effect on files that are not under commitment control.
Using Commitment Control *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++ FMASTER UF E K DISK COMMIT FTRANS UF E K DISK COMMIT F* *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
DDM Files Figure 156 on page 312 is an example showing conditional commitment control. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++ FMASTER UF E K DISK COMMIT(COMITFLAG) FTRANS UF E K DISK COMMIT(COMITFLAG) *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
DDM Files The DDM file provides the information needed for a local system to locate a remote system and to access the data in the source file. For more information about using DDM and creating DDM files, refer to the Distributed Data Management manual. Using Pre-V3R1 DDM Files | | | | If you are using a pre-Version 3 Release 1.
DDM Files 314 ILE RPG for AS/400 Programmer's Guide
Types of Device Files Chapter 17. Accessing Externally Attached Devices You can access externally attached devices from RPG by using device files. Device files are files that provide access to externally attached hardware such as printers, tape units, diskette units, display stations, and other systems that are attached by a communications line. This chapter describes how to access externally attached devices using RPG device names PRINTER, SEQ, and SPECIAL.
Accessing Printer Devices Accessing Printer Devices PRINTER files of ILE RPG programs associate with the printer files on the AS/400 system: Printer files allow you to print output files. This chapter provides information on how to specify and use printer files in ILE RPG programs. Specifying PRINTER Files To indicate that you want your program to access printer files, specify PRINTER as the device name for the file in a File Description specification. Each file must have a unique file name.
Accessing Printer Devices For either a program-described or an externally-described file, you can specify an indicator, *IN01 through *IN99, using the keyword OFLIND(overflow indicator) on the File Description specification. 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.
Accessing Printer Devices ¹ 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.
Accessing Printer Devices Table 23. Results of the Presence or Absence of an Overflow Indicator File Description Specifications Positions 44-80 Output Specifications Positions 21-29 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.
Accessing Printer Devices *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * OFilename++DF..N01N02N03Excnam++++B++A++Sb+Sa+............................. OPRINT D OANL2 3 6 O OR L2 O..............N01N02N03Field+++++++++YB.End++PConstant/editword/DTformat++ O ACCT 8 O* Figure 158.
Accessing Printer Devices Overflow Occurs During Overflow Printing and Setting of the OA Overflow Indicator Without Fetch Normal Output Get a Record Detail Output Total Output With Fetch Exception Output Detail Calc Total Calculations Total Calc Normal Output Detail Output Total Output Exception Output Detail Calc 0A Print 0A Total Output Total Calc 0A Print 0A Overflow Printing T = Total H = Heading Print Print Print Print D = Detail E = Exception Detail Calculations 0A Print 0A
Accessing Printer Devices at overflow output time unless overflow is sensed again since the last time the overflow lines were written. Specifying Fetch Overflow Specify fetch overflow with an F in position 18 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.
Accessing Printer Devices The total lines with an F coded in position 18 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.
Accessing Printer Devices Table 25.
Accessing Tape Devices *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FPRINT O F 132 PRINTER PRTCTL(LINE) *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ DLINE DS D SpBefore 1 3 D SpAfter 4 6 D SkBefore 7 9 D SkAfter 10 12 D CurLine 13 15 0 *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+.
Using Sequential Files Accessing Display Devices You use display files to exchange information between your program and a display device such as a workstation. A display file is used to define the format of the information that is to be presented on a display, and to define how the information is to be processed by the system on its way to and from the display. See Chapter 18, “Using WORKSTN Files” on page 331 for a discussion on how to use WORKSTN files.
Using SPECIAL Files Example of Specifying a Sequential File Figure 162 shows an example of how to specify a SEQ file in an ILE RPG source member. *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+ ...* FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++ FTIMECDS IP E DISK FPAYOTIME O F 132 SEQ * Figure 162. SEQ Device A SEQ device is specified for the PAYOTIME file.
Using SPECIAL Files Status R Read a record and place it in the area defined by the area parameter. W The ILE RPG 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. The status parameter is a one-position character field that indicates the status of the user-written routine when control is returned to the ILE RPG program.
Using SPECIAL Files Table 27. Valid File Operations for a SPECIAL File File Description Specifications Positions 17 Calculation Specifications Positions 18 26-35 I P/S CLOSE, FEOD C P/S WRITE, CLOSE, FEOD U P/S UPDATE, DELETE, CLOSE, FEOD O WRITE, OPEN, CLOSE, FEOD I F READ, OPEN, CLOSE, FEOD C F READ, WRITE, OPEN, CLOSE, FEOD U F READ, UPDATE, DELETE, OPEN, CLOSE, FEOD Example of Using a Special File Figure 163 shows how to use the RPG device name SPECIAL in a program.
Using SPECIAL Files *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * DName+++++++++++ETDsFrom+++To/L+++IDc.Functions++++++++++++++++++++++++++++ D ERROR S 5S 0 *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... * CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq.... *----------------------------------------------------------------* * The first 4 parameters are ILE RPG created parameter list.
Using Externally Described WORKSTN Files Chapter 18. Using WORKSTN Files Interactive applications on the AS/400 generally involve communication with: ¹ One or more work station users via display files ¹ One or more programs on a remote system via ICF files ¹ One or more devices on a remote system via ICF files. Display files are objects of type *FILE with attribute of DSPF on the AS/400 system. You use display files to communicate interactively with users at display terminals.
Using Externally Described WORKSTN Files 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 linenumber 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.
Using Externally Described WORKSTN Files *.. 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 CA03(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 .
Using Externally Described WORKSTN Files Specifying 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.
Using Externally Described WORKSTN Files 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.
Using Externally Described WORKSTN Files Customer Name Search Search Code _______ Number Name Address City State XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXX
Using Externally Described WORKSTN Files specifications require that a relative-record-number field be specified in the second position of the SFILE keyword on the file description specification. 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.
Using Program-Described WORKSTN Files *.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..* AAN01N02N03T.
Using Program-Described WORKSTN Files ¹ 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 PASS(*NOIND) on a file description specification for a programdescribed WORKSTN file. The PASS(*NOIND) keyword indicates that the RPG program will not additionally pass indicators to data management on output or receive them on input.
Using Program-Described WORKSTN Files Input Specifications The input specifications describe the record that the RPG program receives from the display or ICF device. The WORKSTN file name must be specified in positions 7 through 16. 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.
Valid WORKSTN File Operations ¹ 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. 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.
Multiple-Device Files EXFMT Operation The EXFMT operation is a combination of a WRITE followed by a READ to the same record format (it corresponds to a data management WRITE-READ operation). If you define a WORKSTN file on the file description specifications as a fullprocedural (F in position 18) combined file (C in position 17) that uses externally-described data (E in position 22) the EXFMT (execute format) operation code can be used to write and read from the display.
Multiple-Device Files operations. See the sections on inviting a program device in ICF Programming manual and Data Management manual. ¹ 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-frominvited-program-device).
Multiple-Device Files ation to the ICF device, you do not need to modify the value again unless an input operation completes successfully with a different device. ¹ The SAVEDS keyword indicates a data structure that is saved and restored for each device acquired to a file. The SAVEIND keyword 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.
Database Physical File Chapter 19. Example of an Interactive Application This chapter illustrates some common workstation applications and their ILE RPG coding. The application program presented in this chapter consists of four modules. Each module illustrates a common use for WORKSTN files. The first module (CUSMAIN) provides the main menu for the program. Based on the user's selection, it calls the procedure in the appropriate module which provides the function requested.
Main Menu Inquiry A***************************************************************** A* FILE NAME: CUSMST * A* RELATED PGMS: CUSMNT, SCHZIP, SCHNAM * A* RELATED FILES: CUSMSTL1, CUSMSTL2, CUSMSTL3 (LOGICAL FILES) * A* DESCRIPTION: THIS IS THE PHYSICAL FILE CUSMST. IT HAS * A* ONE RECORD FORMAT CALLED CUSREC.
Main Menu Inquiry A***************************************************************** A* FILE NAME: MAINMENU * A* RELATED PGMS: CUSMAIN * A* DESCRIPTION: THIS IS THE DISPLAY FILE MAINMENU. IT HAS 1 * A* RECORD FORMAT CALLED HDRSCN.
Main Menu Inquiry ***************************************************************** * PROGRAM NAME: CUSMAIN * * RELATED FILES: MAINMENU (DSPF) * * RELATED PGMS: CUSMNT (ILE RPG PGM) * * SCHZIP (ILE RPG PGM) * * SCHNAM (ILE RPG PGM) * * DESCRIPTION: THIS IS A CUSTOMER MAIN INQUIRY PROGRAM. * * IT PROMPTS THE USER TO CHOOSE FROM ONE OF THE * * FOLLOWING ACTIONS: * * 1.MAINTAINS (ADD, UPDATE, DELETE AND DISPLAY) * * CUSTOMER RECORD. * * 2.SEARCH CUSTOMER RECORD BY ZIP CODE. * * 3.
File Maintenance 22:30:05 CUSTOMER MAIN INQUIRY 9/30/94 Press one of the following PF keys. F3 F5 F6 F7 End Job Maintain Customer File Search Customer by Zip Code Search Customer by Name Figure 172. Customer Main Inquiry prompt screen File Maintenance The following illustrates a maintenance program using the WORKSTN file. It allows you to add, delete, update, and display records of the master customer file.
File Maintenance MNTMENU: DDS for a Display Device File A***************************************************************** A* FILE NAME: MNTMENU * A* RELATED PGMS: CUSMNT * A* RELATED FILES: CUSMSTL1 (LOGICAL FILE) * A* DESCRIPTION: THIS IS THE DISPLAY FILE MNTMENU. IT HAS 3 * A* RECORD FORMATS.
File Maintenance A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A MODE 8A O CUST NAME R R O B ADDR1 R B ADDR2 R B CITY R B STATE R B ZIP R B 04 04 04 04 04 04 MODE1 R CSTBLD 8 O MODE 8 O CUST R O NAME R I ADDR1 R I ADDR2 R I CITY R I STATE R I ZIP R Y I 1 4DSPATR(HI) 1 13'MODE' DSPATR(HI) 2 4TIME DSPATR(HI) 2 28'CUSTOMER FILE MAINTENANCE' DSPATR(HI) DSPATR(RI) 2 70DATE EDTCDE(Y) DSPATR(HI) 4 14
File Maintenance Delete, and Display modes. The fields are defined as output/input (B in position 38). The fields are protected when Display or Delete mode is selected (DSPATR(PR)). The CSTBLD record provides only input fields (I in position 38) for a new record. The HDRSCN record format contains the constant 'Customer File Maintenance'. The ERRMSG keyword defines the messages to be displayed if an error occurs.
File Maintenance ******************************************************************** * SUBROUTINE - ADDSUB * * PURPOSE - ADD NEW CUSTOMER TO FILE * ******************************************************************** C ADDSUB BEGSR C CSTKEY CHAIN CMLREC1 50 C IF NOT *IN50 C MOVE *ON *IN51 C ELSE C MOVE *OFF *IN51 C MOVE *BLANK NAME C MOVE *BLANK ADDR1 C MOVE *BLANK ADDR2 C MOVE *BLANK CITY C MOVE *BLANK STATE C Z-ADD *ZERO ZIP C EXFMT CSTBLD C IF NOT *IN12 C WRITE CMLREC1 C ENDIF C ENDIF C ENDSR *********
File Maintenance ******************************************************************** * SUBROUTINE - DELSUB * * PURPOSE - DELETE CUSTOMER MASTER RECORD * ******************************************************************** C DELSUB BEGSR C MOVE *ON *IN04 C CSTKEY CHAIN CMLREC1 52 C IF NOT *IN52 C EXFMT CSTINQ C IF NOT *IN12 C DELETE CMLREC1 C ELSE C UNLOCK CUSMSTL1 C ENDIF C ENDIF C ENDSR ******************************************************************** * SUBROUTINE - INQSUB * * PURPOSE - DISPLAY CUSTOM
File Maintenance change the mode of processing by pressing F5 (ADD), F6 (UPDATE), F7 (DELETE), or F8 (DISPLAY). To add a new record to the file, the program uses the customer number as the search argument to chain to the master file. If the record does not exist in the file, the program displays the CSTBLD screen to allow the user to enter a new customer record. If the record is already in the file, an error message is displayed.
File Maintenance DISPLAY MODE 22:31:06 Customer: CUSTOMER FILE MAINTENANCE 00007 9/30/94 Mikhail Yuri 1001 Bay Street Suite 1702 Livonia MI 11201 F12 Cancel DISPLAY Figure 177. 'Customer File Maintenance' Display Mode screen The workstation user responds to the add prompt by entering a new customer number as shown in Figure 178.
File Maintenance ADD MODE 22:32:04 Customer: Name Address Address City State CUSTOMER FILE MAINTENANCE 00012 9/30/94 JUDAH GOULD 2074 BATHURST AVENUE YORKTOWN NY Zip 70068 F12 Cancel Addition Figure 179. 'Customer File Maintenance' Add Mode prompt screen The workstation user responds to the delete prompt by entering a customer number as shown in Figure 180.
Search by Zip Code UPDATE MODE 22:33:17 CUSTOMER FILE MAINTENANCE 00010 F3 End Job F5 Add 9/30/94 <--Enter Customer Number F6 Update F7 Delete F8 Display Figure 181. 'Customer File Maintenance' Update Mode prompt screen Search by Zip Code The following illustrates WORKSTN subfile processing (display only). Subfiles are used to display all matched records for a specified zip code.
Search by Zip Code SZIPMENU: DDS for a Display Device File A***************************************************************** A* FILE NAME: SZIPMENU * A* RELATED PGMS: SCHZIP * A* RELATED FILES: CUSMSTL2 (LOGICAL FILE) * A* DESCRIPTION: THIS IS THE DISPLAY FILE SZIPMENU. IT HAS 6 * A* RECORD FORMATS.
Search by Zip Code A 55 A N55 A N55 A A A A A A A A A A A ZIP R O 4 4 7 7 SFLCLR SFLDSPCTL SFLDSP SFLSIZ(13) SFLPAG(13) ROLLUP(95 'ROLL UP') OVERLAY CA04(04 'RESTART ZIP CDE') 4'Zip Code' 14DSPATR(HI) 4'Customer Name' DSPATR(HI UL) 27'A/R Balance' DSPATR(HI UL) Figure 183 (Part 2 of 2). DDS for display device file SZIPMENU The DDS for the SZIPMENU display device file contains six record formats: HEAD, FOOT1, FOOT2, PROMPT, SUBFILE, and SUBCTL.
Search by Zip Code SCHZIP: RPG Source ***************************************************************** * PROGRAM NAME: SCHZIP * * RELATED FILES: CUSMSTL2 (LOGICAL FILE) * * SZIPMENU (WORKSTN FILE) * * DESCRIPTION: THIS PROGRAM SHOWS A CUSTOMER MASTER SEARCH * * PROGRAM USING WORKSTN SUBFILE PROCESSING. * * THIS PROGRAM PROMPTS THE USER FOR THE ZIP CODE* * AND DISPLAYS THE CUSTOMER MASTER RECORD BY * * ZIP CODE. * * ROLL UP KEY CAN BE USED TO LOOK AT ANOTHER * * PAGE. PF3 IS USED TO QUIT THE PROGRAM.
Search by Zip Code ******************************************************************** * SUBROUTINE - SFLPRC * * PURPOSE - PROCESS SUBFILE AND DISPLAY * ******************************************************************** C SFLPRC BEGSR C NXTPAG TAG C EXSR SFLCLR C EXSR SFLFIL C SAMPAG TAG C WRITE FOOT2 C WRITE HEAD C EXFMT SUBCTL C IF *IN95 C IF NOT *IN71 C GOTO NXTPAG C ELSE C GOTO SAMPAG C ENDIF C ENDIF C ENDSR ******************************************************************** * SUBROUTINE - SFLFIL *
Search by Zip Code The zip code (ZIP) is used to position the CUSMSTL2 file by the SETLL operation. Notice that the record format name CMLREC2 is used in the SETLL operation instead of the file name CUSMSTL2. If no record is found, an error message is displayed. The SFLPRC subroutine handles the processing for the subfile: clearing, filling, and displaying. The subfile is prepared for additional requests in subroutine SFLCLR.
Search and Inquiry by Name 22:34:45 Zip Code CUSTOMER SEARCH BY ZIP 11201 Customer Name A/R Balance Rick Coupland Mikhail Yuri Karyn Sanders 9/30/94 ENTER - Continue 300.00 150.00 5.00 F3 - End Job F4 - RESTART ZIP CODE Figure 186. 'Customer Search by Zip' screen Search and Inquiry by Name The following illustrates WORKSTN subfile processing (display with selection).
Search and Inquiry by Name SNAMMENU: DDS for a Display Device File A 55 A N55 A N55 A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A SRCNAM R O 5 5 7 8 8 SFLCLR SFLDSPCTL SFLDSP ROLLUP(95 'ROLL UP') OVERLAY CA04(04 'RESTART SEARCH NAME') 4'Search Name' 17REFFLD(NAME CUSMSTL3) DSPATR(HI) 6'Select' DSPATR(HI) 6' "X" Customer Name ' DSPATR(HI) DSPATR(UL) 42' Number Zip Code ' DSPATR(HI) DSPATR(UL) R CUSDSP CUST 5S 0O NAME 20A O ADDR1 ADDR2 20A 20A O O CITY 20A O STATE 2A
Search and Inquiry by Name ¹ SFLDSPCTL indicates when to display the subfile-control record format (when indicator 55 is off). ¹ SFLDSP indicates when to display the subfile (when indicator 55 is off). ¹ SFLSIZ specifies the total size of the subfile. In this example, the subfile size is 13 records that are displayed on lines 9 through 21. ¹ SFLPAG defines the number of records on a page. In this example, the page size is the same as the subfile size.
Search and Inquiry by Name ******************************************************************** * MAINLINE * ******************************************************************** C WRITE FOOT1 C WRITE HEAD C EXFMT PROMPT C DOW NOT *IN03 C CSTKEY SETLL CUSREC C EXSR SFLPRC C EXSR SFLCHG C IF (NOT *IN03) AND (NOT *IN04) C WRITE FOOT1 C WRITE HEAD C EXFMT PROMPT C ENDIF C ENDDO C* C SETON LR ******************************************************************** * SUBROUTINE - SFLPRC * * PURPOSE - PROCESS SUBFILE
Search and Inquiry by Name ******************************************************************** * SUBROUTINE - SFLCLR * * PURPOSE - CLEAR SUBFILE RECORDS * ******************************************************************** C SFLCLR BEGSR C MOVE *ON *IN55 C WRITE SUBCTL C MOVE *OFF *IN55 C MOVE *OFF *IN21 C Z-ADD *ZERO RECNUM 5 0 C ENDSR ******************************************************************** * SUBROUTINE - SFLCHG * * PURPOSE - CUSTOMER RECORD SELECTED * **************************************
Search and Inquiry by Name ¹ To display customer detail by entering X, and pressing ENTER. The user can then return to the PROMPT screen by pressing ENTER, display the subfile again by pressing F4, or end the program by pressing F3. In Figure 190, the user responds to the initial prompt by entering a customer name. 22:35:26 CUSTOMER SEARCH & INQUIRY BY NAME Enter Search Name 9/30/94 JUDAH GOULD ENTER - Continue F3 - End Job Figure 190.
Search and Inquiry by Name The detailed information for the customer selected is shown in Figure 192 on page 370. At this point the user selects the appropriate function key to continue or end the inquiry. 23:39:48 CUSTOMER SEARCH & INQUIRY BY NAME Customer 00012 Name JUDAH GOULD Address 2074 BATHURST AVENUE City YORKTOWN State NY ENTER - Continue F3 - End Job .00 F4 - Restart Name Figure 192.
Appendixes Copyright IBM Corp.
372 ILE RPG for AS/400 Programmer's Guide
Differences Between OPM RPG/400 and ILE RPG Appendix A. Behavioral Differences Between OPM RPG/400 and ILE RPG for AS/400 The following lists note differences in the behavior of the OPM RPG/400 compiler and ILE RPG. Compiling 1. If you specify CVTOPT(*NONE) in OPM RPG, all externally described fields that are of a type or with attributes not supported by RPG will be ignored.
Differences Between OPM RPG/400 and ILE RPG Running 1. The FREE operation is not supported by RPG IV. 2. Certain MCH messages may appear in the job log that do not appear under OPM (for example, MCH1202). The appearance of these messages does not indicate a change in the behavior of the program. 3. If you use the nonbindable API QMHSNDPM to send messages from your program, you may need to add 1 to the stack offset parameter to allow for the presence of the program-entry procedure in the stack.
Differences Between OPM RPG/400 and ILE RPG 4. Call performance for LR-on will be greatly improved by having no PSDS, or a PSDS no longer than 80 bytes, since some of the information that fills the PSDS after 80 bytes is costly to obtain. If the PSDS is not coded, or is too short to contain the date and time the program started, these two values will not be available in a formatted dump. All other PSDS values will be available, no matter how long the PSDS is. 5.
Differences Between OPM RPG/400 and ILE RPG In ILE RPG, the total number of program devices that can be acquired by the program cannot be different from the maximum number of devices defined in the device file. OPM RPG/400 allows this through the NUM option. 7. In ILE RPG, the ACQ and REL operation codes can be used with single device files. 8.
Differences Between OPM RPG/400 and ILE RPG give different results than expected when DDS features are used that cause more than one search argument to match a given key in the file. For example, if ABSVAL is used on a numeric key, both -1 and 1 would succeed as search arguments for a key in the file with a value of 1. Using the hexadecimal collating sequence, a search argument of -1 will not succeed for an actual key of 1.
Differences Between OPM RPG/400 and ILE RPG ¹ The user has not specified that a transparency check should be performed by the compiler In ILE RPG, if there are two consecutive apostrophes enclosed within shift-out and shift-in control characters inside a character literal, the apostrophes will not be considered as a single apostrophe. A pair of apostrophes inside a character literal will only be considered as a single apostrophe if they are not enclosed within shift-out and shift-in control characters. 3.
Conversion Overview Appendix B. Using the RPG III to RPG IV Conversion Aid The RPG IV source specification layouts differ significantly from the System/38 environment RPG III and the OPM RPG/400 layouts. For example, the positions of entries on the specifications have changed and the types of specifications available have also changed. The RPG IV specification layouts are not compatible with the previous layouts.
Conversion Overview File Considerations The Conversion Aid operates on file members. This section presents information on different aspects of files that must be taken into consideration when using the Conversion Aid. Source Member Types Table 30 lists the various source member types, indicates whether the member type can be converted, and indicates the output source member type. Table 30.
Conversion Overview If the converted source file has a record length less than 92 characters then an error message will be issued and the conversion will stop. This is because the record length is not long enough to contain the 80 characters allowed for source code and so some code is likely to be lost. File and Member Names The unconverted member and the member for the converted output can only have the same name if they are in different files or libraries.
Converting Your Source In addition to object-authority requirements, there may be additional storage requirements. Each converted source program is, on average, about 25 percent larger than the size of the program before conversion. To use the Conversion Aid you need sufficient storage to store the converted source files. What the Conversion Aid Won't Do ¹ The Conversion Aid does not support conversion from the RPG IV format back to the RPG III or RPG/400 format.
Converting Your Source 5. Check the log file or the error report for any errors. For more information, see “Analyzing Your Conversion” on page 393. 6. If there are errors, correct them and go to step 4 on page 382. 7. If there are no errors, create your program. For information on how to create ILE RPG programs, see Chapter 6, “Creating a Program with the CRTBNDRPG Command” on page 57. 8.
Converting Your Source ┌─*LIBL/────────┐ ┌─source-file-member-name─┐ 55──CVTRPGSRC──FROMFILE──(──┼───────────────┼────source-file-name────)──FROMMBR──(──┼─*ALL────────────────────┼──)─────5 ├─*CURLIB/──────┤ └─generic*-member-name────┘ └─library-name/─┘ (P) ──────5 5──┬───────────────────────────────────────────────────────────┬──┬──────────────────────────────────────────┬─── │ ┌─*LIBL/────────┐ ┌─QRPGLESRC────────┐ │ │ ┌─*FROMMBR────────────────┐ │ └─TOFILE──(──┬─┼───────────────┼──┴─source-file-name─┴─┬
Converting Your Source source-file-member-name Enter the name of the source member to be converted. *ALL The command converts all the members in the source file specified. generic*-member-name Enter the generic name of members having the same prefix in their names followed by a '*' (asterisk). The command converts all the members having the generic name in the source file specified. For example, specifying FROMMBR(PR*) will result in the conversion of all members whose names begin with 'PR'.
Converting Your Source the source members in the FROMFILE are converted. The converted source members have the same names as those of the original source members. If a generic name is specified in the FROMMBR parameter, then all the source members specified having the same prefix in their names are converted. The converted source members have the same names as those of the original generic source members. source-file-member-name Enter the name of the converted source member.
Converting Your Source LOGFILE Specifies the name of the log file that is used to track the conversion information. Unless *NONE is specified, there must be a log file. The file must already exist, and it must be a physical data file. Create the log file by using the CPYF command with the "From object" file QARNCVTLG in library QRPGLE and the "New object" file QRNCVTLG in your library. QRNCVTLG The default log file QRNCVTLG is used to contain the conversion information.
Converting Your Source Converting All Members in a File You can convert all of the members in a source physical file by specifying FROMMBR(*ALL) and TOMBR(*FROMMBR) on the CVTRPGSRC command. The Conversion Aid will attempt to convert all members in the file specified. If one member should fail to convert, the conversion process will still continue.
Converting Your Source Using the TOFILE(*NONE) parameter stops the Conversion Aid from generating a converted member, but still allows it to produce a conversion report. For more information on the conversion report, see “Analyzing Your Conversion” on page 393. Obtaining Conversion Reports The Conversion Aid normally produces a conversion report each time you issue the command. The name of the spooled file corresponds to the file name specified in the TOFILE parameter.
Example of Source Conversion Converting Source Members with Embedded SQL When converting code that contains embedded SQL and the SQL code is continued over multiple lines, the following will occur: ¹ If there are continuation lines but column 74 is blank, the line is simply copied to the ILE member. Note: This could be a problem if column 74 happens to be a blank character inside a character string.
Example of Source Conversion H FFILE1 IF E DISK FQSYSPRT O F 132 OF LPRINTER LQSYSPRT 60FL 56OL E ARR1 3 3 1 E ARR2 3 3 1 IFORMAT1 I OLDNAME I* DATA STRUCTURE COMMENT IDS1 DS I 1 I* NAMED CONSTANT COMMENT I 'XYZ' C I 4 C ARR1,3 DSPLY C READ FORMAT1 C NAME DSPLY C SETON C EXCPTOUTPUT OQSYSPRT E 01 OUTPUT O ARR2,3 10 TSTPGM COMM1 COMM2 NAME 3 FIELD1 CONST1 6 ARR1 COMM3 01 LR ** 123 ** 456 Figure 194.
Example of Source Conversion 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 .....H*unctions+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++Comments+++++++++ H DFTNAME(TSTPGM) .....F*ilename++IPEASFRlen+LKlen+AIDevice+.Functions++++++++++++++++++++++++++++Comments+++++++++ FFILE1 IF E DISK COMM1 FQSYSPRT O F 132 PRINTER OFLIND(*INOF) F FORMLEN(60) F FORMOFL(56) .....D*ame+++++++++++ETDsFrom+++To/L+++IDc.
Analyzing Your Conversion ¹ Record address file (RAF) entries on extension specifications have been replaced by the keyword RAFDATA on the File Description specification. ¹ The line counter specifications have been eliminated. They have been replaced by the keywords FORMLEN and FORMOFL on the file description specification. See Lines 6 and 7. ¹ All specification types have been expanded to allow for 10-character names for fields and files.
Analyzing Your Conversion Using the Conversion Report The Conversion Aid generates a conversion report if you specify the CVTRPT(*YES) parameter on the CVTRPGSRC command. The spooled file name is the same as the file name specified on the TOFILE parameter. The conversion report consists of four parts: 1. CVTRPGSRC command options 2. source section 3. message summary 4. final summary The first part of the listing includes a summary of the command options used by CVTRPGSRC.
Analyzing Your Conversion 5769RG1 V4R4M0 990521 From file . . . . . To file. . . . . . . Log file . . . . . . Sequence Number 000002 *RNM0511 000003 *RNM0508 000004 *RNM0506 RN IBM ILE RPG AS400S01 12/30/99 20:41:35 Page 2 . . . . . . : MYLIB/QRPGSRC(REPORT) . . . . . . : MYLIB/QRPGLESRC(REPORT) . . . . . . : *NONE C o n v e r s i o n R e p o r t <----------------------- Source Specifications ---------------------------><-------------- Comments --------------> Page ....1....+....2....+....3....+....4....
Analyzing Your Conversion F i n a l S u m m a r y Message Totals: Information (00) . . . . . . . : 2 Warning (10) . . . . . . . : 0 Severe Error (30+) . . . . . . : 1 --------------------------------- ------Total . . . . . . . . . . . . . : 3 Source Totals: Original Records Read . . . . . . : 3 Converted Records Written . . . . : 4 Highest Severity Message Issued . : 30 * * * * * E N D O F F I N A L S U M M A R Y * * * * * * * * * * E N D O F C O N V E R S I O N * * * * * Figure 199.
Analyzing Your Conversion A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A A R QRNCVTFM LGCENT 1A LGDATE 6A LGTIME 6A LGSYST 8A LGUSER 10A LGFRFL 10A LGFRLB 10A LGFRMR 10A LGFRMT 10A LGTOFL 10A LGTOLB 10A LGTOMR 10A LGTOMT 10A LGLGFL 10A LGLGLB 10A LGLGMR 10A LGCEXP 1A LGERRL 1A LGSECL 1A LGINSR 1A LGSTAT 2A LGMRDS 50A COLHDG('CVT' 'CENT') TEXT('Conversion Century: 0-20th 1-+ 21st') COLHDG('CVT' 'DATE') TE
Resolving Conversion Problems Resolving Conversion Problems Conversion problems may arise for one or more of the following reasons: ¹ The RPG III source has compilation errors ¹ Certain features of the RPG III language are not supported by RPG IV ¹ One or more /COPY compiler directives exists in the RPG III source ¹ Use of externally described data structures ¹ Behavioral differences between the OPM and ILE run time Each of these areas is discussed in the sections which follow.
Resolving Conversion Problems Merging Problems Because of differences between the RPG III and RPG IV languages, the Conversion Aid must reorder certain source statements. An example of this reordering is shown in “Example of Source Conversion” on page 390 for the RPG III source member TEST1. If you compare the placement of the data structure DS1 in Figure 194 on page 391 and in Figure 195 on page 392, you can see that the data structure DS1 was moved so that it precedes the record format FORMAT1.
Resolving Conversion Problems There are two methods of correcting this type of problem: 1. Use the EXPCPY(*YES) option of the CVTRPGSRC command to include all /COPY members in the converted RPG IV source member. This approach is easy and will work most of the time. However, including the /COPY members in each source member reduces the maintainability of your application. 2. Manually correct the code after conversion using the information in the ILE RPG compiler listing and the ILE RPG for AS/400 Reference.
Resolving Conversion Problems ¹ In renaming an externally described data structure field or an externally described file field I* I* I* I* I* I* I* I If the RPG III source member contains only the source statement describing field CHAR below, the Conversion Aid is unsure how to convert it.
Resolving Conversion Problems Merging an Array with an Externally Described DS Subfield As mentioned earlier, you are not allowed to define a standalone array and a data structure subfield with the same name in RPG IV. In general, the Conversion Aid will merge these two definitions. However, if the subfield is in an externally described data structure, this merging is not handled and you will be required to manually correct the converted source member.
Resolving Conversion Problems IDSONE I I I C C E DSEXTREC CHARACTER 'XYZ' CHAR DSPLY SETON CHAR CHAR LR Figure 210. RPG III source with renamed and initialized external subfield D DSONE D CHAR D CHAR C CHAR C E DS E E EXTNAME(EXTREC) EXTFLD(CHARACTER) INZ('XYZ') DSPLY SETON LR Figure 211. RPG IV source with two definitions for renamed subfield D DSONE D CHAR C CHAR C E DS E EXTNAME(EXTREC) EXTFLD(CHARACTER) INZ('XYZ') DSPLY SETON LR Figure 212.
Resolving Conversion Problems 404 ILE RPG for AS/400 Programmer's Guide
Reading Syntax Diagrams Appendix C. The Create Commands This section provides information on: ¹ Using CL commands ¹ Syntax diagram and description of CRTBNDRPG ¹ Syntax diagram and description of CRTRPGMOD For information on the Create Program and Create Service Program commands, see the CL Reference (Abridged). Using CL Commands Control Language (CL) commands, parameters, and keywords can be entered in either uppercase or lowercase characters.
CRTBNDRPG Command 55──REQUIRED-PARAMETER──(──┬─PREDEFINED-VALUE───┬──)─────────────────────────────────────5 └─user-defined-value─┘ 5──┬──────────────────────────────────────────────────┬─────────────────────────────────5% └─OPTIONAL-PARAMETER──(──┬─PREDEFINED-VALUE───┬──)─┘ └─user-defined-value─┘ Default values appear above the base line and do not need to be entered. They are used when you do not specify a parameter.
CRTBNDRPG Command 55──CRTBNDRPG──┬────────────────────────────────────────────────┬──────────────────────────────────────────────────────5 │ ┌─*CURLIB/──────┐ ┌─*CTLSPEC─────┐ │ └─PGM──(──┼───────────────┼──┴─program-name─┴──)─┘ └─library-name/─┘ (P) ────────5 5──┬────────────────────────────────────────────────────────┬──┬───────────────────────────────────────────┬─── │ ┌─*LIBL/────────┐ ┌─QRPGLESRC────────┐ │ │ ┌─*PGM────────────────────┐ │ └─SRCFILE──(──┼───────────────┼──┴─source-file-name─┴──)─┘ └─SR
CRTBNDRPG Command OPTION Details: ┌─*XREF───┐ ┌─*GEN───┐ ┌─*NOSECLVL─┐ ┌─*SHOWCPY───┐ ┌─*EXPDDS───┐ ┌─*EXT───┐ ┌─*NOSHOWSKP─┐ ├──┼─────────┼──┼────────┼──┼───────────┼──┼────────────┼──┼───────────┼──┼────────┼──┼────────────┼───────────────────5 └─*NOXREF─┘ └─*NOGEN─┘ └─*SECLVL───┘ └─*NOSHOWCPY─┘ └─*NOEXPDDS─┘ └─*NOEXT─┘ └─*SHOWSKP───┘ | | ┌─*NOSRCSTMT─┐ ┌─*DEBUGIO───┐ ┌─*NOEVENTF─┐ 5──┼────────────┼──┼────────────┼──┼───────────┼───────────────────────────────────────────────────────────────────────┤ └
CRTBNDRPG Command *LIBL The system searches the library list to find the library where the source file is stored. This is the default. *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 ILE RPG source program to be compiled.
CRTBNDRPG Command *YES When this program is called it will always run in the default activation group. The default activation group is the activation group where all original program model (OPM) programs are run. Specifying DFTACTGRP(*YES) allows ILE RPG programs to behave like OPM programs in the areas of override scoping, open scoping, and RCLRSC. ILE static binding is not available when a program is created with DFTACTGRP(*YES).
CRTBNDRPG Command *SHOWCPY Show source records of members included by the /COPY compiler directive. *NOSHOWCPY Do not show source records of members included by the /COPY compiler directive. *EXPDDS Show the expansion of externally described files in the listing and display key field information. *NOEXPDDS Do not show the expansion of externally described files in the listing or display key field information. *EXT Show the list of external procedures and fields referenced during the compile on the listing.
CRTBNDRPG Command | | *NODEBUGIO Do not generate breakpoints for input and output specifications. *NOEVENTF Do not create an Event File for use by CoOperative Development Environment/400 (CODE/400). CODE/400 uses this file to provide error feedback integrated with the CODE/400 editor. An Event File is normally created when you create a module or program from within CODE/400. *EVENTF Create an Event File for use by CoOperative Development Environment/400 (CODE/400).
CRTBNDRPG Command | *ALL Generates the listing, source and copy views for debugging the compiled program object. The information contained in the listing view is dependent on whether *SHOWCPY, *EXPDDS, and *SRCSTMT are specified for the OPTION parameter. *NONE Disables all of the debug options for debugging the compiled program object. OUTPUT Specifies if a compiler listing is generated. | *PRINT Produces a compiler listing, consisting of the ILE RPG program source and all compile-time messages.
CRTBNDRPG Command CVTOPT Specifies how the ILE RPG compiler handles date, time, timestamp, graphic data types, and variable-length data types which are retrieved from externally described database files. *NONE Ignores variable-length database data types and use the native RPG date, time, timestamp and graphic data types. *DATETIME Specifies that date, time, and timestamp database data types are to be declared as fixed-length character fields.
CRTBNDRPG Command library-name Enter the name of the library where the sort sequence table is stored. LANGID Specifies the language identifier to be used when the sort sequence is *LANGIDUNQ and *LANGIDSHR. The LANGID parameter is used in conjunction with the SRTSEQ parameter to select the sort sequence table. *JOBRUN Use the LANGID value associated with the job when the RPG program is executed. *JOB Use the LANGID value associated with the job when the RPG program is created.
CRTBNDRPG Command cific authority to the object. The authority can be altered for all users or for specified users after the program is created with the CL commands Grant Object Authority (GRTOBJAUT) or Revoke Object Authority (RVKOBJAUT). For further information on these commands, see the CL Reference (Abridged) *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.
CRTBNDRPG Command *NO When numeric overflow is detected, a run time error is generated with error code RNX0103. FIXNBR Specifies whether decimal data that is not valid is fixed by the compiler. *NONE Indicates that decimal data that is not valid will result in decimal data errors during run time if used. *ZONED Zoned-decimal data that is not valid will be fixed by the compiler on the conversion to packed data. Blanks in numeric fields will be treated as zeroes.
CRTBNDRPG Command Valid values depend on the current version, release, and modification level, and they change with each new release. If you specify a target-release that is earlier than the earliest release level supported by this command, an error message is sent indicating the earliest supported release. | | | | | | Note: The current version of the command may support options that are not available in previous releases of the command.
CRTBNDRPG Command *LIBL The system searches the library list to find the library where the binding directory is stored. *CURLIB The current library for the job is searched. If no library is specified as the current library for the job, library QGPL is used. *USRLIBL Only the libraries in the user portion of the job's library list are searched. library-name Specify the name of the library to be searched. ACTGRP Specifies the activation group this program is associated with when it is called.
CRTRPGMOD Command condition-name Up to 32 condition names can be specified. Each name can be up to 50 characters long. The condition names will be considered to be defined at the start of compilation. PRFDTA Specifies the program profiling data attribute for the program. Program profiling is an advanced optimization technique used to reorder procedures and code within the procedures based on statistical data (profiling data). *NOCOL This program is not enabled to collect profiling data.
CRTRPGMOD Command 55──CRTRPGMOD──┬──────────────────────────────────────────────────┬────────────────────────────────────────────────────5 │ ┌─*CURLIB/──────┐ ┌─*CTLSPEC────┐ │ └─MODULE──(──┼───────────────┼──┴─module-name─┴──)─┘ └─library-name/─┘ (P) ────────5 5──┬────────────────────────────────────────────────────────┬──┬───────────────────────────────────────────┬─── │ ┌─*LIBL/────────┐ ┌─QRPGLESRC────────┐ │ │ ┌─*MODULE─────────────────┐ │ └─SRCFILE──(──┼───────────────┼──┴─source-file-name─┴──)─┘ └─S
CRTRPGMOD Command OPTION Details: ┌─*XREF───┐ ┌─*GEN───┐ ┌─*NOSECLVL─┐ ┌─*SHOWCPY───┐ ┌─*EXPDDS───┐ ┌─*EXT───┐ ┌─*NOSHOWSKP─┐ ├──┼─────────┼──┼────────┼──┼───────────┼──┼────────────┼──┼───────────┼──┼────────┼──┼────────────┼───────────────────5 └─*NOXREF─┘ └─*NOGEN─┘ └─*SECLVL───┘ └─*NOSHOWCPY─┘ └─*NOEXPDDS─┘ └─*NOEXT─┘ └─*SHOWSKP───┘ | | ┌─*NOSRCSTMT─┐ ┌─*DEBUGIO───┐ ┌─*NOEVENTF─┐ 5──┼────────────┼──┼────────────┼──┼───────────┼───────────────────────────────────────────────────────────────────────┤ └
Compiler Listings Appendix D. Compiler Listings Compiler listings provide you with information regarding the correctness of your code with respect to the syntax and semantics of the RPG IV language. The listings are designed to help you to correct any errors through a source editor; as well as assist you while you are debugging a module. This section tells you how to interpret an ILE RPG compiler listing. See “Using a Compiler Listing” on page 63 for information on how to use a listing.
Compiler Listings Table 32 (Page 2 of 2). Sections of the Compiler Listing | Listing Section1 OPTION2 Description Code generation errors3 Errors (if any) which occur during code generation phase. Binding section3 Errors (if any) which occur during binding phase for CRTBNDRPG command Notes: | | | | | | 1. The information contained in the listing section is dependent on whether *SRCSTMT or *NOSRCSTMT is specified for the OPTION parameter.
Compiler Listings | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 5769RG1 V4R4M0 990521 RN Command . . . . . . . . . Issued by . . . . . . . Program . . . . . . . . . Library . . . . . . . . Text 'description' . . . . Source Member . . . . . . Source File . . . . . . . Library . . . . . . . . CCSID . . . . . . . . . Text 'description' . . . . Last Change . . . . . . . Generation severity level Default activation group . Compiler options . . . . . . . . . . . . . . . . . . . .
Compiler Listings Source Section The source section shows records that comprise the ILE RPG source specifications. The root source member records are always shown. If OPTION(*EXPDDS) is also specified, then the source section shows records generated from externally described files, and marks them with a '=' in the column beside the line number. These records are not shown if *NOEXPDDS is specified.
Compiler Listings | | | | | | | | | | | | | | | | | | with the next sequence number in the listing: sequence number 001700. The three intervening lines are assigned the SEU sequence numbers from the /COPY source member. The corresponding statement numbers are genereated from source IDs and SEU sequence numbers of the root and /COPY source members. <--------------------- Source Specifications ----------------------------------------------><---- Comments ----> Statement ....1....+....2....
Compiler Listings | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 5769RG1 V4R4M0 990521 RN IBM ILE RPG MYLIB/MYSRC AS400S01 98/07/28 14:21:00 .1a/ Line <---------------------- Source Specifications ----------------------------><---- Comments ----> Do Page Number ....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+...
Compiler Listings | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | *--------------------------------------------------------------------------------------------* * Data structure . . . . . . : DSEXT1 * * Prefix . . . . . . . . . . : BI_ : 0 * * External format . . . . . : REC1 : MYLIB/DSEXT1 * * Format text . . . . . . .
Compiler Listings | | | | | | | | | | | Line <---------------------- Source Specifications ----------------------------><---- Comments ----> Do Page Change Src Seq Number ....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+...10 Num Line Date Id Number 57=OOUTREC 6000001 *--------------------------------------------------------------------------------------------* 6 * RPG record format . . . . : OUTREC * 6 * External format . . . . .
Compiler Listings | | | Statement Number Shows the statement number generated from the source ID number and the SEU sequence number as follows: | stmt_num = source_ID * 1000000 + source_SEU_sequence_number | Use this number when debugging using statement numbers. .2/ Compiler Options in Effect Identifies the compiler options in effect. Displayed when compile-option keywords are specified on the control specification. .
Compiler Listings | | | | | | | | | A d d i t i o n a l D i a g n o s t i c M e s s a g e s Sv Number Seq Message text 00 8 000800 Record-Format REC1 not used for input or output. 00 8 000800 Record-Format REC2 not used for input or output. 00 60 000004 RPG handles blocking for file INFILE. INFDS is updated only when blocks of data are transferred. *RNF7086 00 60 000004 RPG handles blocking for file OUTFILE. INFDS is updated only when blocks of data are transferred.
Compiler Listings Compile-Time Data The Compile-Time Data section includes information on ALTSEQ or NLSS tables, and on tables and arrays. In this example, there is an alternate collating sequence and two arrays, as shown in Figure 222.
Compiler Listings Key Field Information The Key Field Information section shows information about key fields for each keyed file. It also shows information on any keys that are common to multiple records (that is, common keys). Figure 223 shows an example.
Compiler Listings | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | C r o s s R e f e r e n c e File and Record References: File Device References (D=Defined) Record CUSTFILE DISK 8D CUSTREC 0 44 *RNF7031 CUSTRPT DISK 9D ARREARS 0 60 79 Global Field References: Field Attributes References (D=Defined M=Modified) *INZSR BEGSR 63D AMOUNT P(10,2) 56M 83 95 CITY A(20) 53D 132 CURDATE D(10*ISO-) 42D 64M 92 CUSTNAME A(20) 50D 122 CUSTNUM P(5,0) 49D 124 DU
Compiler Listings E x t e r n a l R e f Statically bound procedures: Procedure PROTOTYPED PADDR_PROC CALLB_PROC Imported fields: Field Attributes IMPORT_FLD P(5,0) Exported fields: Field Attributes EXPORT_ARR(2) A(5) * * * * * E N D O F E X T E R N A L e r e n c e s References 2 4 6 2 Defined 3 Defined 2 R E F E R E N C E S * * * * * Figure 225. Sample External References Message Summary The message summary contains totals by severity of the errors that occurred.
Compiler Listings | | | | | | | | | | | | | | | | F i n a l S u m m a r y Message Totals: Information (00) . . . . . . . : 20 Warning (10) . . . . . . . : 0 Error (20) . . . . . . . : 0 Severe Error (30+) . . . . . . : 0 --------------------------------- ------Total . . . . . . . . . . . . . : 20 Source Totals: Records . . . . . . . . . . . . : 71 Specifications . . . . . . . . : 55 Data records . . . . . . . . . : 8 Comments . . . . . . . . . . .
Compiler Listings 438 ILE RPG for AS/400 Programmer's Guide
Bibliography For additional information about topics related to ILE RPG programming on the AS/400 system, refer to the following IBM AS/400 publications: ¹ ADTS/400: Application Development Manager User's Guide, SC09-2133-01, describes creating and managing projects defined for the Application Development Manager feature as well as using the program to develop applications.
embedded SQL statements. Contains examples of SQL statements and a description of the interactive SQL function. Describes common concepts and rules for using SQL statements in COBOL/400, ILE COBOL, PL/I, ILE C, FORTRAN/400, RPG/400, ILE RPG, and REXX. ¹ DB2 UDB for AS/400 SQL Reference, SC41-5612-02, provides information about how to use Structured Query Language DB2 UDB for AS/400 statements and gives details about the proper use of the statements.
¹ ILE RPG for AS/400 Reference Summary, SX09-1315-01, provides information about the RPG III and RPG IV programming language. This manual contains tables and lists for all specifications and operations in both languages. A key is provided to map RPG III specifications and operations to RPG IV specifications and operations. ¹ Printer Device Programming, SC41-5713-03, provides information to help you understand and control printing.
442 ILE RPG for AS/400 Programmer's Guide
Index Special Characters /COPY statement conversion problems 389, 398 COPY debug view 168 in a conversion report 394 table in compiler listing 432 *CANCL 237 *DETC 237 *DETL 237 *EXTDFT example 427 in compiler listing 431 *GETIN 237 *JOB sort sequence, SRTSEQ 414 *JOBRUN language identifier, LANGID 415 sort sequence, SRTSEQ 414 *OFL 237 *PSSR See program exception/error subroutine *TOTC 237 *TOTL 237 *USER user profile, USRPRF 415 %ADDR (Get Address of Variable) omitted parameters 140 %ADDR debug built-in 2
array conversion problems 402 displaying while debugging 202 loading 403 prerun-time arrays 403 arrival sequence access path 282 ATTR debug command definition 164 example 210 using 210 audit file 381 See also log file AUT parameter CRTBNDRPG command 58, 415 CRTRPGMOD command 74 authority to commands xv auto report program converting to ILE RPG 389 avoiding a loop in an error subroutine 235 B behavior of bound ILE RPG modules 80 behavioral differences between OPM RPG/400 and ILE RPG 373 bibliography 439 bi
call operations (continued) free-form call 133, 134 query names of called procedures 149 special routines 157 using 133 call stack 129, 218 Call Stack Entry Termination User Exit Procedure (CEEUTX) 244 CALLB (call a bound procedure) operation code calling programs 148 using 148 *CALLER 111 calling a graphics routine 156 calling programs/procedures abnormal program/procedure end 153 call stack 129 calling bindable APIs 155 calling graphics 156 calling procedures 128 calling programs 128 calling special routi
CL commands (continued) DSPPGMREF 149 End Debug (ENDDBG) 170 module-related 80 MONMSG 247 program-related 85 RCLACTGR 110 RCLRSC 112 reading syntax diagrams 405 Remove Program (RMVPGM) 172 Start Debug (STRDBG) 170, 171 UPDPGM 87 using 405 WRKRPLYE 109 clear command 334 CLEAR debug command definition 164 removing all 188 using 179, 182, 187 code conversion constraints 398 code generation errors in compiler listing 437 collating sequence See alternate collating sequence combined file 341 command attention (CA
control-record format, subfile 335 Conversion Aid See converting to RPG IV conversion reports obtaining 389 sections of 394 using 394 conversion, analyzing 393 converting to RPG IV analyzing your conversion 393 constraints 382 conversion problems 398 converting 382 converting all file members 388 converting auto report source members 389 converting some file members 388 converting source from a data file 390 converting source members with embedded SQL 390 CVTRPGSRC command 383 example 390 file and member na
CRTPGM command See Create Program (CRTPGM) command CRTRPGMOD command See Create RPG Module (CRTRPGMOD) command CRTRPTPGM (create auto report program) command converting auto report members 389 CRTSRVPGM command See Create Service Program (CRTSRVPGM) command CVTOPT parameter CRTBNDRPG command 58, 414 CRTRPGMOD command 74 CVTRPGSRC (Convert RPG Source) command default parameter values 383 example 388 parameter description 384 syntax diagram 383 using the command defaults 387 CVTRPT parameter 386, 389, 394 cyc
debugging (continued) displaying fields as hexadecimal values 205 displaying fields in character format 205 displaying fields in UCS-2 format 206 displaying fields in variable-length format 206 displaying indicators 204 displaying multiple-occurrence data structures 203 displaying the contents of a table 202 displaying the contents of an array 202 general discussion 163 National Language Support 211 NLSS considerations 183 obtaining a formatted dump 251 OPM program limit in debug session 172 optimization ef
DISK file (continued) program-described (continued) processing 291 record-address file 290 sequential file 290 record-format specifications 282 DISPLAY debug command definition 164 using 175 viewing shorthand names 211 Display Module (DSPMOD) command 149 Display Module Source (DSPMODSRC) command 172, 173, 175 Display Program (DSPPGM) command determining optimization level 88 Display Program References (DSPPGMREF) command 149 Display Service Program (DSPSRVPGM) command 91 displaying attributes of a field 210
EVAL debug command (continued) using 199 event file for CODE/400 411 examples compiling binding multiple modules 84 OPM-compatible program 61 program for source debugging 59 program with static binding 60 sample binder listing 100 service program 94 converting to RPG IV all members in a file 388 performing a trial conversion 388 sample conversion 390 some members in a file 388 debugging adding a service program to a session 173 changing field values 209 changing the debug view of a module 176 displaying att
externally described file (continued) file description specifications for 265 output specifications for 269 overriding 267 physical and logical files 281 record format specifications 282 renaming field names 266 renaming record format 266 specifications 265 F fetch overflow See also overflow (OA-OG, OV) indicators general description 320 logic 320 field changing the value while debugging 208 displaying attributes of while debugging 210 displaying while debugging as hexadecimal values 205 in character forma
G GDDM 156 generating a program See compiling See control specifications GENLVL parameter CRTBNDRPG command 58, 409 CRTRPGMOD command 74 Get Descriptive Information About a String Argument (CEESGI) 139 Get Heap Storage (CEEGTST) bindable API 20, 120 graphic format graphic CCSID indicated in compiler listing 428 NLSS debug considerations 183 rules for assigning values using EVAL 208 graphic support 156 Graphical Data Display Manager(GDDM) 156 H H1-H9 See halt (H1-H9) indicators halt (H1-H9) indicators used
indicators See also individual operation codes as error indicators 227 displaying while debugging 204 error 227 function key (KA-KN, KP-KY) with WORKSTN file 334 halt (H1-H9) used to end a program/procedure 152, 153, 154 last record (LR) general description 5 used to end a program/procedure 152, 153, 154 overflow examples 319, 320 fetch overflow logic 320 general description 316 presence or absence of 317 relation to program cycle 320 setting of 320 with PRINTER file 316 return (RT) used to end a program/pr
listing view, creating 168 listing, binder as maintenance resource 86 basic 100 creating 85 determining exports in service program 91 sections of 85 listing, compiler additional diagnostic messages 68 browsing using SEU 68 coordinating listing options with debug view options 69 correcting compilation errors 66 correcting run-time errors 68 default information 63 in-line diagnostic messages 67 indenting structured operations 65 obtaining 63 reading 423 sample listing 424 sections of 63, 424 specifying the fo
MODULE parameter 82 CRTBNDRPG command 408 CRTRPGMOD command 74 multiple devices attached to application program multiple-device file WORKSTN 342 310 N name(s) See long names named activation group 110 National Language Support (NLS) of source debugger 211 nested exceptions 223 *NEW 110 no debug data 166 NOMAIN module coding considerations 46 creating 75 nonkeyed processing 304 NOOPT keyword and handling exceptions 226 maintaining current values while debugging 164 program optimization level 87 normal prog
overrides, file 267 example 274 general discussion 273, 304 indicated in compiler listing 425 overriding external description 267 P page headings 64 page number, in PRINTER file 316 page overflow, in PRINTER file 316 parameter descriptions CRTBNDRPG command 408 CRTRPGMOD command 422 CVTRPGSRC command 384 parameter list See also PARM (identify parmeters) operation code created by PARM 151 identifying 131 rules for specifying 151 parameter table CRTBNDRPG command 58 CRTRPGMOD command 74 CVTRPGSRC command 383
processing methods (continued) sequential only 293, 304 sequential-by-key 293 sequential-within-limits 300 WORKSTN file 335, 341 program abnormal ending 153 advanced ILE 30 binding modules 81 calling 127, 128 calling using expressions 134 calling using the CALL operation 148 calling using the CALLP operation 133 changing 86 changing optimization level 87 changing while debugging 175 different debug views 176 effect of debug data on size 166 ending 109 entering source 51 entering SQL statements 55 example 6
program/procedure call (continued) recursive calls 130 returning from a called program or procedure returning values 134 returning without ending 154 static calls 128 using the CALL operation 148 using the CALLB operation 148 within ILE 19 program/procedure end abnormal end 153 after system call 109 normal end 152 return overview 152 returning without ending 154 using bindable APIs 155 programming tips creating NOMAIN module 92 setting subprocedure breakpoints 196 prologue section of compiler listing 424 pr
removing observability 88 RENAME keyword 266 renaming field names 266 renaming fields 266 renaming record-format names 266 REPLACE parameter CRTBNDRPG command 58, 415 CRTRPGMOD command 74 replacing modules in a program 87 reply list of messages adding to 108 changing 109 replying to run-time inquiry messages 108 requirements of Conversion Aid 381 reserved words *CANCL 237 *DETC 237 *DETL 237 *GETIN 237 *OFL 237 *TOTC 237 *TOTL 237 resulting indicators (01-99, H1-H9, OA-OG, OV, L1-L9, LR, U1-U8, KA-KN, KP-KY
service program (continued) binding with CRTBNDRPG 60 changing 93 creating 91 example 94 in advanced application 30 reasons for using 91 reclaiming resources 112 related CL commands 93 sample binder listing 100 strategies for creating 92 updating 100 service program creation about 91 strategies 92 SET debug command definition 164 setting breakpoints about 177 conditional job breakpoints 181 conditional thread breakpoints 187 example 179, 182 unconditional job breakpoints 178 unconditional thread breakpoints
specifying a return point 237 specifying an activation group 110 specifying error indicators 227 specifying the format of compiler listing 64 spooling 278 SQL See DB2 for AS/400 SQL SRCFILE parameter CRTBNDRPG command 58, 408 CRTRPGMOD command 74 SRCMBR parameter CRTBNDRPG command 58, 409 CRTRPGMOD command 74 SRTSEQ parameter affect on key comparisons 279 CRTBNDRPG command 58, 414 CRTRPGMOD command 74 debug considerations 183 stack, call 129, 218 Start Debug (STRDBG) command 170 Update Production files (UPD
T table See also array displaying while debugging 202 table of parameters CRTBNDRPG command 58 CRTRPGMOD command 74 CVTRPGSRC command 383 tape file 290 TBREAK debug command definition 165 using 180, 187 templates, inserting specification 390 teraspace memory 148 test library, using 171 testing breakpoints 178 TEXT parameter CRTBNDRPG command 58, 409 CRTRPGMOD command 74 TGTRLS parameter CRTBNDRPG command 58, 417 CRTRPGMOD command 74 THREAD debug command definition 165 using 180 threaded applications coding
WORKSTN file definition 331 examples 345 externally described processing 335 externally-described 331 file operation codes allowed with 341 function key indicators with 334 multiple-device 342 processing 341 program-described calculation specifications 340 combined file 341 considerations 340 general 338 input file 341 input specifications 340 output file 341 output specifications 339 with format name 339 without format name 340 sample data maintenance program 349 sample inquiry and search program 364 sampl
ÉÂÔÙ Part Number: 99H3778 Program Number: 5769-RG1 99H3778 Printed in U.S.A.
