ILE RPG/400

CONTENTS
1.

Introduction to ILE 1.1. What is ILE? 1.2. Advantages of ILE 1.3. History of ILE 1.3.1. Original program model (OPM) 1.3.2. Extended program model (EPM) 1.3.3. Integrated language Environment (ILE) ILE Concepts 1.4.1. Procedures 1.4.2. Module 1.4.3. ILE program 1.4.4. ILE service program 1.4.5. Binding directory 1.4.6. Activation 1.4.7. Activation group Introduction to ILE RPG/400 programming 2.1. RPGIV specifications 2.2. Cycle programming 2.3. Example of an ILE RPGIV program 2.4. ILE Improvements over OPM to RPGIV users 2.4.1. Program creation (Compilation) 2.4.1.1. Create a program usign CRTBNDRPG to maximize OPM compatibility 2.4.1.2. Create an ILE program using CRTBNDRPG 2.4.1.3. Create an ILE program using CRTRPGMOD and CRTPGM 2.4.1.4. Compiler listing 2.4.2. Program management 2.4.3. Program call (Execution) 2.4.3.1. Parameter passing syle 2.4.4. Source debugging 2.4.5. Bindable application program interface(APIs) 2.5. Data types Op-Code variations in ILE RPG/400 over RPG/400 3.1. Arithmetic operations 3.2. Branching operations 3.3. Call operations 3.4. Date operations 3.5. Moving Date-Time data 3.6. Operations using Expressions 3.7. Message operation 3.8. String operations 3.9. Structured programming operations File handling in ILE RPG/400 4.1. Changes in File declaration 4.1.1. Renaming a record format name of externally described file 4.1.2. Renaming a field name 4.1.3. Ignoring record format names in logical file 4.1.4. Declaring overflow indicator 4.1.5. Decalring a subfile 4.2. Record Locking and Relative-Record-Number processing 4.3. Using Commitment Control Data structures
Page No.

1.4.

2.

3.

4.

5.

AS/400-RPGLE-SN-2.0

ILE RPG/400 5.1. Uses of Data structure

5.1.1. Divide a field into subfield 5.1.2. Group fields 5.1.3. Define externally described data structure 5.1.4. Define data area data structure 5.1.5. Define multiple occurance data structure 5.2. Program-described and Externally-described data structure 5.3. Special data structures 5.3.1. Data area data structure 5.3.2. File inforamtion data structure 5.3.3. Program-status data structure
6.

Arrays and Table processing 6.1. Differences between Arrays and Tables 6.2. Arrays 6.2.1. Prerun-time arrays 6.2.2. Compile-time arrays 6.2.3. Run-time arrays 6.3. Searching Arrays 6.3.1. Searching an Array without an Index 6.3.2. Searching an Array with an Index 6.4. Sorting an Array 6.5. How Tables differs from Array in coding Pointers 7.1. Understanding pointers 7.2. Declaring a pointer data type 7.3. Dynamic memory allocation 7.4. Pointers to functions Exception and Error handling 8.1. Difference between OPM and ILE RPG/400 Exception handling 8.2. Using RPG-Specific Handlers 8.2.1.Specifying error indicators 8.2.2.Using a File Error ( INFSR ) subroutine 8.2.3 Using a Program Error Subroutine Built-in functions

7.

8.

9.

1.
AS/400-RPGLE-SN-2.0

INTRODUCTION TO ILE
Page No.

ILE RPG/400

1.1. What is ILE?

ILE is a set of tools and associated system support designed to enhance program development on the AS/400 system. These capabilities can be exploited by programs produced by the new ILE family of compilers which includes ILE C/400 , ILE RPG/400, ILE COBOL/400, ILE CL.

1.2. Advantages of ILE

1.

Binding: Binding the modules together speeds up the call. The ILE call method is referred to as a static or bound procedure call. The binding capability makes it far more practical to develop applications in a highly modular fashion. Modularity: 1. Faster compile time 2. Simplified maintenance 3. Simplified testing 4. Better use of programming resources 5. Easier migrating of code from other platforms

2.

3.

Coexistence with Existing Applications: ILE programs can call OPM programs and other ILE programs. Similarly , OPM programs can call ILE programs and other OPM programs. Source Debugger: The source debugger allows to debug the ILE programs and service programs. Better control over resources: Under ILE, a resource can be scoped to any of the following
a) A Program b) An activation group c) The Job

4.

5.

Shared Open data paths (ODPs) are an example of resources you can better control with ILEs new level of scoping. The ability to scope a shared open data path (ODP) to the application is useful in the area of commitment control.
6.

Better Code Optimization: The ILE translator does many more types of optimization than the Original Program Model (OPM) does. Better environment for C: C has become the language of choice for tool builders. Because of this, a better C language means that more and more of the latest application development tools are migrated to the AS/400. Foundation for the future: As we move into object-oriented programming languages and visual programming tools, the need for ILE becomes even more apparent.

7.

8.

1.3 History of ILE

The programming environment provided when the AS/400 system was introduced is called the original program model (OPM).In version 1 Release 2, the Extended program model(EPM) was introduced. Then the ILE is introduced. The major factors of each programming model is listed below:

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

1.3.1 OPM: 1. Dynamic program call (Simplicity) 2. Single entry point 3. Language controls run-time behavior 4. One Compilation = One program 5. Variables visible across entire program 6. Resources shared across a job 1.3.2 EPM:
1. 2. 3. 4. 5. 6. 7.

Multiple entry points Nested scoping of variables Automatic and static variables External data shared across programs Separate address space Concept of environment Optimal for development tools, OS code, Scientific. Dynamic or static binding Significant new language function(especially RPG) One environment integrates all ILE languages Improved performance for C applications Environment provides run-time behavior OPM and EPM still available

1.3.3. ILE:
1. 2. 3. 4. 5. 6.

1.4 ILE Concepts 1.4.1. Procedures

Procedure is a executable code with an entry point. Called with new CALL BOUND PROCEDURE syntax. Procedures appear on call stack. 3. In ILE RPG/400, even main source is also a procedure.
1. 2.

1.4.2. Module
1. 2. 3. 4. 5. 6. 7. 8. 9.

Output from an ILE compiler Basic building block for ILE runnable objects May have a Program Entry Procedure (PEP) defined If a PEP is defined, a User Entry Procedure (UEP) is also defined. Is not a runnable object. May Export procedure and data item names May import procedure and data item names May have a debug data defined The object is represented as *MODULE

To create a module in ILE RPG/400, Use the following command: CRTRPGMOD MODULE(Name) SRCFILE(Srcfilename) SRCMBR(Member)

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

Example of a module and a procedure in ILE RPG/400: *************** Beginning of data ************************************* 0000.01 * This module does not have a main procedure. This module contains 0000.02 * two procedures display and mult. 0001.00 Hnomain 0001.01 *Protype definition 0001.02 *display take msg parameter of lenght 20 and it does not return any. 0002.01 Ddisplay pr 0003.00 D msg 20a 0003.01 *Mult takes two parameters a and b. It results a value of length 10. 0003.02 Dmult pr 10 0 0003.03 D a 5 0 0003.04 D b 5 0 0003.05 *Procedure definition of display 0004.00 Pdisplay b 0005.00 Ddisplay pi 0006.00 D msg 20a 0007.00 C 'hello world' dsply 0008.00 Pdisplay e 0009.00 *Procedure definition of mult 0010.00 Pmult b 0011.00 Dmult pi 10 0 0012.00 D a 5 0 0013.00 D b 5 0 0014.00 C return a * b 0015.00 Pmult e ****************** End of data **************************************** We can also create modules with main source. Then there is no need to include NOMAIN keyword on the control specification.

1.4.3. ILE Program

1. 2. 3. 4. 5. 6. 7.

One or more modules from any ILE language are copied to make the *PGM object You can control over which modules PEP becomes the one and only PEP for the program On a dynamic program call, the modules PEP that was selected as the PEP for the program gets control to run. procedures and data item names cannot be exported from the program Procedures or data item names can be imported from other ILE objects A program is a runnable object The object is represented as *PGM

After creating one or two modules, you can create a program object by using CRTPGM command. In that command we have to list all the modules which we want to include in that program.

1.4.4. ILE Service Program 1. A service program is a bound program consisting of a set of procedures that can be
called by procedures in other bound programs.

2. No PEP is associated with the service program.. Because there is no PEP, a dynamic call
to a service program is not valid. 3. Signatures are generated from the procedure and data item names that are exported from the service program. The set of exports contained in a service program are the interface to the services provided by it.

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

