You are previewing The Modern RPG IV Language, Fourth Edition.
O'Reilly logo
The Modern RPG IV Language, Fourth Edition

Book Description

Cozzi on everything RPG! What more could you want? In this fourth edition of The Modern RPG IV Language, internationally recognized RPG expert Bob Cozzi takes his classic best seller to a whole new level. At close to 700 pages, this edition covers all of the new functions and facilities available in V5R4 RPG IV while keeping the straightforward, no-nonsense style that has kept this book on the best-seller list for almost 20 years. This new edition is guaranteed to keep Bob Cozzi as the leading expert on RPG, and his book the one turned to by countless developers worldwide.

This new edition of The Modern RPG IV Language is packed with new information including new, never-before published information on coding free-format RPG IV. Chapter 12 delves into free-format in detail as he discusses MOVE alternatives, date and time conversions, data structures, and more. And to give you even more exposure to free-format, he has converted many of the examples throughout the book to free-format code. Add to that XML, CGI, and subprocedure information, and you have a book that no "modern" RPG programmer can be without. Even with all the new material, the basic concept of the book remains the same. As with previous editions, The Modern RPG IV Language, 4th Edition takes you through RPG IV, from its foundation to its most advanced techniques. At the core of this book are its chapters on built-in functions and op codes. In these chapters, Cozzi details each built-in function and op code with syntax tables that give you all the information you need at a glance plus examples to help you as you code. This is much more than just a book on rules, however. Bob includes more than 400 charts and tables to show how those rules apply and provides more than 500 real-life code examples of functions and operations. You’ll turn to this book again and again as you program in RPG IV. It is the quintessential reference for every RPG programmer.

What's New in This Edition?

> Free-format syntax, including an entire chapter focused on this highly popular subject > Free-format examples throughout the book > Expanded information on subprocedures XML support, including new BIFs and op codes > Web programming with RPG, including CGI APIs and URL encoding
> Updated and revised content throughout the book to cover i5/OS V5R4

Within the pages of this book, you will find:

• The basics of RPG IV, including data types, indicators, constants, and directives • Detail on all of the specification types • A complete discussion of expressions and how they should be used • Every built-in function • Every op code • Options for organizing your program with source files, modules, and storage • A discussion on modern operation code optimization • An explanation of structured programming and how to apply it effectively in RPG • Instructions on how to code inter-module communications • Everything you need to know about procedures • An entire chapter on the alternate syntax options now available—most notably Free-Format