4. When you bind a service program to a program, the contents of service program are not
copied into the bound program. Instead, linkage information of the service program is bound into the program. 5. The object is represented as *SRVPGM After creating modules required for service program, you can create service program with the CRTSRVPGM command. For example, assume you want to create a service program which contains modules MOD1, MOD2. Then you can use the following command. CRTSRVPGM SRVPGM(service program name) MODULE(modules created for service program) EXPORT(*all). In keyword EXPORT, *all is required to give access to all procedures in modules MOD1 and MOD2. If you dont want to give the user access to all procedures in MOD1 and MOD2, you can control that with the use of binding language. Basically we create service programs to put all our reusable procedures. If any program requires the procedures in service program, while creating that program using CRTPGM include the name of the service program in the parameter value of BNDSRVPGM, and make a simple call to that procedure from your program. There is no need to write the entire procedure next in the program. 1.4.5. Binding Directory

1. Contains the names of modules and service programs that you may need when
creating an ILE program or service program.

2. Is a system object , identified by the symbol *BNDDIR 3. Binding directory entries do not have to exist yet on the system. 4. The named objects are used only if any unresolved imports exist and if the named
objects provides an export to satisfy the unresolved import request. 1.4.6. Activation

1. Is a process used to prepare an ILE program to run. 2. Allocates and initializes static storage for an ILE program 3. Completes the binding of ILE programs to ILE service programs
1.4.7. Activation Group

1. A substructure of a job in which all ILE programs and service programs are
activated 2. Scope resources to the ILE programs 3. Change the symbolic links to used ILE service programs to physical addresses. 4. Ensures that ILE programs running the same job run independently without intruding on each other by scoping resources to the activation group

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

2. INTRODUCTION TO ILE RPG/400 PROGRAMMING

This chapter presents a high-level overview of the RPGIV programming language that distinguish RPG from other programming languages. You should be familiar and comfortable with all of these features before you program in RPGIV language. This part provides information on the following topics that you should know:
2.1. RPGIV specifications 2.2. Cycle programming 2.3. Example of an ILE RPGIV program 2.4.1. ILE Improvements over OPM to RPGIV users

2.4.1. Program creation (Compilation) 2.4.1.1. Create a program usign CRTBNDRPG to maximize OPM compatibility 2.4.1.2. Create an ILE program using CRTBNDRPG 2.4.1.3. Create an ILE program using CRTRPGMOD and CRTPGM 2.4.1.4. Compiler listin 2.4.2. Program management 2.4.3. Program call (Execution) 2.4.3.1. Parameter passing syle 2.4.4. Source debugging 2.4.5. Bindable application program interface(APIs) 2.5. Data types 2.1. RPGIV SPECIFICATIONS: Writing ILE RPG/400 programs requires a knowledge of the specification forms. Many of the entries which make up a specification type are position-dependent. There are seven types of RPGIV specifications. Each specification type is optional. In RPGIV, procedures can be written after main source. Specifications must be entered into your source program in the order shown below. Main source section:
1.

2. 3. 4. 5. 6.

Control specifictions(H) provide the compiler with information about generating and running programs, such as the date format, debugging, and use of alternate collating sequence or file translation. File description specifications(F) describe all the files that your program uses. Definition specifications(D) describe the data(datastructures, arrays, tables) used by program. Input specifications(I) describe the input records and fields used by the program. Calculation specifications( C) describe the calculations done on the data and the order of calculations. Output specifications(O) describe the output records and fields used by the program.

Subprocedure section: Procedure specifications(P) mark the beginning and end of the Subprocedure, indicate the Subprocedure name, and whether it is exported. 2. Definition specifications(D) describe the local data used by the Subprocedure. 3. Calculation specifications( C) describe the calculations done on both the global and local data and the order of calculations.
1. 2.2 CYCLE PROGRAMMING:

The program cycle is a series of steps that your program repeats until an end-of-file condition is reached. When you let the compiler provide the logic for your programs, it is called Cycle programming.

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

No cycle code is generated for subprocedures or when NOMAIN is specified on the control specification. RPG program logic cycle Following explains the logic cycle briefly:
1. 2. 3. 4. 5. 6. 7.

RPG processes all heading and detail lines ( H or D in position 17 of the output specifications). RPG reads the next record and sets on the record identifying and control level indicators. RPG processes total calculations ( conditioned by control level indicators L1 through L9, an LR indicator, or an L0 entry). RPG processes all total output lines( identified by a T in position 17 of the output specifications). RPG determines if the LR indicator is on. If it is on, the program ends. The fields of the selected input records move from the record to a processing area. RPG sets on field indicators. RPG processes all detail calculations ( not conditioned by control level indicators in positions 7 and 8 of the calculation specifications). Go back to step1.

The first and last time through the program cycle differ somewhat from other cycles. There is no cycle code generated for a Subprocedure.
2.3 EXAMPLE OF AN ILERPGIV PROGRAM:

The following program covers the concepts of cycle, Subprocedure and static binding. The logic flow of program(TAXC) is given below: For each record in EMPMSTR Calculate Tax depending on salary. If Tax > 0 Then Print Employee name and Tax computed in printer file. The DDS for EMPMSTR is as follows: *************** Beginning of data ************************************* 0001.00 0002.00 0003.00 0004.00 A A A A R EMPMSTRA ENO 5 0 ENAME 15A ESAL 10 2

****************** End of data ****************************************

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

The ILE RPG code for above requirement is as follows: *************** Beginning of data ************************************* 0001.00 Fempmstr ip e disk 0002.0 0 Fqsysprt o f 80 printer 0003.00 *Declaring a stand alone field(temporary) with length 8 and decimal positions 2 0004.00 Dtax s 8p 2 0005.00 *Declaring a constant 0006.00 DHeading c 'Name Tax ' 0007.00 *Declaring a prototype for procedure 0008.00 Dcalctax pr 8p 2 0009.00 D esal 10p 2 0010.00 *Calling a procedure(Protyped call) 0011.00 C eval tax = calctax(esal) 0012.00 Oqsysprt H 1P 0013.00 O 60 HEADING 0014.00 O D 0015.00 O ENAME 20 0016.00 O TAX 40 '$ 0. ' 0017.00 *Declaring a prototype interface 0018.00 Pcalctax b 0019.00 Dcalctax pi 8p 2 0020.00 D esal 10 2 0021.00 C if esal > 10000 0022.00 C return esal * (25/100) 0023.00 C else 0024.00 C return 0 0025.00 C endif 0026.00 Pcalctax e ****************** End of data ****************************************
2.4. ILE IMPROVEMENTS OVER OPM TO RPGIV USERS

Compared to OPM, ILE provides RPG users with improvements or enhancements in the following areas of application development:
2.4.1.

2.4.2. 2.4.3. 2.4.4. 2.4.5.

Program creation (Compilation) 2.4.1.1. Create a program usign CRTBNDRPG to maximize OPM compatibility 2.4.1.2. Create an ILE program using CRTBNDRPG 2.4.1.3. Create an ILE program using CRTRPGMOD and CRTPGM 2.4.1.4. Compiler listing Program management Program call (Execution) 2.4.3.1. Parameter passing style Source debugging Bindable application program interface(APIs)

2.4.1 Program creation strategies(Compiltaion):

1. 2. 3.

Create a program using CRTBNDRPG to maximize OPM compatibility. Create an ILE program using CRTBNDRPG Create an ILE program using CRTRPGMOD and CRTPGM.

AS/400-RPGLE-SN-2.0

Page No.

ILE RPG/400

2.4.1.1. Create a program using CRTBNDRPG to maximize OPM compatibility: This is used to create ILE program that interact well with OPM programs. You may want such a program temporarily while you complete your migration to ILE. In this method, Create a program object using the CRTBNDRPG command, specifying DFTACTGRP(*YES). ] Specifying DFTACTGRP(*YES) means that the program object will run only in the default activation group.(The default activation group is the activation group where all OPM programs are run.) When you use this approach you cant make use of ILE static binding. For example, you cant make use of some Bindable APIs. 2.4.1.2. Create an ILE program using CRTBNDRPG: By using this method, ILE program can take advantage of ILE static binding. You can also specify the activation group in which the program will run. In this method, Create a program object using the CRTBNDRPG command, specifying DFTACTGRP(*NO). The main drawback of this method is you do not have a permanent module object that you can later reuse to bind with other modules to create an ILE program. Further more, any procedure calls must be to modules to service programs that are identified in a binding directory. If you want to bind two or more modules without using a binding directory you need to use the third strategy. 2.4.1.3. Create an ILE program using CRTRPGMOD and CRTRPG: 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. This strategy allows you to fully utilize the concepts offered by ILE. With this strategy, you can create permanent modules, modularize an application. There is no need to compile the entire application if one module changes. 2.4.1.4 Compiler listing consists minimally following sections:

prologue ( command option summary) Source listing, which includes: In-line diagnostic messages Match-field table Additional diagnostic messages Field positions in output buffer /COPY member table Compile time data which includes: Alternate collating sequence records and table or NLSS information and table File translation records Array records Table records Message summary Final summary Code generation report(appears only if there are errors) Binding report(applies only to CRTBMDRPG; appears only if there are errors)

2.4.2. Program Management: Earlier program management is done at job level ie., you can scope file overrides and shared open data paths and commitment-control operations at job level. Now for better control of resources, concept of activation group came into picture. In one job, there can be any number of activation groups. Now you can scope file overrides, open data paths and commitment-control at activation group level.

AS/400-RPGLE-SN-2.0

Page No.

10

ILE RPG/400

The process of getting a program or service program ready to run is known as activation. Activation allocates resources within a job so that one or more programs can run in that space. An activation group is a substructure of a job and consists of system resources that are allocated to run on or more ILE or OPM programs. A named activation group allows you to manage a collection of ILE programs and service programs as one application. An activation group is the key element governing an ILE applications resources and behavior. 2.4.3 Program call: Dynamic call: The called programs name is resolved to an address at run time, just before the calling program passes control to the called program. In ILE, you can write applications in which ILE RPG/400 programs and OPM RPG/400 programs continue to interrelate through the traditional use of dynamic program calls. Static call: Static calls involve calls between procedures. A procedure is a self-contained set of code that performs a task and then returns to the caller. Because the procedure names are resolved at bind time(that is, when you create the program), static calls are faster than dynamic calls. 2.4.3.1. Parameter passing style: ILE RPG/400 allows three methods for passing and receiving prototyped parameters: By reference By value By read-only reference By reference: This is default parameter passing style for ILE RPGIV. You should pass parameters by reference to a procedure when you expect the call to modify the field passed. You may also want to pass by reference to improve run-time performance. Example Have a look at the following program. *************** Beginning of data ************************************* 0001.00 Dpref pr 0002.00 D temp 5 0 0003.00 *Initializing variable temp. 0004.00 Dtemp s 5 0 inz(100) 0006.00 *Display variable temp first time 0007.00 C temp dsply 0008.00 *Calling a procedure with callp because no return value. 0009.00 C callp pref(temp) 0010.00 *Display variable temp third time 0011.00 C temp dsply 0012.00 C seton lr 0013.00 Ppref b 0014.00 Dpref pi 0015.00 D temp 5 0 0016.00 *Modifying value in procedure 0017.00 C z-add 10 temp 0018.00 *Display variable temp second time 0019.00 C temp dsply 0020.00 Ppref e ****************** End of data **************************************** The output of the program is 100, 10 and 10 respectively. This is because in CALLP statement, the address of variable TEMP is being passed to PREF Subprocedure. So modifications to TEMP are not lost.

AS/400-RPGLE-SN-2.0

Page No.

11

ILE RPG/400

By Value: When a parameter is passed by value, the compiler passes the actual value to the called procedure. To pass a parameter by value, specify the keyword VALUE on the parameter definition in the prototype. Example: Observe the changes made in the above program. *************** Beginning of data ************************************* 0001.00 Dpref pr 0002.00 D temp 5 0 Value 0003.00 *Initializing variable temp. 0004.00 Dtemp s 5 0 inz(100) 0005.00 *Initializing variable temp. 0006.00 *Display variable temp first time 0007.00 C temp dsply 0008.00 *Calling a procedure with callp because no return value. 0009.00 C callp pref(temp) 0010.00 *Display variable temp third time 0011.00 C temp dsply 0012.00 C seton lr 0013.00 Ppref b 0014.00 Dpref pi 0015.00 D temp 5 0 Value 0016.00 *Modifying value in procedure 0017.00 C z-add 10 temp 0018.00 *Display variable temp third time 0019.00 C temp dsply 0020.00 Ppref e ****************** End of data **************************************** The output of the program is 100, 10 and 100 respectively. This is because, on CALLP statement, the value of temp is being passed, not its address. So modifications to temp in Subprocedure are not remained. By Read-only reference: Passing by read-only reference is useful if you must pass the parameter by reference and you know that the value of the parameter will not be changed during the call. For example, many system APIs have read-only parameters specifying formats, or lengths. To pass a parameter by read-only reference, specify the keyword CONST on the definition specification of the parameter definition in the prototype. Example: Dpassror D Num PR 10I 0 CONST

2.4.4. Source debugging: The ILE source debugger is used to detect errors in and eliminate errors from program objects and service programs. Debug data is created depending on DBGVIEW parameter on CRTBNDPGM or CRTRPGMOD. A program or module must have debug data available if you are to debug it. The following values for DBGVIEW parameter are valid:

AS/400-RPGLE-SN-2.0

Page No.

12

ILE RPG/400

*None : *STMT : *SOURCE: *COPY : *LIST :

No debug data is created You have to make use of statement numbers. Source will not be displayed. It is default value. Contains text from the root source member. We generally use this option. Contains text form the root source member and all copy members. Contains text in compiler listing.

To debug a program, Compile it with required DBGVIEW parameter value. Set the break point using DSPMODSRC. Then Call the program. The debugger allows stepinto, step over functions. 2.4.5. Bindable APIs: ILE offers a number of bindable APIs that can be used to supplement the function currently offered by ILERPG/400. The bindable APIs provide program calling and activation capability, condition and storage management, math functions, and dynamic screen management. To use these bindable APIs, Compile the programs using DFTACTGRP(*NO). Examples: CEECRHP - To create your own heap CEEFRST - Free storage in your own heap CEE4ABN - Abnormal End etc.,
2.5 Data types:

Different datatypes allowed in ILE RPGIV are as follows: A - Character field B - Fixed binary field D - Date field F - Floating-point field G - Graphic character field I - Signed Integer field P - Packed decimal field S - Zoned field T - Time field U - Unsigned Integer field Z - Timestamp field *-Pointer field Different date formats allowed are *MDY, *DMY, *YMD, *JUL, *ISO(yyyy-mm-dd), *USA(mm/dd/yyyy), *EUR(dd.mm.yyyy) and *JIS(yyyy-mm-dd).

AS/400-RPGLE-SN-2.0

Page No.

13

ILE RPG/400

3. OP-CODE VARIATIONS IN ILERPG/400 OVER RPG/400

You feel familiar in many places of ILERPG/400 because many op-codes in RPG/400 are intact. There are some additional opcodes which need attention. In some existing opcodes, slight modifications are incorporated for better performance. This chapter does not explains in detail those operations which are in RPG/400. This chapter briefly explains the additional op-codes and modifications of existing op-codes in the following categories of operations:
3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9

Arithmetic operations Branching operations Call operations Date operations Moving Date-Time data Operations using Expressions Message operation String operations Structured programming operations

3.1. ARITHMETIC OPERATIONS:

The arithmetci operations are: ADD (H), DIV (H), MULT (H), MVR, SQRT (H), SUB (H), XFOOT(H), Z-ADD (H), Z-SUB(H). You can observe the modification in arithmetic operations, ie., the symbol (H). H means Half adjust ie., round the numeric result. In RPG/400, we give this H in 53 column of C-spec.
3.2. BRANCHING OPERATIONS:

CABxx, GOTO, ITER, LEAVE, TAG. We havent gone in detail to explain above operations as you are already be familiar with them. The ITER operation transfers control from within a DO-group to the ENDDO statement of the DO-group. The LEAVE operation is similar to the ITER operation; however, LEAVE transfers control to the statement following the ENDDO operation.
3.3. CALL OPERATIONS:

The CALL operations are: CALL, CALLB, CALLP, PARM, PLIST, RETURN. A prototype is an external definition of the call interface that allows the compiler to check the interface at compile time. In ILE, it is possible to call either program or procedure. Furthermore, ILE RPG/400 provides the ability to call prototyped or non-prototyped programs and procedures. There are three types of calls: Program call, Procedure call and in expressions A Program call is a call that is made to a program object(*PGM). The called programs name is resolved to an address at runtime, 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. You can use CALLP operation or both the CALL and PARM operation to make a program call. Use CALLP if you have prototype for called program in calling program otherwise use CALL. If you use CALL, then the compiler cannot perform type checking on the parameters, which may result in run-time errors. In procedure call, the called procedures name is resolved to an address at compile time. Procedure calls are also referred to bound calls. These calls are faster than program calls. You use the CALLP or both the CALLB and PARM operation to make a procedure call. Use CALLP if you have prototype for that called procedure otherwise use CALLB. If you use the CALLB, then the compiler cannot perform type checking on the parameters, which may result in run-time errors.
AS/400-RPGLE-SN-2.0 Page No.

14

ILE RPG/400