Table of Contents

  1. Copyright
    1. Dedication
  2. Acknowledgments
  3. Preface to the Fourth Edition
    1. The Evolution of RPG
    2. Who Should Read this Book?
    3. Which Version of RPG is Covered?
    4. What’s New in this Edition?
    5. Names ARE Important
  4. 1. Introduction
    1. Position-Oriented Program Specifications
    2. A Brief Language
    3. Specification Types
    4. RPG Components
    5. RPG Limitations
    6. Naming Conventions
    7. Data Types
    8. Indicators
      1. Indicatorless RPG Code
    9. Indicator Usage
    10. Function Key Attention Identification Byte
    11. Indicator Classification
    12. Indicators to Avoid
    13. Constants and Literal Values
      1. Figurative Constants
      2. Named Constants
      3. Reserved Names
      4. Reserved Words
    14. Operation Code Arguments
    15. Output Control Values
    16. Subroutine Return Points
    17. Directives
      1. Conditional Compiler Preprocessor Source Directives
  5. 2. Specification Formats
    1. Specification Types
    2. Header (Control) Specification
    3. File Specification
    4. Definition Specification
      1. Extended Name Definition
      2. Integer Variables
      3. Special PSDS Data Structure Subfields Positions
      4. Special INFDS Data Structure Subfields
      5. Definition Specification Keywords
    5. Input Specification
    6. Input Specification Summary
      1. Program-Described Files
      2. Program-Described File Field Descriptions
      3. Externally Described Files
      4. Externally Described Field Descriptions
    7. Calculation Specification
      1. Calculation Specification Summary
    8. Output Specification
      1. Program-Described Output File Control Entries
      2. Program-Described Output File Field Description
      3. Externally Described Output File Control Entries
      4. Externally Described Output File Field Description
    9. Procedure Specification
      1. Procedure Definition
      2. Procedure Specification Summary
      3. Procedure Specification Keyword Summary
    10. Editing Numeric Output
      1. Edit Words
      2. Edit Word Construction
      3. Edit Word Control Codes
      4. Edit Words and Named Constants
      5. Edit Codes
      6. Custom Currency Symbol
    11. Date Edit Code Control Summary
    12. Table and Array Specification
  6. 3. Expressions
    1. Expressions in RPG
    2. Natural Expressions
      1. Priority of Operators
      2. Expression Continuation
      3. Expressions in Assignment Statements
      4. Expressions in Compare Statements
      5. Expressions in Declarative Statements
      6. Expressions in Free Format Calculations
      7. Expressions in Parameters and Return Values
      8. Expressions as Parameters
      9. Precision Rules for Expressions
  7. 4. Built-In Functions
    1. Built-in Function Syntax
    2. Built-In Function Syntax Summary
      1. %ABS (Absolute Value)
        1. %ABS Syntax Diagram
      2. %ADDR (Get Address)
        1. %ADDR Syntax Diagram
      3. %BITAND (Bitwise “Anding” of Values)
        1. %BITAND Syntax Diagram
      4. %BITNOT (Bit Inversion)
        1. %BITNOT Syntax Diagram
      5. %BITOR (Bitwise “Oring” of Values)
        1. %BITOR Syntax Diagram
      6. %BITXOR (Bitwise Exclusive “Oring” of Values)
        1. %BITXOR Syntax Diagram
      7. %CHAR (Convert to Character)
        1. %CHAR Syntax Diagram
      8. %CHECK (Verify Field Content Left-to-Right)
        1. %CHECK Syntax Diagram
      9. %CHECKR (Verify Field Content Right-to-Left)
        1. %CHECKR Syntax Diagram
      10. %DATE (Convert to Date Value)
        1. %DATE Syntax Diagram
      11. %DEC and %DECH (Convert to Packed Decimal)
        1. %DEC Syntax Diagram
        2. Converting Dates or Time with %DEC
      12. %DECPOS (Retrieve Decimal Positions)
        1. %DECPOS Syntax Diagram
      13. %DIFF (Difference Between Two Date,Time, or Timestamp Values)
        1. %DIFF Syntax Diagram
      14. %DIV (Integer Division)
        1. %DIV Syntax Diagram
      15. Duration Built-in Functions
        1. Duration Built-in Functions’ Syntax Diagrams
      16. %EDITC (Edit with Edit Code)
        1. %EDITC Syntax Diagram
      17. %EDITFLT (Edit with Floating Point)
        1. %EDITFLT Syntax Diagram
      18. %EDITW (Edit with Edit Word)
        1. %EDITW Syntax Diagram
      19. %ELEM (Get Number of Elements)
        1. %ELEM Syntax Diagram
      20. %EOF (End of File Status)
        1. %EOF Syntax Diagram
      21. %EQUAL (Equal Condition Status)
        1. %EQUAL Syntax Diagram
      22. %ERROR (Error Condition Status)
        1. %ERROR Syntax Diagram
      23. %FIELDS (Identify Fields to Update)
        1. %FIELDS Syntax Diagram
      24. %FLOAT (Convert to Floating Point Value)
        1. %FLOAT Syntax Diagram
      25. %FOUND (Record/String Found Condition)
        1. %FOUND Syntax Diagram
      26. %GRAPHIC (Convert to Double-Byte Character Value)
        1. %GRAPHIC Syntax Diagram
      27. %HANDLER - Handle XML Parse Request
        1. %Handler Syntax Diagram
        2. %HANDLER with XML-INTO
      28. %Handler with XML-SAX
      29. %INT (Convert to Integer Value)
        1. %INT Syntax Diagram
      30. %KDS (Use a Data Structure as a Key List)
        1. %KDS Syntax Diagram
      31. %LEN (Set/Get Length)
        1. %LEN Syntax Diagram
      32. %LOOKUPXX (Array Element Lookup [Search])
        1. %LOOKUPXX Syntax Diagram
      33. %NULLIND (Set/Get Null Indicator Property)
        1. %NULLIND Syntax Diagram
      34. %OCCUR (Set/Get the Occurrence of a Data Structure)
        1. %OCCUR Syntax Diagram
      35. %OPEN (Check for File Open Condition)
        1. %OPEN Syntax Diagram
      36. %PADDR (Get Procedure Address)
        1. %PADDR Syntax Diagram
      37. %PARMS (Get Parameter Count)
        1. %PARMS Syntax Diagram
      38. %REM (Integer Division, Return Remainder)
        1. %REM Syntax Diagram
      39. %REPLACE (Replace/Insert Character String)
        1. %REPLACE Syntax Diagram
      40. %SCAN (Scan Character String)
        1. %SCAN Syntax Diagram
      41. %SHTDN (Check for System Shut Down or Job End Request)
        1. %SHTDN Syntax Diagram
      42. %SIZE (Get Size in Bytes Used)
        1. %SIZE Syntax Diagram
      43. %SQRT (Compute Square Root)
        1. %SQRT Syntax Diagram
      44. %STATUS (File or Program Status Code)
        1. %STATUS Syntax Diagram
      45. %STR (Get/Store Null-Terminated C-String)
        1. %STR Syntax Diagram
      46. %SUBARR (Subscript an Array)
        1. %SUBARR Syntax
      47. %SUBDT (Substring Date – Extract a Date or Time Component)
        1. %SUBDT Syntax Diagram
      48. %SUBST (Get/Set a Substring of a Value)
        1. %SUBST Syntax Diagram
      49. %TIME (Convert to Time Value)
        1. %TIME Syntax Diagram
      50. %TIMESTAMP (Convert to Timestamp Value)
        1. %TIMESTAMP Syntax Diagram
      51. %TLOOKUPxx (Table Element Lookup [Search])
      52. %TRIM, %TRIML, %TRIMR (Trim Leading and/Or Trailing Blanks)
        1. %TRIM Syntax Diagram
      53. %UCS2 (Convert to UCS-2)
        1. %UCS2 Syntax Diagram
      54. %UNS and %UNSH (Convert to Unsigned Integer Value)
        1. %UNS and %UNSH Syntax Diagram
      55. %XFOOT (Cross Foot Array Elements)
        1. %XFOOT Syntax Diagram
      56. %XLATE (Translate Characters)
        1. %XLATE Syntax Diagram
      57. %XML
        1. %XML Syntax Diagram
  8. 5. Operation Codes
    1. Abbreviations Used Throughout this Chapter
    2. Operation Code Summary
    3. Unconditionable Operation Codes
    4. Date and Time Format Codes
      1. Timestamp Format
    5. Date and Time Duration Codes
    6. Operation Extender Reference
    7. RPG IV Operation Code Summary Syntax Diagram Legend
    8. Operation Code Syntax Diagrams
    9. Boolean Operation Codes
    10. Free Format Operation Codes
    11. Natural Expression Operation Codes
    12. Program Status Codes
    13. File-Status Error Codes
    14. Nested Code Illustration
    15. Free Format Nested Code Illustration
      1. ACQ (Acquire)
      2. ADD (Add Numeric)
      3. ADDDUR (Add Duration)
      4. ALLOC (Allocate Memory)
      5. ANDxx (And Condition)
      6. BEGSR (Begin Subroutine)
      7. BITOFF (Set Bits Off)
      8. BITON (Set Bits On)
      9. CABxx (Compare and Branch)
      10. CALL (Dynamic Call to Another Program)
        1. Qualified Program Name
      11. CALLB (Call a Bound Procedure/Program)
      12. CALLP (Call with Prototype)
      13. CASxx (Compare and Perform Subroutine)
      14. CAT (Concatenation)
      15. CHAIN (Random Record Access/Read)
      16. CHECK (Verify a Character String)
      17. CHECKR (Verify Right to Left)
      18. CLEAR (Clear Data Set)
        1. CLEAR and Initial Values
      19. CLOSE (Close a File)
      20. COMMIT (Commit)
      21. COMP (Compare)
      22. DEALLOC (Release Allocated Memory)
      23. DEFINE (Define a Field or Data Area)
      24. DELETE (Delete Data File Record)
      25. DIV (Divide)
      26. DO (Begin Do Loop)
      27. DOUxx (Begin Do Until Loop)
      28. DOWxx (Begin Do While Loop)
      29. DSPLY (Display Workstation Message)
      30. DUMP (Print Formatted Dump)
      31. ELSE (Else Clause)
      32. ELSEIF (Else If Conditional Comparison)
      33. ENDxx (End a Group)
      34. ENDSR (End Subroutine)
      35. EVAL (Evaluate an Expression)
      36. EVALR (Evaluate an Expression, Right-Adjust)
      37. EXCEPT (Exception Output)
      38. EXFMT (Write/Read a Workstation File Format)
      39. EXSR (Perform Subroutine)
        1. Subroutine Considerations
      40. EXTRCT (Extract a Portion of a Date, Time, or Timestamp)
      41. FEOD (Force End of Data)
      42. FOR (For Loop)
      43. FORCE (Force Input Priority)
      44. GOTO (Go To)
      45. IFxx (If Conditional Comparison)
      46. IN (Read in a Data Area)
      47. ITER (Iterate a Loop)
      48. KFLD (Key Field)
      49. KLIST (Key List)
      50. LEAVE (Leave a Do Group)
      51. LEAVESR (Exit Subroutine)
      52. LOOKUP (Lookup Array or Table)
      53. MONITOR (Begin a Monitor Group)
        1. Special ON-ERROR Constants
      54. MxxZO (Move Zone to Zone)
      55. MOVE and MOVEL (Copy Data)
        1. Examples of MOVE and MOVEL
      56. MOVEA (Move with Array)
        1. MOVEA with Figurative Constants
      57. MOVEL (Copy Data Left-Justified)
        1. MOVEL with DATE and TIME Variables
      58. MULT (Multiply)
      59. MVR (Move Remainder of Division)
      60. NEXT (Force Next Input from a Specific Device File)
      61. OCCUR (Set/Retrieve Data Structure Occurrence)
      62. ON-ERROR (Test Error Status Condition)
      63. OPEN (Open a File)
      64. ORxx (Or Condition)
      65. OTHER (Otherwise)
      66. OUT (Output an External Data Area)
      67. PARM (Parameter Declaration)
      68. PLIST (Parameter List Declaration)
      69. POST (Post Device Information)
      70. READ (Read From a File)
      71. READC (Read Next Changed Workstation Record)
      72. READE (Read Next Record with an Equal Key)
      73. READP (Read Prior Record from a Data File)
      74. READPE (Read Prior Record with an Equal Key)
      75. REALLOC (Reallocate Memory)
      76. REL (Release an Acquired Device File)
      77. RESET (Reset Variable to its Initial Value)
      78. RETURN (Return to Calling Program)
      79. ROLBK (Rollback)
      80. SCAN (Scan String or Array)
      81. SELECT (Start In-line Case Group)
        1. Differences between SELECT/WHENxx and IFxx/ELSE
      82. SETGT (Set Greater Than)
      83. SETLL (Set Lower Limit)
      84. SETOFF (Set Off an Indicator)
      85. SETON (Set on an Indicator)
      86. SHTDN (Test for Shutdown Request)
      87. SORTA (Sort Array)
      88. SQRT (Square Root)
      89. SUB (Subtract)
      90. SUBDUR (Subtract Duration)
      91. SUBST (Substring Then Move Left)
      92. TAG (Label)
      93. TEST (Test Date/Time/Timestamp)
      94. TESTB (Test Bit Pattern)
      95. TESTN (Test Character Field for Numeric Data)
      96. TESTZ (Test the Zone of a Field)
      97. TIME (Retrieve System Time and Date)
      98. UNLOCK (Unlock Data Area/Release Record Lock)
      99. UPDATE (Update a File)
      100. WHENxx (In-Line Case Selection/When True then Select)
      101. WRITE (Write to a File)
      102. XFOOT (Cross-Foot an Array)
      103. XLATE (Translate a Character String)
      104. XML-INTO (Parse XML into RPG Variable)
        1. Receiver Variable
        2. XML Handler Subprocedure
      105. XML-SAX (Call XML SAX Parser)
        1. The XML-SAX Handler
      106. Z-ADD (Zero and Add)
      107. Z-SUB (Zero and Subtract)
  9. 6. Program Organization
    1. Source File Location
    2. Source File Member Contents
    3. Module Definition
      1. Traditional, Single-Source File RPG Program
      2. Single-Source File Using Embedded Subprocedures
      3. Multiple Source Files with Embedded or External Subprocedures
    4. Scope
    5. Static and Automatic Storage
    6. Import and Export
  10. 7. Modern Operation Code Usage
    1. Optimizing
    2. Indicator-Controlled Logic
    3. Indicatorless Controlled Logic
    4. Do Loops
      1. Do Loops with Level-Break Processing
      2. DO WHILE and DO UNTIL Operations
    5. Compare and Branch
    6. Compare Operation
    7. Ranges, Lists, and Select/Omit
    8. RPG IV Style
  11. 8. Structured Programming
    1. The Structured Approach
      1. Top-Down Programming
      2. Characteristics of a Well-Formed Routine
      3. Control Flow Constructs
        1. Sequence
        2. Choice
        3. Repetition
      4. Structured Operation Codes
      5. Boolean Operators
    2. The If-Then-Else Structure
    3. The Case Structure
      1. Successive CASE Operations
        1. Compare and Branch Operations
  12. 9. Inter-Module Communication
    1. Benefits of Modular Programming
    2. Common Techniques for Inter-Module Communication
      1. Parameter Passing
        1. Parameter Passing with PLIST
        2. Passing Data Structures as Parameters
    3. Prototyped Call
    4. Data Structures and Prototyped Procedures
      1. Prototyped Procedure Keywords
    5. Data Areas
      1. Data Area Data Structures
      2. IN and OUT Operation
  13. 10. Procedures
    1. User-Written Procedures
    2. Calling a Procedure
    3. Procedure Definition
    4. Prototyped Procedure Keywords
    5. Program Entry Point
    6. A System Interface for Procedures
  14. 11. File Processing
    1. Full-Procedural File Processing
    2. Physical Files
      1. Multiple Key Fields
    3. Logical Files
      1. Join Logical Files
    4. File Access
      1. Read Equal Key Anomaly
    5. Access Path Processing
      1. WORKSTATION DEVICE FILE PROCESSING
    6. Chain (Random File Access)
    7. Open and Close (Open and Close a File)
    8. Exfmt (Write then Read Workstation Device)
    9. Post (Post Device-Specific Information)
    10. Read (Read a Record from a File)
    11. Readc (Read Next Changed Subfile Record)
    12. Update (Update a Record)
    13. Write (Write a Record)
  15. 12. Alternate Syntax Options
    1. Fixed-Format Calculation Specifications
    2. Enhanced-Format Calculation Specifications
    3. Free-Format Calculation Specifications
      1. Commenting Free-Format Code
      2. Free-Format Directives
      3. Free-Format Operation Code Syntax
      4. Myriad Math Syntax Options
    4. Free Format Move/Movel Alternatives
    5. Free Format Data Type Conversion
      1. %CHAR Built-in Function for Conversion
      2. %DATE and %TIME Built-in Functions for Conversion
      3. %DEC Built-in Function for Conversion
      4. Free Format and Data Structures
    6. Free Format Subroutine Declaration
      1. Free Format Date and Time Processing
      2. Retrieving Date Values at Runtime
      3. Alternative Syntax Summary
  16. 13. Web Programming Interfaces
    1. CGI Application Programming Interface (API)
      1. QtmhGetEnv – Get Value of Environment Variable
      2. QtmhPutEnv – Put Environment Variable
      3. Environment Variables
      4. QtmhRdStin – Read from Standard-input
      5. QtmhWrStout – Write to Standard-Output
      6. QtmhCvtDB – Convert to Database Structure
    2. URL ENCODING
      1. atoll() – C Runtime Library Function
  17. A. Compiler Options
    1. Compiler Choices for RPG IV Programs
      1. The CRTBNDRPG Command
        1. PGM (Program Name)
        2. SRCFILE (Source File Name)
        3. SRCMBR (Source File Member)
        4. GENLVL (Generation Severity)
        5. TEXT
        6. DFTACTGRP (Default Activation Group)
        7. BNDDIR (Binding Directory)
        8. ACTGRP (Activation Group)
        9. OPTION
        10. DBGVIEW (Debug View Level)
        11. OUTPUT (Compiler Output Listing)
        12. OPTIMIZE (Optimization Level)
        13. INDENT (Indented Compiler Listing)
        14. CVTOPT (Data Type Conversion Options)
        15. SRTSEQ (Sort Sequence Table)
        16. LANGID (Language Identifier)
        17. REPLACE (Replace Existing Program upon Successful Compile)
        18. USRPRF (User Profile Authority Adoption)
        19. AUT (User Authority)
        20. TRUNCNBR (Truncate Numbers on Overflow)
        21. FIXNBR (Fix Decimal Data Errors for Zoned Numeric Fields)
        22. TGTRLS (Target Operating System Release)
        23. ALWNULL (Allow Null-Capable Fields in Database Records)
  18. B. Decimal Data Errors
    1. Decimal Data Overview
      1. Fix Decimal Data Errors
    2. Database File Models
    3. Zoned Decimal Data
      1. Zoned Decimal Data Errors
    4. Packed Decimal Data
    5. Conditions for Decimal Data Errors
      1. Decimal Data Error upon an Input Operation to a Database File
  19. C. DDS Date and Time Format Considerations
    1. Database Date and Time Overview
    2. Database Date Format and Separator (Edit Character)
      1. Date Separator Keyword
    3. Database Time Format and Separator (Edit Character)
      1. Timestamp Format
    4. Special Dates and Times Values
      1. Display File Support for Date Variables
      2. Additional Dates Routines in RPG xTools
  20. D. Source Code Listings
    1. Return as Uppercase
    2. Convert to Uppercase
    3. Return Length of Input String
    4. In-Line ILE Procedures
    5. Additional Source Listings