You can also call a prototyped procedure with an expression if the procedure returns a value. Example: The following program accepts a valid employee code from screen and displays the detail employee designation. For example, if you give SE, Software Engineer will be displayed. *************** Beginning of data ************************************* 0001.00 Ddesc s 20a 0002.00 *Prototype 0003.00 Dempdesc pr 20a 0004.00 D des 3a 0005.00 *To accept designation code from workstation 0006.00 C 'Desig?:' dsply desig 3 0007.00 *Calling a prototyped procedure in expression. If this function does 0008.00 * not return any value you can use CALLP. 0009.00 C eval desc = empdesc(desig) 0010.00 C desc dsply 0011.00 C seton lr 0012.00 PEMPDESC B 0013.00 *Procedure interface 0014.00 DEMPDESC PI 20A 0015.00 D DES 3A 0016.00 C SELECT 0017.00 C WHEN DES = 'SE' 0018.00 C RETURN 'SOFTWARE ENGINEER' 0019.00 C WHEN DES = 'SSE' 0020.00 C RETURN 'SENIOR S. ENGINEER' 0021.00 C WHEN DES = 'GM' 0022.00 C RETURN 'GENERAL MANAGER' 0023.00 C OTHER 0024.00 C RETURN 'NOT VALID' 0025.00 C ENDSL 0026.00 PEMPDESC E ****************** End of data ****************************************
3.4. DATE OPERATIONS:

Date operations allow you to perform date and time arithmetic, extract portions of a date, time or timestamp field; or test for valid fields. They operate on Date, Time and Timestamp fields, and character and numeric fields representing dates, times and timestamps. The data operations are: ADDDUR(Add Duration): The ADDDUR operation adds the duration specified in factor 2 to a date or time and places the resulting date, time or timestamp in the result field. Example: D Duedate S D DATFMT(*MDY) INZ(D12 31 92) DUEDATE DUEDATE

*To determine the date 23 days later C ADDDUR 23:*D *To subtract 30 days from a duedate C ADDDUR -30:*D

AS/400-RPGLE-SN-2.0

Page No.

15

ILE RPG/400

The valid duration codes(and their short forms) are: *YEARS for the year (*Y) *MONTHS for the month (*M) *DAYS for the day (*D) *HOURS for the hours (*H) *MINUTES for the minutes (*MN) *SECONDS for the seconds (*S) *MSECONDS for the microseconds (*MS) EXTRACT(Extract Date/Time/Timestamp): The EXTRACT operation code will return one of the year, month or day part of a date or timestamp field the hours, minutes or seconds part of a time or timestamp field the microseconds part of the timestamp field to the field specified in the result field. Example: EXTRACT Duedate:*M Month 2 0 It extracts the Month and places it in variable Month. SUBDUR(Subtract Duration): The SUBDUR operation has been provided to: Subtract a duration to establish a new date, time, or timestamp Calculate a duration Example: *Adds 30 days to a due date C SUBDUR -30:*D Duedate *Calculate the number of days between a LOANDATE and a DUEDATE C Loandate SUBDUR Duedate Days:*D

5 0

TEST(Test Date/Time/Timestamp): The TEST operation code allows users to test the validity of date, time, or timestamp fields prior to using them. Example: D Datefield S D DATFMT(*JIS) D Date1 S 6P 0 INZ(910921) C *DMY TEST (D) Date1 *Indicator 20 is set since Date1 is not in *DMY format. *(D) indicates Date1 is a date field. 20

C TEST Datefield 21 *No factor1 since result is a D data type field. Ind 21 will not be set on since the field contains a valid date.
3.5. MOVING DATE-TIME DATA:

The MOVE and MOVEL operation codes can be used to move date, time and timestamp data type fields. Factor 1 is optional for MOVE and MOVEL and is used to specify the format of the character or numeric field. Any valid format may be specified. If factor 1 is blank, the format of the Date-Time field is used. Factor 2 is required and may contain a character or numeric, date, time or timestamp field to be converted. The date or time is placed in the result field according to its defined format or the format code specified in factor 1.

AS/400-RPGLE-SN-2.0

Page No.

16

ILE RPG/400

Example: The following example accepts the birth date from the workstation and displays his age interms of year. *************** Beginning of data ************************************* 0001.00 Dcurdate s d 0002.00 Dbd s d 0003.00 Dbirthd s 10 0004.00 Dyears s 3 0 0005.00 *Enter the date in *ISO format(yyyy-mm-dd) 0006.00 C 'b.date?' dsply birthd 0007.00 *Convert from date format to date field. 0008.00 C *iso move birthd bd 0009.00 *Current date 0010.00 C *dmy movel udate curdate 0011.00 *Calculating the years. 0012.00 C curdate subdur bd years:*y 0013.00 C years dsply 0014.00 C seton lr ****************** End of data ****************************************
3.6. OPERATING USING EXPRESSIONS:

Using expressions in operations is an improvement in ILE RPG/400 over RPG/400. The operations using expressions are as follows: EVAL, DOU, DOW, IF, WHEN. We are already familiar with above operations except EVAL. EVAL: The EVAL operation code evaluates an assignment statement of the form result = expression. The expression is evaluated and the result placed in result. Example: Assume A = 10; B = 9; C = 8; D = 7 EVAL RESULT = A + B + (C - D) The value of RESULT after the operation is 20. Assume A = Wipro Technologies EVAL %SUBST(A:7:12) = Limited The value of A is Wipro Limited
3.7. MESSAGE OPERATION:

The message operation DSPLY allows interactive communication between the program and the operator or between the program and the display workstation that requested the program. The Factor 1 contains either field name to display value or message to display. The result field contains the reply.
3.8. STRING OPERATIONS:

The string operations include concatenation, scanning, substringing, translation, and verification. String operations can only be used on character or graphic fields. The string operations are: CAT (P), CHECK, CHECKR, SCAN, SUBST (P), XLATE (P) The only difference in these operations from RPG/400 is the symbol (P). The symbol P means pad the result with blanks or zeros. In RPG/400 we give P in 53 column of string operations.

AS/400-RPGLE-SN-2.0

Page No.

17

ILE RPG/400

STRUCTURED PROGRAMMING OPERATIONS: There is no difference in structured operations. The structured operations are as follows: DO, DOUxx, DOWxx, ELSE, END, Ifxx, ITER, LEAVE, Orxx, OTHER, SELECT, WHENxx where xx can be GT, LT, EQ, NE, GE, LE.

AS/400-RPGLE-SN-2.0

Page No.

18

ILE RPG/400

4. FILE HANDLING IN ILE RPG/400

The key element for all I/O operations on the AS/400 is the file. The system supports the following file types: Database files allow storage of data permanently on system. Device files allow access to externally-attached devices. Includes display files, printer files, tape files, diskette files and ICF files. Save files used to store saved data on disk. DDM files allow access to datafiles stored on remote systems. When identifying the file description your program will be using, you must indicate whether it is a program-described file or an externally described file. Externally described files offer the following advantages over program-described files: Less coding in programs Less maintenance activity when the files record format is changed. Improved documentation Improved reliability The commonly used file operation codes used in ILE RPG/400 are CHAIN (N), CLOSE, COMMIT, DELETE, EXCEPT, EXFMT, OPEN, READ (N), READC, READE (N), READP (N), READPE (N), ROLBK, SETGT, SETLL, UNLOCK, UPDATE, WRITE. The only difference is operation extender (N). If you specify N as the operation extender for an update disk file, a record is read without locking. If no operation extender is specified, the record is locked if the file is an update disk file. We are not explaining all the above operations in detail as all are familiar to you. Changes has been incorporated in the declaration of file(In F-spec). For example to rename a record, declaring a subfile etc., This chapter explains the changes incorporated in ILERPG/400. This chapter explains the following topics in brief: 4.1. Changes in File declaration 4.1.1. Renaming a record format name of externally described file 4.1.2. Renaming a field name 4.1.3. Ignoring record format names in logical file 4.1.4. Declaring overflow indicator 4.1.5. Decalring a subfile
4.2. Record Locking and Relative-Record-Number processing 4.3. Using Commitment Control 4.1.

CHANGES IN FILE DESCRIPTION:

4.1.1. Renaming Record-Format Name: To rename a record-format name, use the RENAME keyword on the file description specifications for the externally described file. Example: To rename a record format name REC1 in FILEA, use the following FFILEA IP E K DISK RENAME(REC1:NewRecordName) 4.1.2. Renaming Field Names: You can partially rename all fields in an externally described file by using the PREFIX keyword on the file description specification for the file. Example: To add the prefix WTH to each field in file FILEA, use the following
AS/400-RPGLE-SN-2.0 Page No.

19

ILE RPG/400

FFILEA

IP E

K DISK

PREFIX(WTH)

You can rename a field using I spec. Example: Assume the file FILEA contains REC1 which inturn contains field FLD1. Assign a record-identifying indicator to FILEA and rename the field FLD1 to FIELD1. IREC1 01 I FLD1 FIELD1 *FLD1 is external field name and FIELD1 is name used in program. 4.1.3. Ignoring record formats: If a record format in an externally described file is not to be used in a program, you can use the IGNORE keyword to make the program run as if the record format didnot exist in the file. For logical files, this means that all data associated with that format is inaccessible to the program. Alternatively, the INCLUDE keyword can be used to include only those record format names that are to be used in the program. All other record formats contained in the file will be excluded. Example: Assume the file FILEA contains the following record formats: REC1, REC2, REC3, REC4. To make the program run as if only the REC1, REC2 records existed, either of the following two methods can be used: FFILEA or FFILEA UF E UF E K K DISK DISK IGNORE(REC3:REC4) INCLUDE(REC1:REC2)

4.1.4. Declaring Overflow indicator: Type an indicator in keyword OFLIND to set on when a line is printed on the overflow line, or when a overflow line is reached or passed during a space or skip operation. Example:Decalring indicator 40 as overflow indicator. FQSYPRT O
4.1.5.

80

PRINTER

OFLIND(*IN40)

Declaring a subfile:

Processing subfiles in ILE RPGIV is same as RPG/400. The only difference lies in declaring a subfile and relative record number in file description specification. Example: To declare a subfile named SUBFILE with relative reocrd number RECNUM, Fdisplayfile CF E WORKSTN SFILE(SUBFILE : RECNUM) 4.2. RECORD LOCKING AND RELATIVE RECORD NUMBER PROCESSING: 4.2.1. RECORD LOCKING When record is read by a program, it is read in one of two methods: input or update. If a program needs 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 needs a record for input, no lock is placed on the record. For update files, you can specify that a record be read for input by using one of the input operations CHAIN, READ, READE, READP, READPE and specifying an oepration code extender(N) in the operation code fied following the operation code name. When a record is locked by an RPG IV program, that lock remains until one of the following occurs:

the record is updated the record is deleted another record is read from file
Page No.

AS/400-RPGLE-SN-2.0

20

ILE RPG/400

a SETLL or SETGT operation is performed against the file an UNLOCK operation is performed against the file an outpu operation defined by an output specification with no field names included is performed against the file.

4.2.2. Relative-Record-Number Processing: Use the RECNO keyword on a file description specifications to specify a numeric field that contains the relative record number. A RECNO field must be specified if new records are to be placed in the file by using the output specification or a WRITE operation. When you update or add a record to a file by relative record number, the record must already have a place in the member. For an update, that place must be a valid existing record; for a new record, that place must be a deleted record. The current relatvie record number is placed in the RECNO field for all retrieval operations or operations that reposition the file( for example, SETLL, CHAIN, READ). Example: The logical order of the following program is as follows -Read a first record -Delete that record -Write another record in the place of first record not at the end of file. -Until EOF of EMPMSTR, read the file and observe the change in RECNO field. The DDS for the file EMPMSTR is as follows *************** Beginning of data ************************************* 0001.00 A R EMPMSTRA 0002.00 A ENO 5 0 0003.00 A ENAME 15A 0004.00 A ESAL 10 0 ****************** End of data **************************************** The RPG IV code is as follows: *************** Beginning of data ************************************* 0001.00 *Declare a file with relative record number field 0002.00 Fempmstr uf a e disk recno(trrn) 0003.00 Dtrrn s 3 0 0004.00 *Read the first record in EMPMSTR file 0005.00 C read empmstr 30 0006.00 *Delete the first record in file 0007.00 C delete empmstr 0008.00 *Write another record in the place of first record, not at last. 0009.00 C z-add 1 trrn 0010.00 C z-add 100 eno 0011.00 C move 'example' ename 0012.00 C z-add 1000000 esal 0013.00 C write empmstra 0014.00 *Until End of file, read the file and display Relative record number. 0015.00 C dow not *in30 0016.00 C read empmstr 30 0017.00 C trrn dsply 0018.00 C enddo 0019.00 C seton lr ****************** End of data **************************************** 4.3. USING COMMITMENT CONTROL:

AS/400-RPGLE-SN-2.0

Page No.

21

ILE RPG/400

Commitment control is used 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)

To use the commitment control, you do the following: On the AS/400:

1. 2.

To use commitment control, create journal, journal receiver and start the journal physical file. Notify the AS/400 when to strart and end commitment control: Use STRCMTCTL and ENDCMTCTL

In the RPG program: Specify commitment control (COMMIT) on the file-description specifications of the files you want under commitment control. 2. Use the COMMIT ( commit ) operation code to apply a group of changes to files under commitment control, or use ROLBK ( Roll Back ) operation code to eliminate the pending group of changes to fiels under commitment control.
1.

The COMMIT oepration tells the system that you have completed a group of changes to the files under commitment control. The ROLBK operation eliminates the current group of changes to the files under commitment control. Example: This example illustrates the specifications and CL commands required for a program to operate under commitment control. To prepare for using commitment control, you issue the following CL commands:
1. 2. 3.

CRTJRNRCV JRNRCV(RECEIVER) CRTJRN JRN(JOURNAL) JRNRCV(RECEIVER) STRJRNPF FILE(FILEA) JRN(JOURNAL)

In RPG IV program, FFILEA UF E K DISK COMMIT

*After a group of database operations, if you want to commit all those operations C COMMIT *If you want to revert all the database operations done on FILEA. C ROLBK To operate your program under commitment control, you issue the following commands:
1. 2. 3.

STRCMTCTL CALL RPGIVprogram ENDCMTCTL

AS/400-RPGLE-SN-2.0

Page No.

22

ILE RPG/400

5. DATA STRUCTURES
Data structure define an area in storage and the layout of related subfields. You define a data structure by specifying DS in positions 24 thourgh 25 on a definition specification. This chapter briefly explains the following: 5.1. Uses of Data structure 5.1.1. Divide a field into subfield 5.1.2. Group fields 5.1.3. Define externally described data structure 5.1.4. Define data area data structure 5.1.5. Define multiple occurance data structure 5.2. Program-described and Externally-described data structure
5.3. Special data structures

5.3.1. Data area data structure 5.3.2. File inforamtion data structure 5.3.3. Program-status data structure 5.1. Data structures may be used to: 5.1.1. Divide a field into subfield: Suppose you have a date field DATE1 of length 8 in the format mmddyyyy in externally described file. By using datastructure, you can divide the DATE1 field into days, months and years. Example D DATE1 D months D days D year DS 2 2 4

5.1.2. Group fields: Suppose you have a month, day, year fields in your externally described file. By using datastructure, you can combine all these fields into DATE1 in the format of year, month, day Example D Date1 D year D months D day DS 4 2 2

5.1.3. Define Externally described data structures: Assume FILEA contains fields FLD1 and FLD2. By using externally described datastructures, you can rename field FLD1 and you can initialize FLD2 with Hello as follows: Example D ExtName E DS D Field1 E D FLD2 E EXTNAME(FILEA) EXTFLD(FLD1) INZ(Hello)

With EXTNAME keyword, specify the name of the externally described file. With EXTFLD, the name of FLD1 has been changed to Field1. 5.1.4. Define Data area data structures: A data area is an object that may exist permanently or temporarily in any library on the system. A data area data structure in an RPG IV program and the related data area must have the same name. Data areas may be implicitly or explicitly retrieved and written. When the data area is defined in an RPG IV program as a data area data structure, its data is implicitly retrieved for processing and written back(updated) at the end of the program. Example CRTDTAARA DTAARA(NAME) LEN(30) VALUE(Wipro Technologies)
Page No.

AS/400-RPGLE-SN-2.0

23

ILE RPG/400

To access this data area in your program, D Name UDS D Firstname 5 D Secondname 15 D Thirdname 30 5.1.5. Define Multiple occurance data structures: To define a multiple occurance data structure of 20 elements with : - 3 fields of character 20. th nd - a 4 field of character 10 which overlaps the 2 field starting at the second position. Example D twenty D MulDS D field1 D field2 D field21 D field3 C DS CONST(20) OCCURS(twenty) 1 20 21 40 22 31 41 60

5.2. Data structures can be program-described or externally-described. A program-described data structure is identified by a blank in position 22 of the definition specification. An externally-described data structure, identified by an E in position 22 of the definition specification, has subfield descriptions contained in an externally-described file, At compile time, the ILE RPG/400 compiler uses the external name to locate and extract the external description of the data structure subfields. You specify the name of the external description either in positions 7 through 21, or as a parameter for the keyword EXTNAME. An external subfield name can be renamed in the program using the keyword EXTFLD. The keyword PREFIX can be used to add a prefix to the external subfield names. Additional subfields can be added to an externally described data structure by specifying program-described subfields immediately after the list of external subfields. 5.3. SPECIAL DATA STRUCTURES: Special data structures include:
5.3.1. 5.3.2. 5.3.3.

Data area data structure File inforamtion data structure (INFDS) Program-status data structure

5.3.1. Data area data structure: A data area data structure, identified by a U in position 23 of the definition specification, indicates to the RPG IV program that it should read in and lock the data area of the same name at program initialization and should write out and unlock the same data area at the end of the program. The data area and data area data structure must have the same name unless you rename the data area within the RPG IV program by using *DTAARA DEFINE operation code or the DTAARA keyword. If you specify blanks for the data area data structure ( positions 7 through 21 of the definition spec that contains a U in position 23), the RPG IV program uses the local data area. To provide a name for the local data area, use the *DTAARA DEFINE operation, with *LDA in factor 2 and the name in the result field or DTAARA(*LDA) on the definition specification.

AS/400-RPGLE-SN-2.0

Page No.

24

ILE RPG/400

Examples for File information and program status data structure will be depicted in Exception/Error Handling chapter. 5.3.2. File Inforamtion data structure: You can specify a file inforamtion data structure( defined by the keyword INFDS on a file description specifications) for each file in the program. This provides you with status information on the file exception/error that occured. A file inforamation data structure contains predefined subfields that provide inforamtion on the file exception/error that occured. 5.3.3. Program-status data structure: A program-status data structure, identified by an S in position 23 of the definition specification, provides program exception/error inforamtion to the program.

6. TABLE AND ARRAY PROCESSING

AS/400-RPGLE-SN-2.0 Page No.

25

ILE RPG/400

Arrays and Tables are both collections of data fields(elements) of the same field length, data type, format. This chapter describes:
6.1. Differences between Arrays and Tables 6.2. Arrays

6.2.1. Prerun-time arrays 6.2.2. Compile-time arrays 6.2.3. Run-time arrays

6.3. Searching Arrays

6.3.1. Searching an Array without an Index 6.3.2. Searching an Array with an Index
6.4. Sorting an Array 6.5. How Tables differs from Array in coding

6.1. DIFFERENCES BETWEEN ARRAYS AND TABLES: Arrays and Tables differ in that:

You can refer to a specific array element by its position You cannot refer to specific table elements by their position An array name by itself refers to all elements in the array. A table name always refers to the element found in the last LOOKUP(Look up a Table or Array Element) operation. During processing, elements in related arrays may be cross-referenced by indexing.

6.2. Arrays: An array may be defined as an arrangement of computer memory positions with each position having the same attributes. Loading an array refers to the time in the program cycle during which data is read, moved and stored in the array elements. There are three types of arrays.
6.2.1.

The Compile-time array is loaded when your program is created. The initial data becomes a permanent part of your program. The Prerun-time array is loaded from an array file when your program begins running, before any input, calculation, or output operations are processed. The run-time array is loaded by your program while it is runnig.

Compile-time array:

A compile-time array is specified using the essential array specifications plus the keyword CTDATA. You can specify the number of array entries in an input record using the PERRCD keyword on the definition specification. If you do not use the PERRCD keyword, the number of entries defaults to 1.

AS/400-RPGLE-SN-2.0

Page No.

26

ILE RPG/400

Example: Write a program which accepts month name and tells whether it is a valid month or not. *************** Beginning of data ************************************* 0001.00 Ddaynam s 3a dim(7) perrcd(2) CTDATA 0001.01 *daynam is a compile time array consisting of 7 elements. 0001.02 *daynam consists of two elements per record. 0002.00 Dname s 3a 0003.00 C 'Day name:?' dsply name 0003.01 *Searching whether the name is in array or not. 0004.00 C name lookup daynam 0005.00 C if *in20 0006.00 C 'valid' dsply 0007.00 C else 0008.00 C 'invalid' dsply 0009.00 C endif 0010.00 C seton l 0010.01 *Compile time array 0011.00 **CTDATA daynam 0012.00 montue 0012.00 montue 0013.00 wedthu 0014.00 frisat 0015.00 sun ****************** End of data **************************************** Compile-time arrays in alternating format: Code two arrays with 7 elements each. Name is a character array of length 3, and Number is a numeric array of length 1. To code a compile-time array in alternating format. Example: To code an alternating arrray, use ALT keyword. DNAME D DNUMBER

S S

15 1 0

DIM(7) PERRCD(3) CTDATA DIM(7) ALT(NAME)

Declare the data as follows

** CTDATA Mon1 Tue2 Wed3 Thu4 Fri5 Sat6 sun7

6.2.2.

Prerun-time array:

For a prerun-time array, enter array input data into a file. The file must be a sequential program described file. By modifying this file, you can alter the arrays initial values on the next call to the program. The file is read in arrival sequence. On the definition specifications, in addition to the essential array specifications, you can specify the name of the file with the array input data, using the FROMFILE keyword. You can use the TOFILE keyword to specify the name of a file to which the array is written at the end of the program. You can use PERRCD keyword to specify the number of elements per input record. Specify a T in position 18 of the file description specifications for the file with the array input data. Example: Array ARH has 250 character elements(12 elements per record). Each element is five positions long. ARH is written back to the same file form which it is read when the program ends normally with LR on.
AS/400-RPGLE-SN-2.0 Page No.

27

ILE RPG/400

DARH D D
6.2.3.

5A

DIM(250) PERRCD(12) ASCEND FROMFILE(DISKOUT) TOFILE(DISKOUT)

Runtime arrays:

If you make no further specifications beyond the essential array specifications, you have defined a run-time array. Noth that keywords ALT, CTDATA, FROMFILE, PERRCD and TOFILE connot be used for a run-time Example to declare a runtime array with 12 elements, each of length 3 is as follows: DARY1 S 3A DIM(12)

Loading a Run-time array:

You can assign initial values for a run-time array using the INZ keyword on the definition specification. You can assign values for a run-time array in calculation specifications. For example, you can use MOVE or MOVEL operation to load certain elements of an array. You can assign values for a run-time array through input specifications. If the array elements are consecutive on the input record, the array can be loaded with a single input specification. Suppose FILEA(program described file contains a record of length 9. If you want to load that record into an array of dimention 3, use the following code: *Using a run-time array with consecutive elements DARR1 S 12A DIM(3) *ARR1 is loaded with reocrd in FILEA. IFILEA AA 01 I 1 12 ARR1

If the array elements are scattered throughout the record, they can be defined and loaded one at a time, with one element described on a specification line. Following is an example shows loading an array ARR1, of six elements with 12 characters each, from a single record from file FILEA; a blank seperates each of the elements from the others. *Defining a runtime array with scattered elements D ARR1 S 12A DIM(6) I FILEA I I I I I I
6.3. Searching Arrays:

AA

01 1 14 40 66 ARR1(1) 25 ARR1(2) 27 38 ARR1(3) 51 ARR1(4) 53 64 ARR1(5) 77 ARR1(6) 12

The LOOKUP operation can be used to search arrays. Searching an Array without an index: When searching an array without an index, use the resulting indicators to determine whether a particular element is present in the array. Searching an array without an index can be used for validity checking of input data to determine if a field is in a list of array elements.

AS/400-RPGLE-SN-2.0

Page No.

28

ILE RPG/400

The search starts at the beginning of the array and ends at the end of the array or when the conditions of the lookup are satisfied. Whenever an array element is found that satisfies the type of search being made(equal, high, low), the resulting indicator is on. Example: suppose there is an array Months containing all the names of the months in a year. C January LOOKUP Months 20(Equal indicator)

The indicator 20 is set on because the search argument january is in the list of elements of Months. Searching an Array with an index: To findout which element satisfies a LOOKUP search and start the search at a particular element in the array, search the array with an index. Example: Suppose you want to start the search from second element in an array and display the index where search has become successful * To start the search from 2 C Z-ADD 2
nd

element in the array ARR1 X 3 0

C March LOOKUP Months(X) 20(Eq) *At the end of successful LOOKUP, 20 is set on. The index X contains the index of the element which is *equal to the March
6.4. Sorting Arrays:

You can sort arrays using the SORTA(sort an array) operation code. The array is sorted into sequence ( ascending or descending ), depending on the sequence specified for the array on the definition specification. C SORTA ARR1

6.5. How Tables differ from arrays in coding:

Note: Using Tables in program is almost same as using arrays except in the following areas. Defining: A table name must be a unique symbolic name that begins with the letters TAB. Loading: Tables can be loaded only at compile time and prerun time. Using and Modifying table elements: Only one element of a table is active at one time. The table name is used to refer to the active element. An index cannot be specified for a table. Searching: LOOKUP with One Table: Whenever a table element is found that satisfies the type of search being made (equal, high, low), that table element is made the current element for the table. Resulting indicators reflect the result of the search.

AS/400-RPGLE-SN-2.0

Page No.

29

ILE RPG/400

LOOKUP with two tables: When two tables are used in a search, only one is actually searched. When the search condition (high, low, equal) is satisfied, the corresponding elements are made available for use. Factor 1 must contain the search argument, and factor 2 must contain the name of the table to be searched. The result field must name the table from which data is also made available for use. A resulting indicator must also be used. Example: *The LOOKUP operation searches TABEMP for an entry that is equal to the contents of the field named EMPNUM. If an equal entry is found in TABEMP, indicator 09 is set on, and the TABEMP entry and its related entry in TABPAY are made the current elements. C EMPNUM LOOKUP TABEMP TABPAY 09

AS/400-RPGLE-SN-2.0

Page No.

30

ILE RPG/400

7. POINTERS
Pointers are another important feature of ILE RPG/400 langurage. Although they may appear a little confusing for a beginner, they are a powerful tool and handy to use once they are mastered. There are a number of reasons for using pointers.
1. 2. 3. 4. 5.

A pointer enables us to access a variable that is defined outside the function. Pointers are more efficient in handling the data tables. Pointers reduce the length and complexity of a program. They increase the execution speed. The use of a pointer array results in saving of data storage space in memory.

In this chapter, We will examine the pointers in detail and learn how to use them in development. This chapter explains the following topics:
7.1. 7.2. 7.3. 7.4.

Understanding pointers Declaring a pointer data type Dynamic memory allocation Pointers to functions

7.1. Understanding Pointers:

As you know, computers use their memory for storing the instructions of a program, as well as the values of the variables that are associated with it. The computers memory is a sequential collection of storage cells. Each cell commonly known as a byte, has a number called address associated with it. Typically, the addresses are numbered consecutively, starting from zero. The last address depends on the memeory size. A computer system having 64K memory will have its last address as 65,535. Whenever, we declare a variable, the system allocates, somewhere in memory, an appropriate location to hold the value of the variable. Since, every byte has a unique address number, this location will have its own address number. Consider the following statement: D Name S 5A INZ(WTH)

This statement instructs the system to find a location for the variable Name and puts the value WTH in that location. Let us assume that the system has choosen the address location 5000 for Name. We may represent this as follows Variable Name WTH Value 5000 Address

We may have access to the value WTH by using either the name Name or the address 5000. Since memory addresses are simply numbers, they can be assigned to some variables which can be stored in memory, like any other variable. Such variables that hold memory addresses are called pointers. A pointer is, therefore, nothing but a variable that contains an address which is a location of another variable in memory. Remember, since a pointer is a variable, its value is also stored in the memory in another location. Suppose, we asssign the address of Name to a variable P. The link between the variables P and Name can be visualized as follows: Variable Name P
AS/400-RPGLE-SN-2.0

Value WTH 5000 5000 5048

Address

Page No.

31

ILE RPG/400

Since the value of variable P is the address of the variable Name, we may access the value of Name by using the value of P and therefore, we say that the variable P points to the variable Name. Thus, P gets the name Pointer.
7.2. Declaring a Pointer data type:

Consider the following: *************** Beginning of data ************************************* 0001.00 Dptr1 s * 0002.00 Dfld1 s 14a based(ptr1) 0003.00 C alloc 14 ptr1 0004.00 C move *all'a' fld1 0006.00 C seton lr ****************** End of data **************************************** When the BASED keyword is specified for a data structure or standalone field, a basing pointer is created using the name specified as the keyword parameter. The basing pointer holds the address(storage location) of the based datastructure or standalone field being defined. Note: Before the based datastructure or standalone field can be used, the basing pointer must be assigned a valid address. Following gives a detailed explanation of the above example: ptr1 is a pointer field fld1 is a field of length 14. Ptr1 is going to hold the address of fld1. 14 bytes of storage was allocated and ptr1 points to that starting address. We must allocate memory to ptr1 otherwise fld1 is cannot be used. a is filled in all 14 positions of fld1. After executing these statements, the representation of variables is as follows: Variable fld1 ptr1 Value aaaaaaaaaaaaaa address of fld1.(ie., address of value aaaaaaaaaaaaaa)

Declaring a pointer over an array: D MBRPTR D MBRARR S S 10 * BASED(MBRPTR) DIM(32767)

In this example, we code the DIM for the number of maximum elements allowed, nothing that no storage will actually be declared for this definition( because it is BASED) In the above, only declaration of pointers was explained. The other concepts will be covered later.
7.3. Dynamic Memory Allocation:

Introduction: Most often we face situations in programming where the data is dynamic in nature. That is, the number of data items keep changing during execution of the program. For example, consider a program for processing the list of customers of an organization. The list grows when the names are added and shrinks when names are deleted.

AS/400-RPGLE-SN-2.0

Page No.

32

ILE RPG/400

Dynamic data structures provide flexibility in adding, deleting or rearranging data items at run time. Dynamic memory management techniques permit us to allocate additional memory space or to release unwanted space at run time, thus, optimizing the use of storage space. This topic discusses the concept of linked lists, one of the basic types of dynamic data structures. Dynamic Memory Allocation: ILE RPG IV requires the number of elements in an array to be specified at compile time. But we may not be able to do so always. Our initial judgement of size, if it is wrong, may cause failure of the program or wastage of memory space. You can use the following RPG operations on the dynamic storage allocation The ALLOC oerpation allocates storage wihin the default heap. The DEALLOC operation frees one previous allocation of heap storage. The REALLOC operation changes the size of previously allocated storage from any heap. Example: Assume that Data entry operation of an organization doesnt know the total number of employees. He has to enter all the names one by one and atlast he has to print the list of all employees.

AS/400-RPGLE-SN-2.0

Page No.

33

ILE RPG/400

The following example takes the names of the employees until end is given. Then displays all the employee names. 0001.00 DAddname pr 0002.00 D namein 20a 0003.00 Ddisplay pr 0004.00 Dfree pr 0005.00 Demp ds based(emp@) 0006.00 D name@ * 0007.00 D next@ * 0008.00 Dnam s 20a based(name@) 0009.00 Dempsize c %size(emp) 0010.00 Dfirst ds 0011.00 D * INZ(*Null) 0012.00 D * inz(*null) 0013.00 Demp@ s * inz(%addr(first)) 0014.00 C 'Emp Name:?' dsply namein 20 0015.00 C dow namein <> 'end' 0016.00 C callp addname(namein) 0017.00 C 'Emp Name:?' dsply namein 20 0018.00 C enddo 0019.00 C callp display 0020.00 C callp free 0021.00 c seton lr 0022.00 Paddname b 0023.00 daddname pi 0024.00 D namein 20a 0025.00 c alloc empsize next@ 0026.00 C eval emp@ = next@ 0027.00 C eval next@ = *null 0028.00 C alloc 20 name@ 0029.00 C eval nam = namein 0030.00 Paddname e 0031.00 Pdisplay b 0032.00 dsemp@ s * 0033.00 C eval semp@ = emp@ 0034.00 C eval emp@ = %addr(first) 0035.00 C dow next@ <> *null 0036.00 C eval emp@ = next@ 0037.00 C nam dsply 0038.00 C enddo 0039.00 C eval emp@ = semp@ 0040.00 Pdisplay e 0041.00 Pfree b 0042.00 Dprv@ s * 0043.00 C eval emp@ = %addr(first) 0043.00 C eval emp@ = %addr(first) 0044.00 C eval emp@ = next@ 0045.00 C dow emp@ <> *null 0046.00 C dealloc name@ 0047.00 C eval prv@ = emp@ 0048.00 C eval emp@ = next@ 0049.00 C dealloc prv@ 0050.00 C enddo 0051.00 C eval emp@ = %addr(first) 0052.00 Pfree e ****************** End of data ****************************************

AS/400-RPGLE-SN-2.0

Page No.

34

ILE RPG/400

7.4. Pointers to Procedures: A procedure, like a variable, has an address location in the memory. It is therefore, possible to declare a pointer to a function, which can then be used as an argument in another function. The following example explains how to use pointers to procedures. First create a module with the following source *************** Beginning of data *************************************
0001.0 Hnomain

*Enjoy is a procedure, it can be used in other modules. It just displays HELLO. 0002.00 DENJOY pr 0003.00 PENJOY B export 0004.00 DENJOY pi 0005.00 C 'HELLO' DSPLY 0006.00 PENJOY E ****************** End of data **************************************** Create another module with the following source First it declares a procedure pointer penjoy which is initialized with address of ENJOY procedure. Use CALLB to call procedure with procedure pointer. *************** Beginning of data ************************************* 0001.00 DENJOY pr 0002.00 Dpenjoy s * procptr inz(%paddr('ENJOY')) 0003.00 c callb penjoy 0004.00 C seton lr ****************** End of data **************************************** After creating abvoe two modules create a program by including these two modules. Then call the program. The message HELLO is displayed.

AS/400-RPGLE-SN-2.0

Page No.

35

ILE RPG/400

8. EXCEPTION AND ERROR HANDLING

Exception errors that cause program execution to cancel are not uncommon in the programming environment. Exception handling is the process of examining an exception message which has been issued as a result of a run-time error. 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 occured:

ESCAPE Indicates that a severe error has been detected. STATUS Describes the status of work being done by a program NOTIFY Describes a condition requiring corrective action or reply from the calling program.

Function check indicates that one of the three previous exceptions occured and was not handled. Exception handlers are used to handle exception messages. Each call stack entry is associated with a list of exception handlers defined for that entry. In general, when an exception occurs, the handlers associated with the call stack entry are given a chance to handle the exception. If the exception is not handled by any of the handlers on the list the following default actions are taken:
1. 2. 3.

If the exception is a function check, the call stack entry is removed from the stack. The exception is moved(percolated) to the previous call stack entry. The exception handling process is restarted for this call stack entry.

Percolation is the action of allowing the previous call stack entry to handle an exception. This chapter explains the following topics:
8.1. Difference between OPM and ILE RPG/400 Exception handling 8.2. Usingg RPG-Specific Handlers

8.2.1.Specifying error indicators 8.2.2.Using a File Error ( INFSR ) subroutine 8.2.3 Using a Program Error Subroutine ILE RPG/400 supports not only RPG-specific handlers. It also supports ILE condtion handlers, userwritten exception handlers that you register at run time using the ILE condition handler bindable API CEEHDLR. ILE RPG/400 also supports ILE cancel handler which can be used when a procedure ends abnormally. I havent covered ILE conditon handlers and ILE cancel handlers.
8.1. Difference between OPM and ILE RPG/400 Exception Handling:

The key difference lies in the area of unhandled exceptions. In OPM, if an exception occurs and there is no RPG-specific handler enabled, then an inquiry message is issued. In ILE, this will only occur if the exception is a function check. If it is not, then the exception will be passed to the caller of the procedure or program, and any eligible higher call stack entries are given a chance to handle the exception. For example, consider the following example:

PGM A calls PGM B, which in turn calls PGM C. PGM B has an error indicator coded for the call. PGM C has no error indicator or *PSSR error subroutine coded. PGM C gets an exception

In OPM, an inquiry message would be issued for PGM C. In ILE, the exception is percolated to PGM B, since it is unhandled by PGM C. The error indicator in PGM B is turned on allowing PGM B to handle the error, and in the process PGM C ends abnormally. 8.2. Using RPG-Specific Handlers:
AS/400-RPGLE-SN-2.0 Page No.

36

ILE RPG/400

There are three ways for you to indicate that RPG should handle an exception. You can: Specify an error indicator in positions 73 - 74 of the calculation specifictions of the apporpriate operation code 2. Code a file error subroutine, which is defined by the INFSR keyword on a file description specification, for file exceptions. 3. Code a program error subroutine, which is named *PSSR, for program exceptions. Note that a *PSSR is local to the procedure in which it is coded. This means that a *PSSR in a main procedure will handle only those program errors associated with the main procedure. Similarly, a *PSSR in a subprocedure will only handle the errors in that subprocedure.
1.

You can obtain more inforamtion about the error which occured by coding the appropriate data structures and querying the relevant data structure fields.
8.2.1.

Specifying error indicators:

To enable the RPG error indicator handler, you specify an error indicator in positions 73 and 74. If an exception occurs on the oepration, the indicator is set on, the appropriate data structure (PSDS or INFDS) is updated, and control returns to the next sequential instruction. You can then test the indicator to determine what action to take. When you specify an error indicator on an operation code, you can explicitly call a file error subroutine (INFSR) or a program error subroutine ( *PSSR) with the EXSR operation.
8.2.2.

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. 2.

The INFDS is updated. A file error subroutine (INFSR) receives control if the exception occurs.

To add a file error subroutine to your program, you do the following steps: Enter the name of the subroutine after the keyword INFSR on a file description specification. Optionally identify the file information data structure on a file description specification using the keyword INFDS. 3. Enter a BEGSR operation where the factor 1 entry contains the same subroutine name that is specified for the keyword INFSR. 4. Identify a return point and code it on the ENDSR operation in the subroutine. 5. Code the rest of the file error subroutine.
1. 2.

Example: The following program accepts employee number from user and updates the company name of that employee to BMD. If record lock is there on that particular record, it displays the message record is locked The DDS for the file EMPDATA is as follows: *************** Beginning of data ************************************* 0001.00 A R EMPR 0002.00 A NUM 5 0 0003.00 A COMPNAME 15A 0004.00 A K NUM ****************** End of data **************************************** The RPG-IV code is as follows:
AS/400-RPGLE-SN-2.0 Page No.

37

ILE RPG/400

*************** Beginning of data ************************************* 0001.00 Fempdata uf e k disk 0002.00 F infsr(errr) 0003.00 F infds(errs) 0004.00 Derrs ds 0005.00 D rstatus *status 0006.00 C 'Name:?' dsply no 50 0007.00 C no chain empdata 90 0008.00 C if not *in90 0009.00 C move(p) 'BMD' compname 0010.00 C update empr 0011.00 C endif 0012.00 C seton lr 0013.00 C errr begsr 0013.01 *When record lock is there, rstatus becomes 1218 0014.00 C if (rstatus = 1218) 0015.00 C 'record lock' dsply 0016.00 C endif 0017.00 C endsr ****************** End of data **************************************** 8.2.3. 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. 2.

The program status data structure is updated. 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.

You can explicitly transfer control to a program error subroutine after a file error by specifying *PSSR after the keyword INFSR on the file description specifications. You can code a *PSSR for any (or all) procedures in the module. Each *PSSR is local to the procedure in which it is coded. To add a *PSSR error subroutine to your program, you do the following steps: Optionnally identify the program status data structure (PSDS) by specifying an S in positions 23 of the definition specification. 2. Enter a BEGSR operation with a Factor 1 entry of *PSSR. 3. Identify a return point, if any, and code it on the ENDSR operation in the subroutine. 4. Code the rest of the program error subroutine.
1.

Example: Define relevant parts of program status data structure D PSDS D Loc D Err D Parms SDS *ROUTINE *STATUS *PARMS

*In the *PSSR subroutine, code for division by zero, trying to get squareroot of negative number etc.,

AS/400-RPGLE-SN-2.0

Page No.

38

ILE RPG/400

C *PSSR BEGSR C IF Err = 102 C* Write your own code here C ENDIF C ENDSR

(For division by zero error)

AS/400-RPGLE-SN-2.0

Page No.

39

ILE RPG/400

9. BUILT-IN FUNCTIONS
Built-in functions are similar to operation codes in that they perform operations on data you specify. All built-in functions have the percent symbol (%) as their first character. The following explains the built-in functions, their arguments, and the value they return with examples.
1.

%ADDR ( Get Address of Variable )

%ADDR returns a value of type basing pointer. The value is the address of the specified variable. Example: D Fld1 C CONST(7) D Ptr S * INZ(%ADDR(Fld1))
2.

%ELEM ( Get Number of Elements )

%ELEM returns the number of elements in the specified array, table, or multiple occurance data structure. Example: D Arr1 S 20 DIM(10) C
3.

EVAL num = %ELEM (Arr1)

%PADDR ( Get Procedure Address )

%PADDR returns a value of type procedure pointer. The value is the address of the entry point specified as the argument. Example: D Proc S * PROCPTR INZ(%PADDR(FIRSTPROG))
4.

%SIZE:

%SIZE returns the number of bytes occupied by the constant or field. The argument may be a literal, a named constant, a data structure, a data structure subfield, a field, an array or a table name. Example: D table1 S 5 DIM(20) C
5.

EVAL num = %SIZE(table1)

%SUBST:

%SUBST returns a portion of argument string. It may also be used as the result of an assignment with the EVAL operation code. Example: The value of %subst(hello world:4:3) is lo
6.

%TRIM:

%TRIM returns the given string less any leading and trailing blanks Example: The value of %TRIM( hello ) is hello
7.

%TRIML:

%TRINL returns the given string less any leading blanks.

8.

TRIMR:

%TRIMR returns the given string less any trailing blanks.

AS/400-RPGLE-SN-2.0

Page No.

40