DECsystem-10 RPG II Report Program Generator Reference Manual Revision: 2 June 1, 1977 Copyright (C) 1977 Cerritos Community College District and Robert Currier This software is furnished under license for use only on a single computer system and may be copied only with the inclusion of the above copyright notice. This software, or any other copies thereof, may not be provided or otherwise made available to any other person except for use on such system and to one who agrees to these license terms. Title to and ownership of the software shall at all times remain with Cerritos Community College District and Robert Currier. The information in this software is subject to change without notice and should not be construed as a commitment by either Cerritos Community College District or Robert Currier. DECsystem-10 RPG II Reference Manual Page 2 DECsystem-10 RPG II Reference Manual Page 3 Table of Contents CHAPTER 1 INTRODUCTION 1.1 THE RPG II CYCLE ........................ 1-2 1.1.1 Single Input File Processing ......... 1-2 1.1.2 Multiple Input File Processing ....... 1-3 1.1.3 Changes to the Standard Cycle ........ 1-5 1.1.4 Cycle Summary ........................ 1-5 1.2 RPG II FUNCTIONS - THE SPECIFICATIONS ... 1-5 1.3 DEFINITION OF TERMS ..................... 1-7 CHAPTER 2 RPG II SPECIFICATIONS FORMS 2.1 QUICK REFERENCE CHARTS .................. 2-1 CHAPTER 3 COMMON ENTRIES 3.1 PAGE NUMBER ............................. 3-1 3.2 LINE NUMBER ............................. 3-2 3.3 FORM TYPE ............................... 3-2 3.4 COMMENTS ................................ 3-3 3.5 PROGRAM IDENTIFICATION .................. 3-3 CHAPTER 4 CONTROL SPECIFICATIONS -- FORM H 4.1 OBJECT PROGRAM EXECUTION SIZE ........... 4-1 4.2 DEBUG ................................... 4-1 4.3 FORMS POSITIONING ....................... 4-2 CHAPTER 5 FILE DESCRIPTIONS SPECIFICATIONS -- FORM F 5.1 FILENAME ................................ 5-1 5.2 FILE TYPE ............................... 5-2 5.2.1 Input Files .......................... 5-2 5.2.2 Output Files ......................... 5-2 5.2.3 Update Files ......................... 5-3 5.2.4 Combined Files ....................... 5-3 5.2.5 Display Files ........................ 5-3 5.3 FILE DESIGNATION ........................ 5-4 5.3.1 Primary Files ........................ 5-4 5.3.2 Secondary Files ...................... 5-4 5.3.3 Chained Files ........................ 5-5 5.3.4 Record Address Files ................. 5-5 5.3.5 Table or Array Files ................. 5-5 5.3.6 Demand Files ......................... 5-6 5.4 END OF FILE ............................. 5-6 5.5 SEQUENCE ................................ 5-7 5.6 FILE FORMAT ............................. 5-7 5.7 BLOCK LENGTH ............................ 5-7 5.8 RECORD LENGTH ........................... 5-8 5.9 MODE OF PROCESSING ...................... 5-8 5.9.1 Consecutive Processing ............... 5-10 5.9.2 Sequential Processing of Indexed Files 5-10 DECsystem-10 RPG II Reference Manual Page 4 5.9.3 Processing by ADDROUT File ........... 5-10 5.9.4 Random Processing .................... 5-11 5.10 LENGTH OF KEY OR RECORD ADDRESS FIELD ... 5-11 5.11 RECORD ADDRESS TYPE ..................... 5-11 5.12 TYPE OF FILE ORGANIZATION ............... 5-12 5.13 PRINT FILE OVERFLOW INDICATOR ........... 5-12 5.14 KEY FIELD STARTING LOCATION ............. 5-13 5.15 EXTENSION CODE .......................... 5-13 5.16 DEVICE CODE ............................. 5-14 5.17 FILENAME ................................ 5-14 5.17.1 Default Extensions ................... 5-15 5.18 CONTINUATION LINES ...................... 5-16 5.18.1 Column 53 ............................ 5-16 5.18.2 Continuation Lines Options ........... 5-16 5.19 FILE ADDITION AND UNORDERED OUTPUT ...... 5-16 5.20 TAPE REWIND ............................. 5-17 CHAPTER 6 EXTENSION SPECIFICATION -- FORM E 6.1 FROM FILENAME ........................... 6-1 6.2 TO FILENAME ............................. 6-2 6.3 NAME OF TABLE OR ARRAY .................. 6-2 6.4 NUMBER OF ENTRIES PER RECORD ............ 6-3 6.5 NUMBER OF ENTRIES PER TABLE OR ARRAY .... 6-4 6.6 LENGTH OF ENTRY ......................... 6-5 6.7 DATA FORMAT ............................. 6-5 6.8 DECIMAL POSITIONS ....................... 6-6 6.9 SEQUENCE ................................ 6-6 6.10 ALTERNATE TABLE OR ARRAY ................ 6-7 6.11 COMMENTS ................................ 6-7 CHAPTER 7 LINE COUNTER SPECIFICATIONS -- FORM L 7.1 FILENAME ................................ 7-1 7.2 NUMBER OF LINES PER PAGE ................ 7-1 7.3 FORM LENGTH ............................. 7-2 7.4 OVERFLOW LINE NUMBER .................... 7-2 7.5 OVERFLOW LINE ........................... 7-2 CHAPTER 8 INPUT SPECIFICATIONS -- FORM I 8.1 FILENAME ................................ 8-1 8.2 SEQUENCE ................................ 8-2 8.3 NUMBER .................................. 8-3 8.4 OPTION .................................. 8-3 8.5 RECORD IDENTIFYING INDICATOR ............ 8-3 8.6 RECORD IDENTIFICATION CODES ............. 8-5 8.6.1 Position ............................. 8-5 8.6.2 NOT .................................. 8-6 8.6.3 C .................................... 8-6 8.6.4 Record Identification Character ...... 8-6 8.7 ADDITIONAL RECORD IDENTIFICATIONS ....... 8-6 8.8 FIELD TYPE .............................. 8-7 8.9 FIELD LOCATION .......................... 8-7 8.10 DECIMAL POSITIONS ....................... 8-8 DECsystem-10 RPG II Reference Manual Page 5 8.11 FIELD NAME .............................. 8-8 8.11.1 Special Words -- PAGE, PAGE1, PAGE2 .. 8-9 8.12 CONTROL LEVEL ........................... 8-9 8.13 MATCHING FIELDS ......................... 8-10 8.14 FIELD RECORD RELATION ................... 8-11 8.15 FIELD INDICATORS ........................ 8-13 CHAPTER 9 CALCULATION SPECIFICATIONS -- FORM C 9.1 CONTROL LEVEL ........................... 9-3 9.2 INDICATORS .............................. 9-4 9.2.1 AN/OR Lines .......................... 9-5 9.3 FACTOR 1 AND FACTOR 2 ................... 9-7 9.3.1 Field Names .......................... 9-8 9.3.2 Literals ............................. 9-8 9.3.2.1 Numeric ........................... 9-8 9.3.2.2 Alphanumeric ...................... 9-9 9.3.3 Names and Elements ................... 9-9 9.3.4 Date Field Names ..................... 9-9 9.3.5 Special Names ........................ 9-9 9.3.6 Labels ............................... 9-10 9.3.7 Filenames ............................ 9-10 9.4 OPERATION -- COLUMNS 28-32 .............. 9-10 9.4.1 Arithmetic Operations ................ 9-12 9.4.2 Move Operations ...................... 9-12 9.4.3 Move Zone Operations ................. 9-12 9.4.3.1 MHHZO ............................. 9-13 9.4.3.2 MHLZO ............................. 9-13 9.4.3.3 MLLZO ............................. 9-13 9.4.3.4 MLHZO ............................. 9-13 9.4.4 Compare, Bit and Test Operations ..... 9-13 9.4.4.1 COMP .............................. 9-13 9.4.4.2 BITON, BITOF, TESTB ............... 9-18 9.4.4.3 TESTZ ............................. 9-19 9.4.5 Branch and Exit ...................... 9-19 9.4.5.1 GOTO .............................. 9-20 9.4.5.2 TAG ............................... 9-20 9.4.5.3 EXSR .............................. 9-20 9.4.5.4 BEGSR ............................. 9-21 9.4.5.5 ENDSR ............................. 9-21 9.4.5.6 EXIT .............................. 9-21 9.4.5.7 RLABL ............................. 9-21 9.4.6 Indicator Operations ................. 9-21 9.4.6.1 SETON ............................. 9-21 9.4.6.2 SETOF ............................. 9-22 9.4.7 Table Operation ...................... 9-22 9.4.7.1 LOKUP With One Table .............. 9-23 9.4.7.2 LOKUP With Two Tables ............. 9-23 9.4.7.3 LOKUP With Arrays ................. 9-23 9.4.8 Input/Output Operations .............. 9-27 9.4.8.1 EXCPT ............................. 9-27 9.4.8.2 FORCE ............................. 9-27 9.4.8.3 DSPLY ............................. 9-28 9.4.8.4 READ .............................. 9-28 9.4.8.5 CHAIN ............................. 9-29 DECsystem-10 RPG II Reference Manual Page 6 9.4.8.5.1 Random Input Processing ........ 9-29 9.4.8.5.2 Direct File Output Load ........ 9-29 9.4.9 DEBUG Operation ...................... 9-30 9.4.10 TIME Operation ....................... 9-32 9.5 RESULT FIELD ............................ 9-32 9.6 FIELD LENGTH ............................ 9-33 9.7 DECIMAL POSITIONS ....................... 9-33 9.8 HALF ADJUST ............................. 9-33 9.9 RESULTING INDICATORS .................... 9-34 9.10 COMMENTS ................................ 9-35 9.11 CALCULATION SPECIFICATIONS EXAMPLES ..... 9-35 CHAPTER 10 OUTPUT-FORMAT SPECIFICATIONS - FORM O 10.1 FILENAME ............................... 10-1 10.2 AND/OR RELATIONSHIPS ................... 10-1 10.3 RECORD TYPE ............................ 10-2 10.4 ADD RECORD ............................. 10-4 10.5 FETCH OVERFLOW ......................... 10-4 10.6 FORMS CONTROL - SPACE/SKIP ............. 10-7 10.6.1 Space Forms Control ................. 10-7 10.6.2 Skip Forms Control .................. 10-7 10.7 OUTPUT INDICATORS ...................... 10-8 10.8 FIELD NAME ............................. 10-9 10.8.1 Field Names ......................... 10-9 10.8.2 PAGE, PAGE1, PAGE2 .................. 10-10 10.8.3 *PLACE .............................. 10-10 10.8.4 Date Field .......................... 10-11 10.9 EDIT CODES (COLUMN 38) ................. 10-11 10.10 BLANK AFTER ............................ 10-11 10.11 END POSITION IN OUTPUT RECORD .......... 10-14 10.12 FIELD TYPE ............................. 10-14 10.13 CONSTANT OR EDIT WORD .................. 10-14 10.13.1 Constants ........................... 10-15 10.13.2 Edit Code Modifiers -- * and $ ...... 10-15 10.13.3 Edit Words .......................... 10-15 10.14 OUTPUT-FORMAT SPECIFICATIONS EXAMPLES .. 10-17 CHAPTER 11 USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING 11.1 FORMING TABLES AND ARRAYS .............. 11-5 11.2 USING TABLES AND ARRAYS ................ 11-12 CHAPTER 12 RPG II FILE PROCESSING 12.1 SEQUENTIAL FILE PROCESSING ............. 12-1 12.1.1 Matching Records .................... 12-2 12.1.2 Look-Ahead Fields ................... 12-8 12.2 INDEXED FILE PROCESSING ................ 12-13 12.3 DIRECT FILE PROCESSING ................. 12-13 APPENDIX A SUMMARY OF RPG II SPECIFICATIONS A.1 COMMON ENTRIES .......................... A-1 A.2 CONTROL SPECIFICATIONS - FORM H ......... A-3 DECsystem-10 RPG II Reference Manual Page 7 A.3 FILE DESCRIPTION SPECIFICATION - FORM F . A-4 A.4 EXTENSION SPECIFICATION - FORM E ........ A-8 A.5 LINE COUNTER SPECIFICATIONS - FORM L .... A-10 A.6 INPUT SPECIFICATIONS - FORM I ........... A-11 A.7 CALCULATION SPECIFICATIONS - FORM C ..... A-15 A.8 OUTPUT-FORMAT SPECIFICATIONS - FORM O ... A-18 APPENDIX B REFERENCE TABLES APPENDIX C RPG II CYCLE APPENDIX D CHARACTER SETS APPENDIX E RPG II HALT PROCEDURES APPENDIX F COMMAND STRINGS APPENDIX G RPG II STANDARD CALLING SEQUENCE G.1 EXIT OPERATION .......................... G-1 G.2 RLABL SPECIFICATION ..................... G-1 CHAPTER 1 INTRODUCTION DECsystem-10 RPG II is a one-pass multi-phase compiler and run time system. Along with the other programs on the DECsystem-10, RPG II resides on the system device, a disk. RPG II operations have three phases; compilation, linking, and execution. Input to the compilation phase is a set of specifications for the application program, and sometimes additional data arranged in tables or arrays. Such data is usually information that is unlikely to change for the life of the program. Output from the compilation phase includes (1) a relocatable binary (REL) module (input to the linking loader) and (2) a listing of the specifications plus any error messages. Once the listings indicate error-free specifications, the user can make the REL module "executable" by running the linking loader (LINK) program. LINK takes the REL module and produces an executable core image. This core image may then be saved as an EXE file so that later runs do not require the user to relink the RPG II program. The user may store the REL module or the EXE file on disk, DECtape, or magtape. The EXE file plus data stored in files or entered from a terminal make up the input to the execution phase. The execution phase can occur repeatedly with different data. The output of that phase is determined by the application. It may include reports, modifications to the input data files, or completely new data files. In addition to the EXE file, the object program makes use of a collection of routines, called the Object Time System (OTS or RPGLIB). Because these routines are needed by all RPG II users, they are implemented as sharable code, so that only one copy must be present on the machine, regardless of the number of users. RPG II OTS can perform sequential access with files on any device. In addition, disk allows (1) indexed and random access by key or record number and (2) access according to a separate file called a Record Address File. Record Address Files list which records to process in the order of processing. Indexed files are actually two files; one containing the data and the other containing the index. INTRODUCTION Page 1-2 1.1 THE RPG II CYCLE RPG II works from this premise: most business applications which process data files perform the same operations on a significant number of records in the files. Hence, RPGLIB can work in a standard cycle--roughly, input a record, process it, and output some data. 1.1.1 Single Input File Processing The simplest case involves a program to process a single input file with a single record type. Example: a program to read a file of sales records, print buyer and price, and show total receipts at the end. An RPG II specification for such a program would contain (1) a description of input and output files and records, and (2) a single calculation statement to specify continued summing of the receipts for each record. RPGLIB would accomplish all input and output, one record at a time, in the standard cycle. In single input file processing, there can be at least three areas of complication: (1) files with different record types, (2) look ahead fields, and (3) different levels in the report structure. A sales file with different record types might have a type for each product line, and one for salesmen, as well. When a file has more than one record type, users can assign internal switches called "indicators" for "conditioning" calculations and/or output according to the type of record currently being processed. When a file has multiple record types, the cycle remains the same, but different things can happen for different records. In addition, record type groups can be specified to reflect well-structured files. Example: a product line record must be followed by exactly one statistical record and then by any number of (or no) salesmen records. The look-ahead capability allows RPGLIB to examine fields in the next record while it is processing the current one. This is useful, for example, when the program is processing a file with multiple record types, and the user needs to know the next record's type in order to handle correctly the current record. Levels in the report structure often correspond to the management levels in a company. Thus, a sales report for a national company might show subtotals at the salesman, office, district, and regional levels, and end with a total for the whole company. Calculations appropriate for the salesman level may be irrelevant to other levels, and vice-versa, so RPG II gives users easy methods for specifying the correct level for calculations. The Object Time System can automatially set an indicator when, say, the office number changes from one record to the next. For a national company, a master sales file with one record per sale might list sales by order number within salesman, within office, within district, within region. If the file is sorted in that hierarchy, a change in one level (the next district, perhaps) implies a change in all lower levels (office and salesmen), so that totals for INTRODUCTION Page 1-3 all those levels (district, office, and salesman) are required. Each time the salesman listed on the record is different from the one listed on the previous record, the program might total up the previous man's sales and print out information needed for the salesman level. Then, RPGLIB would do detail calculations and output for the new record. Each time office, district, or region differs from that on the previous record, RPGLIB could do all lower level calculations until it completes those for the level that caused the interruption. These interruptions are called control breaks. Users must specify which parts of the records (control fields) pertain to each level, and which calculations and output should be done when each level's control break occurs. He can leave the rest up to the RPG II cycle. When control break processing has been specified, the RPG II cycle is expanded to become (1) input, (2) determine whether a control break has occurred: if not, go to step (5); (3) perform control break calculations (also called total calculations); (4) perform control break (total) output; (5) perform detail calculations; (6) perform detail output. 1.1.2 Multiple Input File Processing Multiple Input File processing can be quite complicated. Each file may have the complexity of a single file, and the files can be interrelated, as well. The user has complete control over the order in which RPGLIB reads records. When he does not exercise that control, however, RPGLIB reads and processes one file after the other, as if all the files were strung end-to-end. In cases where files are interrelated, the user can specify matching records. Matching records involves a comparison of field(s) from records in several input files. When the fields match, RPGLIB turns on the matching record indicator and selects the record for the current cycle according to the order indicated by the file specifications forms. When records do not match, RPGLIB selects the record whose matching record field(s) are first in the collating sequence. As with record types and control levels, the matching record indicator can condition calculations and output. Matching records operations allow simplified file merging. Example: incorporation of a transaction file into a master file. Refer to paragraph 12.1 for more information. INTRODUCTION Page 1-4 Figure 1-1 Typical RPG II Flow INTRODUCTION Page 1-5 1.1.3 Changes To The Standard Cycle In cases where the above operations do not apply, the user can specify which file to read on the next cycle, or even modify the cycle entirely by using special input and output commands. 1.1.4 Cycle Summary As the above discussion implies, RPG II distinguishes between operations done each cycle and those done only after a control break. Operations done each cycle are called detail operations; the others are total operations. Control breaks occur when RPGLIB reads a record with a control field different from the last record's control field. All input records processed between one control break and the next constitute a control group. Since breaks occur only when RPGLIB reads a record from outside the current control group, RPGLIB does processing for the control break before it does detail operations for the current record. In addition to detail and total operations, there are 1P (first page) output operations and LR (last record) operations. 1P output is unique to the first cycle. It must be conditioned by the 1P indicator, and may include printing the title of a report or positioning preprinted forms on the printer. When RPGLIB reaches the end of the last file to be processed, it sets the LR indicator. Users can condition calculations and output to occur after the last cycle by using the LR indicator. 1.2 RPG II FUNCTIONS -- THE SPECIFICATIONS FORMS Figure 1-1 illustrates the function flow of RPG II. In that figure, original input is shown as punched card files. Interactive data terminals, disk, and a magtape can also supply input data. output can go to a printer, a terminal, disk, or a magtape. After someone has produced an initial statement showing the desired results, production of most RPG II programs involves four steps: (a) coding and creating the specifications for the report program; (b) compilation of an object program that meets the specifications; (c) task building the object program with the necessary run-time routines; and (d) executing the task module. The specifications mentioned in steps (a) and (b) have several possible formats, seven of which DIGITAL supplies on preprinted coding forms. There is a control specification for the whole job, and there are six form types for input, calculation, and output. The Control Specification (Form H) supplies ___ _______ _____________ _____ __ information pertaining to the compilation as a whole. INTRODUCTION Page 1-6 The File Description Specification (Form F) and ___ ____ ___________ _____________ _____ __ ___ the Extension Specification (Form E) describe the ___ _________ _____________ _____ __ files, tables, and arrays to be used by the program. The Line Counter Specification (Form L) gives ___ ____ _______ _____________ _____ __ special information about print files. The Input Specification (Form I) describes the ___ _____ _____________ _____ __ input records in the files named in Forms F and E. The Calculation Specification (Form C) describes ___ ___________ _____________ _____ __ the operations to be performed. The Output Specification (Form O) describes the ___ ______ _____________ _____ __ format and contents of the output files named in Form F. In addition, the user may specify: (1) the contents of tables and arrays which won't change for the life of the program; and (2) alternate collating sequence tables to modify the standard ASCII collating sequence in certain operations. These two specification types do not require special coding forms, but they must be prepared according to well-defined formatting rules. The relationships of form type to logical specification area are shown in Table 1-1. Table 1-1 Summary of Form Types Specification Forms Logical Specification Area _____________ _____ _______ _____________ ____ Input Calculation Output _____ ___________ ______ Control Specification (H) File Description (F) X X File Extension (E) X X Line Counter (L) X Input (I) X Calculation (C) X X X Output-Format (O) X Chapter 2 summarizes the form types for experienced RPG users. Chapter 3 through 10 describe all form types in detail. For this introductory discussion of RPG II problem specifications, the orientation will be in terms of the logical specification areas rather than the physical form types. The user describes the input to be available to the object program in terms of files, records, fields and file devices. A file is an aggregation of data that is organized for a consistent purpose. Examples: inventory file, employee file, accounts payable file, file of equipment characteristics. A record is the major entry of a file. Records usually carry an identification value and a number of INTRODUCTION Page 1-7 additional information elements called fields. Example: an inventory file includes records for each item in the inventory identified by the item stock number. The item stock number of an inventory record is considered a field, as is the item balance and the bin location. The description of input need only be complete enough to allow selection of necessary records and fields. The user can omit descriptions of fields not germane to desired processing. File devices are the computer's equipment media for input and output. In the calculation specifications the user describes the conditions under which each calculation operation is to be performed. Examples of conditions: presence or absence of a record identifying code, a specified control level, a positive result of a previous calculation or retrieval of the last record of a file. The calculation operations include arithmetic, movement of fields, comparisons, definition of internal subroutines, execution of internal subroutines, setting of indicators for later reference, setting and testing of flag bits, table lookup, and limited input/output operations. The output specifications describe the files, records, fields, and file devices for the output. The specifications also include the conditions which must be met for output to be produced. For files to be updated, output specifications must supplement the descriptions provided in the input specifications. For a new output file to be produced, the record organization and field positions are given. For listing output, the editing desired for fields is described. Editing includes functions such as zero suppression, insertion of floating dollar sign, insertion of credit balance symbol, and printing numeric fields with commas and a decimal point. The RPG II compilation of an object program for which specifications have been prepared is performed under control of the RPG II Compiler. If specification errors are found, indicative messages are printed. Compilation is completed and task building is allowed, even though errors are found which would prohibit successful execution. Certain omissions from specifications can be tolerated. In such cases, the compiler may insert default values and processes into the object program. The occurence of default cases, insertions, and subroutines is noted in the printed record of the compilation. 1.3 DEFINITIONS OF TERMS Alphabetic Characters - The ASCII characters A through Z __________ __________ Alphanumeric Characters - The set of 128 ASCII characters ____________ __________ Alphanumeric Fields - A field for which a decimal place entry ____________ ______ was omitted from a specification form. ASCII Character Set - The set of 128 seven-bit ASCII _____ _________ ___ characters (listed in Appendix D). INTRODUCTION Page 1-8 Compilation Time - The time at which the RPG II compiler ___________ ____ accepts source program specifications, produces program and diagnostic listings, and generates the object program. Detail Time - The time when those operations not conditioned ______ ____ by control level indicators are executed. EBCDIC Character Set - An alternate character set widely used ______ _________ ___ in the computing industry. Execution Time (or Run Time) - The time during which object _________ ____ ___ ___ _____ program cycles are being executed. Numeric Characters - The ASCII characters 0 through 9. _______ __________ Numeric Field - A field for which a decimal place entry _______ _____ (including 0) was made on a specifications form. Only numeric characters are valid in a numeric field. Pre-Execution Time - The time during which the object program _____________ ____ is entering execution: i.e., when the object program has been loaded into core memory, input/output files are being opened, certain Tables and Arrays are being read, and just before the first program cycle is executed. Record Key - The field or fields that uniquely identify a ______ ___ record in an indexed file. The Record Key determines the order in which the records may be sequentially processed. RPG II Names - ___ __ _____ Filename - Up to eight alphabetic and numeric ________ characters. The first character of a filename must be alphabetic, and the first six characters of a filename must be a unique combination. Embedded blanks are not allowed. Filenames are left-justified in the fields in which they appear. Field Name - Up to six alphabetic and numeric _____ ____ characters. All the restrictions listed above for filenames also apply to field names. Special Characters - The 91 nonalphanumeric ASCII characters. _______ __________ Total Time - The time after a control break when operations _____ ____ for a control group occur. (See paragraph 1.1.4.) CHAPTER 2 RPG II SPECIFICATIONS FORMS As described in Chapter 1, an RPG II source program consists of a series of records or lines originally written on formatted coding sheets called RPG II Specifications forms, and transcribed into machine readable form. There are seven different RPG II Specifications forms, each designed for a specific purpose; not all, however, are mandatory for a given job. Table 2-1 lists the seven forms in the order in which they appear in the source program and indicates the minimum and maximum number of lines allowable. 2.1 QUICK REFERENCE CHARTS The following pages contain a separate chart for each of the seven RPG II Specifications forms. Each chart presents a summary of the use and content for entries on the form. For readers already familiar with RPG or RPG II, these reference charts should be basically self-explanatory. Should the reader encounter an entry whose usage or content differs from the RPG version with which he is familiar, he can refer to the detailed description or further clarification. For readers new to RPG II, these charts will serve as a general overview of the RPG II Specifications forms. After scanning them and becoming familiar with the basic purpose of each, these readers should continue with Chapters 3 through 10. Once the user begins working with RPG II, he will find these charts helpful as a reference source for refreshing his memory or checking the correctness of entries. DIGITAL also supplies these forms as separate forms guides. RPG II SPECIFICATIONS FORMS Page 2-2 Table 2-1 RPG II Specifications Forms: Minimum Required and Maximum Allowable Form Type Minimum # of Maximum # of ____ ____ Lines Required Lines Allowed _____ ________ _____ _______ Control Specification 1 1 File Description Specifications 1 20 Extension Specifications 0 NSL Line Counter Specifications 0 2 Input Specifications Lines required to describe one NSL input file Calculations Specifications 0 NSL Output-Format Specifications Lines required to describe one NSL output file The minima given for Input and Output are practical limits. A working _________ RPG II program could be run with special I/O commands from Form C, and no Form I or no Form O. That would be unusual, however. __ __ NSL = No Specific Limit -- depends on a combination of factors, such as core memory available and space used by other components. RPG II SPECIFICATIONS FORMS Page 2-3 RPG II SPECIFICATIONS FORMS Page 2-4 RPG II SPECIFICATIONS FORMS Page 2-5 RPG II SPECIFICATIONS FORMS Page 2-6 RPG II SPECIFICATIONS FORMS Page 2-7 RPG II SPECIFICATIONS FORMS Page 2-8 RPG II SPECIFICATIONS FORMS Page 2-9 CHAPTER 3 COMMON ENTRIES This chapter describes Specifications Form entries that are common to all RPG II coding sheet formats, except the forms described in Chapter 11. The common entries are: Columns 1-2 Page Number Page and line together make up the "Sequence Columns 3-5 Line Number Number". Column 6 Form Type Column 7 Comments Columns 75-80 Program Identification 3.1 PAGE NUMBER Column Values ______ ______ 1-2 01-99 These columns ordinarily receive the number filled in at the upper right corner of each coding sheet. Those specification types used must come in the following order: Control Specifications File Description Specifications Extension Specifications Line Counter Specifications Input Specifications Calculation Specifications Output - Format Specifications A specifications type may require more than one sheet, but the listed COMMON ENTRIES Page 3-2 order by type must be maintained. 3.2 LINE NUMBER Columns Value _______ _____ 3-5 Any 3-digit number Most of the lines on each form have two-digit numbers already printed in columns three and four. If the line number is completed by entering a zero in column 5, the lines are numbered by tens on each specifications page. This is a helpful convention, because it allows the user to subsequently insert lines without re-numbering. Programmers can use the unnumbered lines at the bottom of the form for insertion. 3.3 FORM TYPE The form type is preprinted in column six on each Specification Form. The compiler uses this column to determine the type of specification of each source statement. Column Values Meaning ______ ______ _______ 6 H Control Specifications F File Description Specifications E Extension Specifications L Line Counter Specifications I Input Specifications C Calculation Specifications O Output-Format Specifications 3.4 COMMENTS Column Values Meaning ______ ______ _______ 7 * This specification contains comments only COMMON ENTRIES Page 3-3 blank This is a normal specification line The compiler treats as a comment any line containing an asterisk in column 7. Columns following the asterisk may contain any ASCII characters. The compiler checks the sequence and prints comments lines in the source program listing. Otherwise, it ignores them. 3.5 PROGRAM IDENTIFICATION Columns Values _______ ______ 75-80 Blanks or a valid RPG II name This field has meaning only on the Control Specification; for other form Specs. it will be listed but otherwise ignored by the compiler. RPG treats the name entered in columns 75-80 of the Control Specification as the internal program name, and includes it on the header of the listing. CHAPTER 4 CONTROL SPECIFICATIONS -- FORM H The Control Specifications form is optional. In the absence of a Control Specification form, a blank form is assumed. The shaded areas of Figure 4-1 indicate the areas of the form containing information pertinent to the RPG II compilation. Other columns, except those listed in Chapter 3, should contain blanks. 4.1 OBJECT PROGRAM EXECUTION SIZE Columns Value Meaning _______ _____ _______ 13-14 Blank The object program will be compiled to use as much space as necessary. No check is made to see if this much is available. 01-64 The main storage available for program execution. Use columns 13-14 to specify some multiple of 1K words of storage (K = 1024). Columns 13-14 define the main storage available for program execution (not including storage space requirements for the runtime system). The entry must end in column 14. Because the current runtime system does not expand the user's program storage space dynamically, these columns have little practical use. 4.2 DEBUG Column Values Meaning ______ ______ _______ 15 blank Do no DEBUG operations. 1 Do any requested DEBUG operations. CONTROL SPECIFICATIONS -- FORM H Page 4-2 The DEBUG specification indicates whether or not a DEBUG operation will (1) or will not (blank) be performed. (Chapter 9 explains the DEBUG specification.) A DEBUG operation will be performed only when requested by this specification and by a DEBUG operation code on a Calculations Specifications form. Thus, when a program has been debugged, the only change required to eliminate the DEBUG checks is in this one column of the Control Specification. 4.3 FORMS POSITIONING Column Values Meaning ______ ______ _______ 41 Blank No forms positioning required. 1 Forms positioning required. Users should specify forms positioning when line printer output must go onto pre-printed forms, such as check blanks. When requested, forms positioning allows the operator to correctly position output forms by first printing a test line. When forms positioning has been specified, RPG II enters the 1P Halt Procedure (see Appendix E). A BYPASS response will continue the execution; a CONTINUE response will give another 1P line and a repetition of the Halt Procedure. Forms positioning may only be used when the printer is directly assigned to the user's job. It will not work properly when the printer spooler is intercepting output. CHAPTER 5 FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Programmers must name and describe all files to be handled at runtime on Form F, the File Description Specifications. Figure 5-1 illustrates the File Descriptions Specifications Form. Form F describes all files except compile-time tables and arrays. Those are described only on Form E. Information about file records must appear on other forms, depending on the type of file: Input data records are described on Input Specifications -- Form I Output data records are described on Output Format Specifications -- Form O Update records are described on both Form I and Form O In addition, Record Address files and Pre-execution and Execution time tables and arrays are further described on Extension Specifications -- Form E. Display File records need no extra forms. Each file requires a single line of Form F. RPG programs can handle a maximum of sixteen files. 5.1 FILENAME A unique filename identifies each file to be handled by the object program. Columns Value _______ _____ 7-14 Any valid RPG II filename Use columns 7-14 to assign a unique filename to every file used in your program except compile time table and array files, which must not be named on the File Descriptions Specifications sheet. The filename can be from 1 to 8 characters long, must begin in column 7, and must be a valid RPG II name. The filename can be the same as a field name. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-2 Pre-execution time table and array files are described on the File Description Specifications sheet. More than one table or array file can be described for device READ01, but the File Description entries must be in the same order as the tables that are to be loaded. Thus if you are going to load tables TABA and TABB from READ01, and TABA is associated with FILEA, and TABB with FILEB; if the data for TABA is to be loaded first, the File Description entry for FILEA must precede that for FILEB. 5.2 FILE TYPE Column Value Meaning ______ _____ _______ 15 I Input file O Output file U Update file C Combined file D Display file Use column 15 to identify the way in which your program is to use the file. 5.2.1 Input File Input files are records that the program uses as a source of data. When input files are described in a program it indicates that records are to read from the file. All input files except table and record address files must be further defined on the Input Specifications sheet. Table and record address files must be further described in the Extension Specifications. 5.2.2 Output Files Output files are records that are written or printed by a program. All output files, except table and array output files, must be further described on the Output Format Specifications Sheet. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-3 5.2.3 Update Files Update files are disk files from which a program reads a record, updates fields in the record, and writes the record back in the same location from which it was read. Update files must be further described on both the Input Specification sheet and the Output Format sheet. A record in an update file can be updated only once during a cycle (see Output File - Output Indicator description). A chained file or a demand file may be updated at detail time, total time, or execution time. All other files should be updated only at detail time, during the same program cycle that reads the record, otherwise, results of the update will be unpredictable at best. 5.2.4 Combined Files A combined file is both an input and an output file. A combined file can only be assigned to the simulated MFCU. A program reads records from a combined file and includes output data on the records in the file. The result is one file that contains both input and output data. Combined files must be further described on both the Input Specification Sheet and the Output Format Sheet. Do not condition output to a combined file such that more than one record can satisfy the output conditions during the same cycle. (This condition should not exist for the entire detail output cycle, even if output is going to more than one combined file.) All output records to a combined file are stored in a hold area until another record is read from the combined file. The output record is punched just prior to the time the next record is read. Since each record stored in the hold area overlays and replaces any previous record in the hold area, only one record can be available as output to a combined file during any one RPG II cycle. This record will be the last record that satisfied output conditions during the cycle. 5.2.5 Display Files A display file is a collection of information from fields used by a program. The DSPLY operation code must be used on the Calculation Specification Sheet in order to print a field or record directly from storage and/or key data into a field or record in storage. Display files need only be described on the File Description Specifications Sheet. The device associated with a display file must be an interactive terminal (CONSOLE). See DSPLY in Chapter 9 for more information. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-4 5.3 FILE DESIGNATION Column Value Meaning ______ _____ _______ 16 P Primary file S Secondary file C Chained file R Record Address file T Table or array file (pre-execution time tables or arrays) D Demand file Use column 16 to further identify the use of input, update, combined, and chained output files. Leave this column blank for display files and all output files except chained output files (direct load). 5.3.1 Primary Files A primary file is the main file from which a program reads records. In multifile processing the primary file is used to control the order in which records are selected for processing. It can be an input, update, or combined file. In programs that read records from only one file, that file is the primary file. Every program must have exactly one primary file. 5.3.2 Secondary Files Secondary files apply to programs that do multifile processing. All of the files involved in multifile processing, except the primary file, are secondary files. A secondary file can be an input, update, or combined file. Secondary files are processed in the order in which they are written on the File Description Specifications Sheet. Note that table, chained, record address, and demand files are not involved in record selection in multifile processing. See Multifile Processing (columns 61-62) in Chapter 8 for more information on primary and secondary files. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-5 5.3.3 Chained Files A chained file is a disk file that is read randomly or loaded directly via the CHAIN operation code. A chained file can be an input, output, or update file. See Column 28 (Mode of Processing, Random) in this chapter, and the CHAIN operation code in Chapter 9 for more information. 5.3.4 Record Address Files A record address file is an input file that indicates which records are to be read from a disk file, and the order in which those records are to be read. A record address files must be further defined in the Extension Specifications. Record address file contain binary relative record numbers. Because the record number are stored as 18-bit binary numbers, record address files can only reside on disk or tape. Record address files on disk are call ADDROUT (address output) files. They can be produced by a disk sort program and can be used with any type of disk file, except ISAM files. See Column 28 (Mode of Processing, via ADDROUT) in this chapter for more information. 5.3.5 Table Or Array Files A table or array file is a sequential input file that contains table or array entries. The entries can be read into the program during compilation or immediatly before execution of the program. Only pre-execution time table or array files are described on the File Description Sheet. However, both pre-execution and compile time tables and arrays must be described on the Extension Specifications sheet. A table or array output file (written or punched after LR output) is defined as a normal output file and does not require an entry in column 16. Table and array files are not involved in record selection and processing. They are only a means of supplying entries for tables and arrays used by the program. When table or array files are read during the execution of the program, the program reads all the entries from the table and array files before it begins record processing. See Tables and Arrays in Chapter 6 for additional information. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-6 5.3.6 Demand Files Demand files can be input, update, or combined files. The READ operation code must be used on the Calculation Specification Sheet in order to read from a demand file. Demand files may be processed either sequentially by key, or consecutively. See the READ operation code in Chapter 9 for a discussion of the processing of demand files. 5.4 END OF FILE Column Value Meaning ______ _____ _______ 17 Blank a. If none of the Primary, Secondary, or Record Address files has an 'E' in its specification, RPGLIB will read all such files to their end. b. If any has an 'E' in its specification, those with a blank in column 17 need not be read to end of file. E RPGLIB will read this file to its end before performing end-of-job process- ing. In single file processing, RPGLIB will read the Primary File to its end, regardless of column 17 in the File Specification. In multi-file processing, RPGLIB will process all files to end-of-file, unless some have an "E" in column 17 of their Specifications. In that case, it will process all files with an "E" to their completion. EXCEPTION: When the primary file is the only file with an "E" in column 17, and a matching records operation has been specified between it and one or more secondary files, and record(s) in the secondary file(s) which match the last record of the primary file are read and processed before end-of-job operations. When processing with a Record Address file, end-of-file processing is specified for the Record Address file, not for its object file. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-7 5.5 SEQUENCE Users may request RPGLIB to monitor the order of input records. Column Values Meaning ______ ______ _______ 18 Blank RPGLIB need not check sequence A This is a sequential primary or secondary file. The value of the fields specified by M1-M9 should be lowest in the first record, and equal or higher in each succeeding record. D This is a sequential primary or secondary file. The value of the fields specified by M1-M9 should be highest in the first record, and equal or lower in each succeeding record. An entry in column 18 is required when matching fields (columns 61-62) are specified on form I. Files with matching fields must be either all Ascending or all Descending. This column does not apply to tables and arrays, Chain, Demand or Record Address files. 5.6 FILE FORMAT Column Value ______ _____ 19 F Column 19 must contain an F to indicate that all the records in the file have a fixed length. 5.7 BLOCK LENGTH Column Value Meaning ______ _____ _______ 20-23 1-4096 Number of characters in each logical block of a file Block length must either equal the record length value specified in columns 24-27, or it must be an integer multiple of record length. Block length can not be greater than the maximum record length for the device. The blocking factor of a file is calculated by dividing the Block Size FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-8 by the Record Length. If the block and record sizes are equal, RPG II calculates the optimum blocking factor based on the file devices physical characteristics. All ASCII files are unblocked. 5.8 RECORD LENGTH Columns Values Meaning _______ ______ _______ 24-27 1-4096 Number of characters per record These columns specify the length of all records in the file. For an Update file, record length must not vary between input and output phases. The value is right-adjusted, and leading zeroes may be suppressed. The maximum record length for each device type is as follows: Device Maximum Record Length ______ _______ ______ ______ MFCU 96 READ01 80 PRINTER 132 CONSOLE 132 DISK 4096 TAPE 4096 5.9 MODE OF PROCESSING RPGLIB must know in advance how it will process each file. Column Values Meaning ______ ______ _______ 28 Blank a. Access will be consecutive, or b. Access will be sequential, in the order the records appear in the index. This is called sequential by key. R a. Access will be random by relative record number or by key, or b. An ADDROUT record address file will determine access, or c. This will be a direct (random) file load. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-9 Users must coordinate the file type (column 16) with the file processing mode (column 28), the record address type (column 31), and the file organization (column 32) for all Input and Update files. Input files not resident on disk have sequential organization and must be accessed consecutively. Such files must be designated Primary, Secondary, Demand, Table/Array, or Record Address with record key limits and their specifications must contain blanks in columns 28 and 31, and blank or 1-9 in 32. Direct or indexed Input and Update files must reside on disk. Table 5-1 illustrates the legal combinations of entries in columns 16, 28, 31, for any Input or Update files stored on disk. Table 5-1 Legal Combinations for Input or Update Disk Files FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-10 5.9.1 Consecutive Processing (Blank In Column 28) Consecutive processing occurs when a program examines each record as it occurs on a medium. RPGLIB can do consecutive processing on files on any device; it can only do consecutive processing on non-random access devices. The nature of such devices requires RPG II to examine each record as it appears -- for example, one card after the other. Disk allows several file organizations. The only ones suited for consecutive processing are sequential and direct organizations. A sequential organization occurs when records come one right after the other, just as in a card deck or magnetic tape. A direct organization is similar to sequential, but gaps may occur in the file, to allow for future additions. (One might simulate direct organization in a card file by inserting blank cards every so often.) The gaps are really records filled with blank characters. Users should test for such gaps when processing a direct organized file. 5.9.2 Sequential Processing Of Indexed Files By Key (Blank In Column 28) Sequential processing by key is similar to consecutive processing in that the index entries are accessed consecutively, but the data records of the file are processed in the order determined by the index. Primary, Secondary, and Demand files may be processed sequentially by key. Sequential processing by key requires an indexed file. Files with indexes work just like books with indexes. In books, key words are scattered all through the volume. The index lists the key words in alphabetic order, and gives their location. In an indexed file, records may be scattered here and there on the device, but the index lists the record keys in an order, and gives the record location within the file. Indexed files are a little more complicated than books, because book indexes are always in alphabetic order, but file indexes may have one of a variety of orders. For example, in a file that contains information about employees, an index might be ordered by employee name, employee number, employee address, department, or salary. Whichever field governs the order of the index is called the key. Each index entry contains the key value and number of each record in the file. Keys must always have an ascending order before RPGLIB can process an indexed file. 5.9.3 Processing By ADDROUT File (R In Column 28) A sort utility program can produce ADDROUT files, which are Record Address files containing record numbers. They are similar to the indexes for indexed files, but they do not contain keys. When a programmer has produced more than one ADDROUT file, he can process the same data file in one order one time and in another order (with a FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-11 different ADDROUT file) at a different time. Although ADDROUT files may reside on disk or magnetic tape, their object files (the files they point to) may reside only on disk. 5.9.4 Random Processing (R In Column 28) Random processing applies to Chained files and occurs only when requested by a CHAIN operation code. (CHAIN is described in paragraph 9.4) CHAIN retrieves records from sequential and direct files according to a record number. With indexed files, record retrieval is based on a key value in the record. 5.10 LENGTH OF KEY OR RECORD ADDRESS FIELD Indexed files and ADDROUT files must have an entry in this field. Columns Values Meaning _______ ______ _______ 29-30 Blank Output, Input, Update or Demand file to be processed sequentially, or chained file by relative record number. 1-64 Indexed file with key length as entered. The value must be right-justified in the field, and leading zeroes may be suppressed. 5.11 RECORD ADDRESS TYPE This entry gives more information about how RPGLIB is to retrieve records from the file. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-12 Column Values Meaning ______ ______ _______ 31 Blank a. Output file, or b. Chained sequential/direct file, or c. Input or update file, and access will be consecutive. A Access will be via an alphameric key. I a. This is an ADDROUT file, or b. This file will be processed via an ADDROUT file. 5.12 TYPE OF FILE ORGANIZATION This entry gives additional information about file organization. Column Values Meaning ______ ______ _______ 32 I Indexed (ISAM) file T ADDROUT file Blank Sequential or direct file NOTE: ISAM files require an "A" in column 31. 5.13 PRINT FILE OVERFLOW INDICATOR This entry allows the user to name an overflow indicator to be associated with a print file. Columns Value Meaning _______ _____ _______ 33-34 Blank a. Not a print file, or b. Print file with no overflow indicator associated with it. OA-OG or OV Print file, and the name of its overflow indicator is the two characters entered. The overflow indicator is associated with the area of the print page starting with the overflow line and ending with the bottom of the page. This area is called the overflow area, and it can be specified via Form L (see Chapter 7). RPGLIB turns on the named overflow indicator when a space or skip terminates in the overflow area. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-13 Paragraph 10.5 discusses overflow in detail. Overflow indicators can be turned on and off by SETON and SETOF operation codes and may be used with control level indicators L0-L9. Use of overflow indicators with other indicators may cause a variable number of lines to be printed on successive pages. The user should take care to leave enough room for the maximum, and yet retain good spacing on the page when few lines are printed. 5.14 KEY FIELD STARTING LOCATION RPG II must know the location of the key field in the records of indexed files. This entry specifies the first (high order) position of the key field. Column Values Meaning ______ ______ _______ 35-38 Blanks Not an indexed file. 1-4096 Indexed file; the key starts at the character with the number entered. The entry must be numeric and right justified. Leading zeroes may be omitted. An entry of blanks or zeroes in columns 35-37, and 6 in column 38 specifies the key field starting location in the example above. 5.15 EXTENSION CODE Print files, Record Address files, tables and arrays may require a Form E or L for a complete specification. This entry indicates that such a form has been prepared. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-14 Column Values Meaning ______ ______ _______ 39 Blank No additional form has been prepared. E An extension Specification (Form E) has been prepared for this file. Tables, arrays, and Record Address files require Form E specifications. L A Line Counter Specification (Form L) has been prepared for this print file. 5.16 DEVICE CODE By the nature of files, each one is associated with a device. This entry names that device. Columns Values Meaning _______ ______ _______ 40-46 DISK A disk device (DSK:) READ01 A card reader (CDR:) PRINTER A line-printer (LPT:) PRINTR A line-printer (LPT:) TAPE A mag-tape (TAPEn:, where n is unit number) CONSOLE A console device (TTY:) MFCU1 Simulated MFCU input hopper 1 MFCU2 Simulated MFCU input hopper 2 44 0-7 Unit number (for TAPE only) Names must be left-justified (start in column 40) in the field. 5.17 FILENAME Use this entry to define a filename to a file. Columns Values Meaning _______ ______ _______ 47-52 Blanks This file is not associated with a multiple file device. FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-15 Valid DEC-10 Filename This entry defines the six-character filename to be used for this file. Since file-structured devices contain more than one file, RPGLIB must have some way of choosing a particular file. Whenever a file is assigned to a file-structured device, either by entering "DISK" in columns 40-45, or via use of logical device names; an entry must be made in these columns. It is often convenient to define a filename in these columns for all files, even if they are never planned to be used with a file-structured device. If a case arises, such as debugging, where a file formerly assigned to a non-file-structured device must be changed, it makes the change a matter of assigning logical device names at the monitor level, rather than having to supply a new F card. 5.17.1 Default Extensions In addition to the six character filename, the DECsystem-10 also uses a three character extension to define a unique file. Because there is no room on the F card to supply this extension, it is defaulted as follows: Extension Type of File _________ ____ __ ____ MF1 MFCU input hopper 1 file MF2 MFCU input hopper 2 file ST1-ST4 MFCU output stackers 1-4 (These files are assigned automatically by RPG II as the simulated MFCU output files) IDX ISAM file index IDA ISAM file data portion RGA ADDROUT file RGD Any file not described above FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-16 5.18 CONTINUATION LINES Continuation lines provide further information on the file being defined. In particular they allow a file to be declared as an ASCII format file. 5.18.1 Column 53 Column Values Meaning ______ ______ _______ 53 Blank No continuation line follows this card K A continuation line follows this card To specify that this F card is followed by a continuation card, a K should be entered in column 53. 5.18.2 Continuation Lines Option These options are placed in the columns listed below, on the card immediatly following the one containing the K in column 53. Columns Value Meaning _______ _____ _______ 54-59 ASCII The file is defined as being in ASCII format 5.19 FILE ADDITION AND UNORDERED OUTPUT Column Values Meaning ______ ______ _______ 66 Blank a. Input file, or b. Non-indexed Output or Update file. A a. Pre-existing indexed file, and the current program will be adding new records by key, or b. Pre-existing disk or Magtape file, and the current program will be adding records to the end. Note that files with non-blank entries must be disk or magtape files. In particular, they must be indexed, sequential or direct. (Direct files are consecutive files with gaps for adding records.) Further, when adding records to a pre-existing Indexed file which is being processed sequentially by key, the key value of the added record must FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-17 fall between those for the last and next records processed from that file. When there is an "A" in column 66, RPGLIB will add new records to the ends of files. EXCEPTION: the CHAIN operation allows insertion of new records within Direct files. A program may add records to a file at detail, total, or exception time. Records to be added must be identified by an "ADD" entry in columns 16-18 of the corresponding Output/Format Specifications (FORM O). NOTE On the DECsystem-10, all indexed files must be created by the ISAM program. Once a file has been created via the ISAM program, it may be loaded via an RPG II program, however, RPG II is not capable of creating indexed files ex __ nihilo. ______ 5.20 TAPE REWIND This column specifies positioning for magnetic tape units. Column Value Meaning ______ _____ _______ 70 R Rewind tape at end of file U Unload tape at end of file N Leave tape at end of file Blank Leave tape at end of file CHAPTER 6 EXTENSION SPECIFICATION -- FORM E RPG II requires more information about Record Address files, Tables and Arrays than space on the File Specification Form permits. The Extension Specification gives the required extra information, and allows the complete description of Compilation time Tables and Arrays. Figure 6-1 shows the positions used for the four types of datasets described on Extension Specifications: 1. Compilation time Tables and Arrays, 2. Pre-execution time Table and Arrays, 3. Execution time Arrays, and, 4. Record Address files. Chapters 12 and 13 contain comprehensive discussions of Table and Array organization and usage, and of disk file operations involving Record Address files. 6.1 FROM FILENAME Pre-execution time Tables and Arrays and Record Address files require this entry. Columns Values Meaning _______ ______ _______ 11-18 Blanks Compilation or Execution time Table or Array. Filename Name of Record Address file, or name of Input file that contains pre-execution time Table or Array data. The name must be left-justified in the field, and must be the same as a filename in the File Description Specifications. EXTENSION SPECIFICATION -- FORM E Page 6-2 6.2 TO FILENAME For Record Address files, this entry specifies the data file to be used with the Record Address file. For Tables and Arrays, this entry specifies the name of an output file to receive the data file. An Execution time array may not be written out in this manner. Columns Values Meaning _______ ______ _______ 19-26 Blanks Execution time array, or Table or Array with no associated output file. Filename a. Record Address file: this entry names the data file associated with the Record Adress file. b. Compilation or Pre-execution time Table or Array: this entry names the file to receive the table or array after compilation or execution. The name should be left-justified in the field, and it must be the same as a filename in the Field Description Specifications. 6.3 NAME OF TABLE OR ARRAY Record Address files must have no more entries after column 26, except for comments. Columns Values Meaning _______ ______ _______ 27-32 Blanks Record Address file Name Name of a Table or Array All names must be valid RPG II names. Table names must start with "TAB"; array names must not. If the form describes an alternating (paired) Table or Array, this is the name of the first one -- the other appears further on. The name should be left-justified in the field. EXTENSION SPECIFICATION -- FORM E Page 6-3 NOTE RPG II processes table and array files in the order they appear in the Form E Specifications. In particular, when more than one Form E references the same file or device, RPG II expects the tables in the order of the Form E Specifications (for Input files) and writes them out in the order of the Form E Specifications (for Output files). 6.4 NUMBER OF ENTRIES PER RECORD This field pertains to Compilation and Pre-execution time Tables and Arrays. It indicates how many entries will be present in each physical record. EXAMPLE: In a card file, this entry shows the number of entries on each card. Columns Values Meaning _______ ______ _______ 33-35 Blanks Record Address file or Execution time Array 1-999 Compilation or Pre-execution time single Table or Array: entry indicates the number of arguments in each physical record, or Compilation or Pre-execution time paired (alternating) Table or Array: the entry indicates the number of pairs of arguments in each physical record. All records except the last must have the same number of arguments. The last record may have fewer. Entries must begin in the first position of the record, and no spaces may occur between entries in a single record. No entry may start in one record and finish in the next. EXTENSION SPECIFICATION -- FORM E Page 6-4 EXAMPLE: This is a table file on punched cards. Arguments have eleven characters, and there are seven entries per record. EXAMPLE: This is a file of related tables on punched cards. Arguments come in pairs -- a five-character item followed by a seven-character item. There are six pairs of entries per record, even though the card has unused columns that could contain another five-character item. Pairs must not be split across record boundaries. The table name of items 1A, 2A, etc. would appear in columns 27-32. The table name of items 1B, 2B, etc. would appear in columns 46-51. The number of entries per record field must be numeric and right justified. Leading zeroes may be omitted. These columns must be blank for execution time arrays. 6.5 NUMBER OF ENTRIES PER TABLE OR ARRAY This field specifies one of two things: 1. The exact number of entries or pairs of entries in the entire table or array, when full, or 2. the maximum number of entries a table or array may have if not full (termed a "short" table or array). EXTENSION SPECIFICATION -- FORM E Page 6-5 Columns Values Meaning _______ ______ _______ 36-39 Blanks Record Address file. 1-999 Table or Array: see above. The number of entries must be numeric and right-justified. Leading zeroes may be omitted. 6.6 LENGTH OF ENTRY Columns Values Meaning _______ ______ _______ 40-42 Blanks Record Address file. 1-256 Entry specifies the number of character positions of the table or array with the following maximum values: a. 256 if alphanumeric b. 15 if numeric For paired (alternate) Tables or Arrays, this entry refers to the length of entries in the first. The length entered in columns 40-42 must be right-justified. Leading zeroes may be omitted. Physical Aspects of Tables: In the file that contains tables and arrays, numeric items which are shorter than the length specified must be padded with leading zeroes or blanks. Short alphanumeric items must be padded with blanks on either end. 6.7 DATA FORMAT Column Value ______ _____ 43 Blank All Extension Specification cards must contain a blank in this column. DECsystem-10 RPG II supports only alphanumeric and unpacked decimal format. EXTENSION SPECIFICATION -- FORM E Page 6-6 6.8 DECIMAL POSITIONS Column Values Meaning ______ ______ _______ 44 Blank a. Record Address file, or b. Data will be alphanumeric. 0 Data will be decimal integers. 1-9 Data will be decimal numbers, with the indicated number of places after the decimal point. 6.9 SEQUENCE The order of a table or array (if any) determines how RPG II will perform LOKUP operations. Column Values Meaning ______ ______ _______ 45 Blank Record Address file, or entries are in arbitrary order A Entries are in ascending order D Entries are in descending order Consecutive equal entries are always considered to be in sequence. Column 45 refers only to the first of alternate (paired) Tables or Arrays. EXTENSION SPECIFICATION -- FORM E Page 6-7 6.10 ALTERNATE TABLE OR ARRAY When a specification describes paired or alternate Tables or Arrays, columns 46 through 57 describe the second one. The rules listed for the first one apply to the second. Note that the two names must both be unique. Corresponding field positions are the following: Field First Table or Array Second Table or Array _____ _____ _____ __ _____ ______ _____ __ _____ Name 27-32 46-51 Length of 40-42 52-54 entry Data format 43 55 Decimal 44 56 Positions Sequence 45 57 A table may not be paired with an array. 6.11 COMMENTS Columns Values _______ ______ 58-74 Any ASCII characters The comments field does not affect compilation or object program execution, but it is useful in program listings for later analysis, checkout and documentation. CHAPTER 7 LINE COUNTER SPECIFICATIONS -- FORM L The Line Counter Specifications form (Figure 7-1) is used for all printer output files with an L in column 39 of the corresponding File Description Specification (FORM F). Form L specifies form size and overflow line. When a printer file does not have a Form L, RPG II uses default values of 66 lines per page and an overflow line at 60. 7.1 FILENAME Columns Values Meaning _______ ______ _______ 7-14 filename Filename entered on the corresponding form F. The device assigned to the corresponding file must be a line printer. 7.2 NUMBER OF LINES PER PAGE Columns Values Meaning _______ ______ _______ 15-17 Blanks The user wishes the default -- 66 lines per page 1-112 The entry specifies the exact number of print lines available on a page (exact number of lines from one top of form to the next) The entry must be numeric and right-justified. Leading zeroes may be suppressed. LINE COUNTER SPECIFICATIONS -- FORM L Page 7-2 7.3 FORM LENGTH Columns Values _______ ______ 20-22 FL This field must contain the characters FL to indicate that the preceding field defines form length. 7.4 OVERFLOW LINE NUMBER Columns Values Meaning _______ ______ _______ 20-22 Blanks The user wishes the RPG II default of line 60. 1-112 Spaces, skips, or print operations that terminate on or before this line will set overflow conditions. See also paragraph 5.13. Different overflow lines can be specified for individual printer files. This may be necessary for varying numbers of lines printed in overflow conditions. Use of overflow indicators with other indicators may cause a variable number of lines to be printed on sucessive pages. The user should take care to leave enough room for the maximum, and yet retain good spacing on the page when few lines are printed. 7.5 OVERFLOW LINE Columns Value _______ _____ 23-24 OL This field must contain the letters OL to indicate that the preceding field defines an overflow line. CHAPTER 8 INPUT SPECIFICATIONS -- FORM I Form F describes all files except compile time tables and arrays. Form I, Input Specifications, describes the records of input and update files. Each file consists of one or more record types and each record type may consist of one or more fields. Form I has a section for records, and one for fields. Record descriptions go in the columns labeled Record Identification (columns 7-41, Figure 8-1). Descriptions of the fields within that record type go in columns 43-70, field description, of as many succeeding lines as required-- one line for each field. Then the next record type may be described, and so on, until all record types and fields have been described. 8.1 FILENAME This entry names the file that holds the record. The filename provides the link between information contained on Form F and Form I. Columns Values Meaning _______ ______ _______ 7-14 blanks a. Field descriptor b. File name is the same as that on the last record description. Filename from a Form F entry Named file. The name of every input or update file (except table input files and record address files) described in form F must be entered on this sheet. The filename must be the first line that contains information concerning the records in that file. If the filename is omitted, the last filename is assumed to be the file being described. All the records and fields for one file must be completely described before another file is described. INPUT SPECIFICATIONS -- FORM I Page 8-2 8.2 SEQUENCE This entry allows users to tell RPGLIB to check for a sequence of record types. Columns Values Meaning _______ ______ _______ 15-16 blanks a. Field description, or b. AND or OR line 01-99 RPGLIB will perform sequence checking AA-ZZ This record type not part of a sequence. Note that "ND" and "R " are not permitted as they would interfere with AND/OR lines. This field may contain an alphabetic or numeric code. The alphabetic code may be any two alphabetic characters (e.g., AA, BC, DQ) and signifies that this specific record type is not part of a predetermined sequence. The record may appear at any time in the file, so long as it does not interrupt some other sequence. Chained files require alphabetic sequence codes. A numeric code (01-99) specifies sequence checking. The codes must be in ascending order for each record type checked. This gives the correct order for records in the sequence. The first record type in a sequence must have 01 in columns 15-16. There may be only one sequence per file. Note that the leading zero must be entered in column 15. Records to be sequence-checked also must be specified on the form in the order in which they should occur when read from the file. When these columns contain a numeric entry, an entry must be made in column 17, and an entry in column 18 must be considered. Note that this type of sequence checking ensures only that record types appear in a given order in the file. A sequence specification on Form F causes sequence checking based on matching record specifications. In the Form I entries for a file, record types with alphabetic sequence specifications must come before those with numeric entries. AND and OR lines (description continuation lines) must not have entries in these columns. Presumably, the line preceding the AND or OR line specifies any required sequence checking. If sequence checking is specified and RPGLIB detects a sequence error, it enters a Halt Procedure. Halt Procedures are defined more fully in Appendix E. INPUT SPECIFICATIONS -- FORM I Page 8-3 8.3 NUMBER Users must make an entry here if columns 15-16 have a numeric entry. This column indicates whether more than one record of a type may be present before a different record type is encountered. Column Values Meaning ______ ______ _______ 17 blank Column 15-16 contain alphabetic characters or blanks. 1 Only one record of this type may appear in the sequence of each group. N Multiple records of this type may appear before a record type change of each group 8.4 OPTION Column Values Meaning ______ ______ _______ 18 blank a. No record type sequence checking is to be performed (columns 15-16 are alphabetic). b. Record type sequence checking is being done and this type must be present in each group (columns 15-16 numeric) except the last group which isn't checked. O Record type sequence checking is is being performed and this type may or may not be present in each group (columns 15-16 numeric). An entry should not be made in this column for lines which have an AND or OR relationship with a preceding line. The first line of an AND/OR relationship specifies the column 18 option. 8.5 RECORD IDENTIFYING INDICATOR AND LOOK-AHEAD FIELD Each different type of input or update record may have an identifier encoded in columns 19-20. INPUT SPECIFICATIONS -- FORM I Page 8-4 Columns Values Meaning _______ ______ _______ 19-20 blanks a. Field description, or b. No destinction need be given this and the preceding record type. 01-99 General record identifying indicator (RII) L1-L9 Control level indicator used as a record identifying indicator when record type rather than control field triggers a control break. H1-H9 Halt indicator to be set when RPGLIB encounters this type. LR Last record indicator -- simulates end-of-file condition. ** Look-ahead field When RPGLIB selects a record for processing and identifies it, it sets on the indicator specified by this entry. Users can specify this code to condition functions and operations in Calculations Specifications, Output-Format Specifications and additional Input Specifications. The entry in columns 19-20 may be unique for each input record type if desired, but sometimes it is useful to assign the same one to different record types. Example: a file with several record types, only the first of which is to be used in a given calculation. The others are handled by a common subroutine. Assignment of the same identifying indicator to all but the first type allows a single indicator to condition the subroutine for all the appropriate records. When RPGLIB turns on a record identifying indicator, it turns off any indicator which is on because of a previous record. Exception: when a record is retrieved by chaining from another record, the indicators for both records are on simultaneously and can condition further processing. When a control level indicator is set on by a record type, lower levels remain off. The record identifying indicator field must be blank for AND lines of an AND relationship. (See paragraph 8.7.) When a line has a pair of asterisks, fields defined on succeeding specifications lines are "look-ahead" fields. A look-ahead field can be examined in the next record of the file, while the current record is still being processed. For update files, look-ahead fields apply only to the current record. Look-ahead fields can not be specified for chained or demand files, or INPUT SPECIFICATIONS -- FORM I Page 8-5 as array fields. Neither can the fields be altered as a result of calculations or blank-after operations. Lines containing asterisks require alphabetic sequence code specifications. Columns 17, 18 and 21-74 must be blank, as well. Only one set of look-ahead fields can be described per file. The description applies to all records in the file, regardless of record type. If a field is to be available for processing before and after selection, the field must be described on two specifications lines-- as a look-ahead field and as a normal field. Look-ahead fields are useful for extending the matching record capability and for searching for the last record of a control group. 8.6 RECORD IDENTIFICATION CODES - COLUMNS 21-41 These entries tell RPGLIB how to distinguish among record types in a file. They allow up to three identifying codes per line as indicated by the 1, 2, and 3 on form I. For more than three codes, additional lines may be used as described in paragraph 8.7. These lines may be in an AND or OR relationship. Identification codes on a single line are considered in an AND relationship: code 1 AND code 2 AND code 3. If a file contains only one type of record, or if a distinction between record types is not important, columns 21-41 may be left blank. If RPGLIB encounters an input record which cannot be identified, it enters halt procedure "U1". For more data on Halt Procedures, see Appendix E. 8.6.1 Position Each record identification code is one character in size. The position (number of characters from beginning of record) of this character in the input record goes in 21-24, 28-31, or 35-38, right-justified. Columns Values Meaning _______ ______ _______ 21-24, 28-31 blanks No record identification code or 35-38 1-4096 Position in the record of the identification code. If the record identification code is not needed, this field is left blank. INPUT SPECIFICATIONS -- FORM I Page 8-6 8.6.2 Not Column Values Meaning ______ ______ _______ 25, 32, or 39 blank Code in the next two columns must be present. N Code must not be present. 8.6.3 C This entry tells RPGLIB which part of the character in column 27, 34, or 41 to use for comparison with the input record. This field is left blank if columns 21-25 are blank. Columns Values Meaning _______ ______ _______ 26, 33 or 40 blank No entry in 21-24, 38-31 or 35-38, respectively. C Full character comparison A C says the entire character specified in column 27, 34, or 41 is used for the comparison. 8.6.4 Record Identification Character Column Values ______ ______ 27, 34, or 41 Blank or any alphanumeric character RPGLIB will use a character entered here for comparison with the input record. 8.7 ADDITIONAL RECORD IDENTIFICATIONS Columns Values _______ ______ 14-16 AND or OR More than three record identification codes may be designated by entering the word AND in columns 14 through 16 of the next line and using columns 21-41 as described in paragraph 8.6. RPG II allows an OR relationship between record identification codes INPUT SPECIFICATIONS -- FORM I Page 8-7 for one record type or between record types for efficient field description when: One record type can be identified by different combinations of record identification codes. Example: all records having 'A', 'B', or 'C' in column 1 are to be considered as the same record type. Two or more record types have identical field descriptions but must be considered as different records. Two or more record types have very similar field descriptions, but a small number of fields may be in different positions or may occur in one record type but not the other. Grouping record types in OR relationships simplifies coding by allowing their common fields to be specified once only. Those few fields which are not common can then be linked to their corresponding record types by entering the record's identifying indicator in columns 63-64 of the field description line (see paragraph 8.14). OR in columns 14 and 15 specifies the OR relationship. A maximum of 20 AND and OR lines in any combination may be used to describe the record identification code. 8.8 FIELD TYPE Column 43 starts the field description. Column Values Meaning ______ ______ _______ 43 blank a. Record description, or b. Alphanumeric or unpacked decimal field 8.9 FIELD LOCATION Columns Values _______ ______ 44-51 Two 1-4 digit numbers Field location designates the starting and ending positions of a field within a record. The starting position goes in the From Field Location (columns 44-47); the ending position in the To Field Location (columns 48-51). A one-position field is designated by encoding the same position in both the From and To location fields; otherwise the From location must be smaller than the To location. INPUT SPECIFICATIONS -- FORM I Page 8-8 Entries must be right-justified; leading zeroes may be omitted. These entries indicate field position and size. The maximum size for numeric data is 15 digits; for alphanumeric data, 256 characters. Fields within a record may be defined in any order. Fields may overlap and the same positions may be given different field names. 8.10 DECIMAL POSITION Column Values Meaning ______ ______ _______ 52 blank Alphameric field 0-9 Numeric field - entry gives number of places to right of decimal The number entered cannot be larger than the effective field length designated in Field Location (columns 44-51). Only numeric fields may be edited or used in arithmetic calculations. 8.11 FIELD NAME References to input fields require a name; this entry supplies it. Columns Values _______ ______ 53-58 A valid RPG II field name, array name, array element, PAGE, PAGE1, or PAGE2 Unused portions of a record need not be named. Different fields in the same record should have different names; because of this, each field of a record is defined on a separate line. If a field is to be used as both an alphanumeric and numeric field, it must be defined twice by designating two different field names for the same position. Fields in different record types may have the same name if they have the same length and format. To avoid duplicate coding to describe the same field in two or more records, one can use an OR relationship (paragraph 8.7) to define the field name once for all the records in which it occurs. INPUT SPECIFICATIONS -- FORM I Page 8-9 8.11.1 Special Words -- PAGE, PAGE1, And PAGE2 A PAGE entry on the Output-Format Specifications form (Chapter 10) causes RPGLIB to write page numbers on a print file. An entry of PAGE, PAGE1, or PAGE2 as a field name specifies that the indicated portion of the record being defined contains a starting page number minus one. (When special words are not entered here, page numbering begins with 1.) Three special words exist so that three page number counters can operate in one object program. Because the counters have field names, they can enter into calculations like other field definitions. The format specified for a special word name must be numeric with zero decimal positions. Page numbering is restarted when the specified field of an input record contains a different value. 8.12 CONTROL LEVEL Columns Values _______ ______ 59-60 Blanks or L1-L9 These columns allow the specification of a control level indicator. Control level indicators are ranked from L9 (highest) to L1 (lowest), but may appear in any order on the Input Specification Form. The L0 indicator is always on, thus may not be used to indicate a control break. If RPGLIB encounters a field which has been assigned a control level, the contents of that field are compared with the contents of the same field from the previous record. If they are not equal, RPGLIB turns on the specified control level indicator and all lower control level indicators. For example, if the field in question has been assigned a control level of L4 and a control break occurs, indicators L4, L3, L2, and L1 are turned on. These indicators can control timing of calculations and output functions. If the user does not wish lower level calculations performed when their respective level indicators are turned on by a higher level control break, he may use the SETOF function on form C. Users can make several fields in an input record into one control field by giving them all the same control level indicator. This is called a split control field. All fields of a given control level must have the same format and must be specified in adjacent field description lines. The first field specified is considered the high order part of the control field; and the last is the low order part; any in between have the order in which they appear. RPGLIB ignores decimal positions in control fields. INPUT SPECIFICATIONS -- FORM I Page 8-10 Control level indicators can not be specified for chained or demand files. This entry is left blank if the field being described is not a control field. 8.13 MATCHING FIELDS Columns Values _______ ______ 61-62 Blanks or M1-M9 Entries in columns 61-62 indicate fields which are used for matching of records from different sequential files and for sequence checking of a single sequential file. Record matching is the technique for associating records from two or more sequential files. Consider posting stock issue transactions against an inventory balance file to update the balances. Assume that both files are sequenced on item stock number within warehouse location; warehouse location and stock number are used as matching fields. These fields are designated in columns 61-62 by encoding a matching record code (M1-M9) for the records to be matched from both files. The issue file is encoded as primary (P in column 16) on the File Description Specification Form F and the inventory balance file is encoded as a secondary file. As issue records are read in, the inventory balance file is advanced and the designated matching fields of the records are compared. When matching occurs, the matching records (MR) indicator is set on. This indicator subsequently may be used as a condition for the issue posting calculation. In record matching, the file sequences must be consistent -- all ascending or all descending, and so encoded in column 18 of form F. The order in which multiple matching fields are checked depends on the value (M1-M9) assigned. M9 designates a highest order field; M1 designates a lowest order field. If the program has a single sequential file, it may be sequence checked by entering M1-M9 codes to designate the sequence control field(s) in proper order. As in record matching, the higher order code must be assigned to the higher order control fields, etc. RPGLIB enters Halt Procedure "L1" if a file is found out of sequence. Sequence checking occurs automatically when fields are being matched. Table 8-1 gives rules for matching fields. Note that M1-M9 are not indicators, but cause the indicator MR to be set on when a match occurs. INPUT SPECIFICATIONS -- FORM I Page 8-11 Table 8-1 Rules for Matching Fields Number of A given record may have as many as nine matching field Codes codes. Length The lengths of fields to be matched (those having corresponding Mn codes) must be equal. The length of the combined matching fields of a record must be the same as for any record against which matching takes place. Format Fields to be matched must have the same format-- both numeric or both alphanumeric. An alphanumeric field may be treated as numeric for matching or sequence checking by defining it again with a different field name and designating it as numeric (by an entry in column 52). The Mn code then is used with the redefined field. Decimals and Decimal positions are ignored in matching numeric Leading fields. Also, a numeric field with leading zeroes Zeroes will match a field having the same value with suppressed leading zeroes. Sign Only the digit portions of numeric fields are matched. ignored Thus a negative number can match a positive number. AND Multiple matching fields are in an AND relationship. relationship Matches must occur in all matching fields specified for a record before RPGLIB sets on the MR indicator. Initial Alphanumeric matching fields are initialized to bla- value nks. Initial value for numerics is zero. Only Matching records may be specified only for input and Input or update files. Update 8.14 FIELD RECORD RELATION Columns Values _______ ______ 63-64 Blanks, 01-99, L1-L9, MR, U1-U8, or H1-H9. This field can be used as a means of minimizing the number of field definition entries to be written. It also provides a convenient means for selective control of processing. INPUT SPECIFICATIONS -- FORM I Page 8-12 The meanings of the allowable entries are the following: 01-99 Record identifying indicator assigned to a record type. L1-L9 Control level indicator previously used. MR Matching record indicator U1-U8 External indicator previously set H1-H9 Halt indicator previously used The following general rules apply to this entry: 1. All fields without a field record relation should be specified before fields with field record relations. 2. All fields with the same field record relation entry should be entered on consecutive lines. 3. All parts of a split control field must have the same field record relation entry and must be described on consecutive specification lines. A record identifying indicator (01-99) can be specified here for records in an OR relationship having fields occupying different positions in the records. In this case, the indicator specifies the record for which the field description applies. Control fields and matching fields can also be associated with a record having an OR relationship by a field record relation. Also, a field record relation may be specified for only one of a pair of control fields or matching fields. In this case, the specification having the relation is used when the indicator is on and the specification not having the relation is used when the indicator is off. A control level indicator (L1-L9) or matching record indicator (MR) can be specified as a field record relation when the defined field is to be used only when the control break or matching records occurs. An L1-L9 or MR entry cannot be specified here when the defined field is a control field or matching field. When U1-U8 has been encoded in columns 63-64, the normal processing for that field is carried out if the specified external indicator has been set on by a job control command. If the indicator is off, all input processing of the field in this record is bypassed. The external encoding must not be used for fields defined as matching or control level fields. A halt indicator (H1-H9) is specified here for records which have OR relationships and have the halt indicator specified in columns 19-20. INPUT SPECIFICATIONS -- FORM I Page 8-13 8.15 FIELD INDICATORS Columns Values _______ ______ 65-70 Blanks, 01-99, H1-H9 This field is used to specify that the contents of the field are to be examined when its record has been selected for processing. The data contained in the field can be tested for the following conditions: Plus Minus Zero or Blank As can be seen on the Input Specifications Form, there is a two position subfield representing each of these conditions. Allowable encoding for indicators in each of these subfields is 01-99 and H1 through H9. If the specified condition is not met, the designated indicator is turned off for the input record. If the condition specified is met, the designated indicator is turned on. The Plus and Minus conditions can be used only with numeric fields. All field indicators are off at the beginning of object program execution. CHAPTER 9 CALCULATION SPECIFICATIONS -- FORM C The Calculation Specifications tell RPG II which run-time operations to perform. General rules: Each operation must be specified on a single line of the coding form. Generally, operations must be in the order of execution. Detail calculations must come first, then all total calculations, then all subroutines. Form C (Figure 9-1) has three major sections: Entries in columns 7-17 control when the calculation is to be performed. Those in columns 18-53 describe the calculation. Those in columns 54-59 specify which indicators should be turned on or off as a result of the calculation. Columns 60-74, COMMENTS, have no significance to the compiler. RPG II prints any entries in the COMMENTS field on the source program listing to aid the user or other readers. CALCULATION SPECIFICATIONS -- FORM C Page 9-2 Figure 9-1 Form C CALCULATION SPECIFICATIONS -- FORM C Page 9-3 9.1 CONTROL LEVEL Columns Values Meaning _______ ______ _______ 7, 8 Blanks Calculation operation is performed at detail time L0 Calculation operation is performed at total time. (L0 is always on.) L1-L9 Calculation is performed when the corresponding or a higher level control break occurs, or when a SETON operation has set it on. LR Calculation operation is done after the last record has been processed, or after LR has been set on. SR Calculation operation is part of a subroutine. AN or OR Indicators listed on the current line are in an AND or OR relationship with indicators on the preceding line(s). Calculation form entries must be presented to the compiler in the above order, with the exception that AN/OR lines are specified with their associated lines. Paragraph 9.2 gives more information about AN and OR. RPGLIB performs calculations at either detail or total time. Blanks in columns 7-8 indicate performance at detail time. Control level indicators L0, L1 through L9 and LR designate calculations to be performed at total time. As is described in paragraph 8.12, control level indicators are set by control breaks. A break in control at any given level sets the indicator at that level and all lower levels. Exception: In the following cases, lower level indicators are not turned on: 1. Higher level indicator is set by a SETON operation. (See paragraph 9.4.5). 2. The higher level indicator is set on as a record identifying indicator. (See paragraph 8.5.) The last record indicator, LR, is set on after the last input record has been read and processed. Control level indicators L1 through L9 are also turned on when this occurs. When LR is set on by anything other than the last record, for example, by a SETON operation, L1 through L9 are not affected. CALCULATION SPECIFICATIONS -- FORM C Page 9-4 The L0 indicator is on throughout the exception phase and marks total calculations to be performed even if a control break has not occurred. An SR in columns 7 and 8 identifies the line as part of a subroutine. Specifications for subroutine operations may not show the control level(s) for those operations in columns 7-8 because these spaces are occupied by the code SR. Subroutines may be entered, however, from either a detail or a total calculation sequence. Individual operations within the subroutine may be conditioned by any indicators, including L0-L9, encoded in columns 9-17. 9.2 INDICATORS The entries in these columns (if any) specify the additional conditions which must be met after those in 7 and 8 are satisfied, if the conditioned operation is to be performed. These conditions are expressed in terms of indicators which must be on and/or off. RPGLIB sets (turns on) or clears (turns off) indicators according to input conditions or previous calculations. Up to three indicators may be specified (one each in columns 10-11, 13-14, and 16-17); if two or more are specified they are considered to be in an AND relationship. If the desired indicator state is off, an N should be encoded in the preceding column (9, 12, or 15). Columns Values Meaning _______ ______ _______ 10-11, 13-14 Blanks Columns 7-8 list the only conditioner. or 16-17 If columns 7-8 are blank, do the operation for every record read. 01-99 Do operation when this result or input indicator is set. L1-L9 Do operation when the named control level indicator is on. LR Do operation when the last record indicator is on. MR Do operation when matching records have been found. H1-H9 Do operation when the named halt indicator is on. U1-U8 Do operation when the named external indicator is on. OA-OG, OV Do operation when the named overflow indicator is on. CALCULATION SPECIFICATIONS -- FORM C Page 9-5 Through AN and OR entries in columns 7 and 8 more than three indicators can be used to condition one operation. 9.2.1 AN/OR Lines A maximum of seven AN/OR lines may condition a single operation, and up to three indicators may be specified on each AN/OR line. The last line of an AN/OR group lists the operation and operands to be used when the conditions are met. The others should not specify operations, operands, or resulting indicators. AN/OR lines give flexibility for conditioning. If more than three indicators must be on or off for a particular operation, AN lines allow up to eighteen more indicators. OR lines allow alternate conditions. When there are combinations of AN and OR lines, AN has the higher binding power. Example: 01N03 09 AN 02 04 07 OR 99 98N 97 OR 96N95 LR AN 93N92 ----------OPERATION-------------- OPERATION will be performed if conditions listed on the first two lines, or those on the third, or those on the last two are met. In particular if 01 is set, 03 is not set, and 09, 02, 04 and 07 are set, or 99 and 98 are set, and 97 is not set, or 96 is set, 95 is not set, LR and 93 are set, and 92 is not set. Users may enter halt indicators to prevent a calculation from being performed with erroneous data. Points to remember when filling in columns 7-8 and 9-17: 1. When columns 7-8 contain a control level indicator and columns 9-17 specify MR, the matching record description applies to the last record processed -- not the record causing the control break. MR will not be set for the current record until all the total calculations specified for the appropriate control break in 7-8 have been performed. 2. A control level entry in columns 7-8 indicates a total calculation. A control level entry in columns 9-17 specifies a detail operation to be performed after the control break. The organization of the RPG II program cycle causes RPGLIB to perform total operations for a control break before the detail operations for the record causing the control break. CALCULATION SPECIFICATIONS -- FORM C Page 9-6 Figure 9-2 Conditioning Calculations CALCULATION SPECIFICATIONS -- FORM C Page 9-7 Figure 9-2 shows examples. Explanation: Line 010 - The detail calculation is performed only if indicator 01 is on. Line 030 - The detail calculation is performed only if control break indicator L2 is on. Line 040 - The total calculation is performed when the L4 control break indicator is on and MR has not been set by the previously processed record. 9.3 FACTOR 1 AND FACTOR 2 Many RPG II Calculation operations require the specification of factors. Entries may be needed for Factor 1, Factor 2, both, or neither, depending on the particular operation. The following paragraphs discuss requirements for each operation. Appendix A is a summary of Calculation Specification Entries. Columns Values _______ ______ 18-27, 33-42 Factor 1 and Factor 2 may contain the following entries: Field name Alphanumeric or numeric literal Array element, or name of subroutine, table or array Date field name (UDATE, UMONTH, UDAY, UYEAR) Special name (PAGE, PAGE1, PAGE2) Label for a TAG, BEGSR, or ENDSR operation (Factor 1) or a label for a GOTO or EXSR operation (Factor 2) Filename (first six characters) for a CHAIN, DEBUG, DSPLY, READ, or FORCE operation (Factor 2) Entries are left-justified in the two fields. The rules for each entry type: CALCULATION SPECIFICATIONS -- FORM C Page 9-8 9.3.1 Field Names All field names must be defined if they are to be used in writing a Calculation Specifications line. A field name is defined by an entry in columns 53-58 of an Input Specifications form or by an entry in columns 43-48 (result field) of a Calculation Specifications line. A field name not defined as input may be used as a Factor 1 or Factor 2 entry only if it is defined (1) as a result field on the same Calculation Specifications line where it is first used as a factor or, (2) as a result field on an earlier line. A compiler error results if a field name is entered which is undefined or defined in a later Calculation line. 9.3.2 Literals Literals are self defining data and may be numeric or alphanumeric. Examples: 123.4 (numeric) or 'ABC', '123.4' (alphanumeric) 9.3.2.1 Numeric - A combination of digits (0-9), one decimal point, and one arithmetic sign. Rules: 1. Numeric literals must 1. not exceed ten positions, 2. not contain embedded blanks, 3. be left-justified 4. have the sign, if encoded, in the leftmost column 18 or 33); an unsigned literal is assumed to be positive 5. not be enclosed in apostrophes. 2. The decimal point, if encoded, may appear anywhere in the literal. If it is not encoded, it is assumed to follow the rightmost digit. CALCULATION SPECIFICATIONS -- FORM C Page 9-9 9.3.2.2 Alphanumeric - An alphanumeric literal is a combination of characters enclosed in apostrophes. Rules: 1. It must not exceed eight position, plus two apostrophes. 2. It may contain any alphanumeric character including blanks. 3. It must be left-justified. An apostrophe within a literal must be encoded by entering two consecutive apostrophes. Example: ________ The word USER'S is encoded as a literal 'USER''S'. 123 is a numeric literal; '123' is an alphanumeric literal. 9.3.3 Names And Elements Table and array names were described briefly in Chapter 6. These names and array element names are discussed in greater detail in Chapter 12. Rule for Labels and Subroutine Names: 1. must be left-justified 2. must start with an alphabetic character 3. must not exceed six characters 4. must not be the same as any field name 5. must not include special characters or embedded blanks 9.3.4 Date Field Names The date field names--UDATE, UMONTH, UDAY, and UYEAR--refer to the current date that RPGLIB supplies to the object program. These values cannot be changed by calculations specifications, so they may not appear in columns 43-48. They may appear as factors to, for example, produce the next month's billing date. CALCULATION SPECIFICATIONS -- FORM C Page 9-10 9.3.5 Special Names The special names--PAGE, PAGE1, and PAGE2--are described in paragraph 10.8.2. These names are used for the three page number counters available to RPGLIB. The programmer may increment these counters explicitly in the calculations specifications, or implicitly in output specifications. 9.3.6 Labels Paragraph 9.3.3 gives rules for establishing Factor 1 labels (used with TAG, BEGSR, and ENDSR operations) and Factor 2 labels (used with GOTO and EXSR operations). 9.3.7 Filenames Any valid RPG II filename can be used as Factor 2 for CHAIN, DEBUG, DSPLY, READ, and FORCE operations, subject to the specific requirements of each operation. 9.4 OPERATION -- COLUMNS 28-32 This field specifies the operation to be performed using Factor 1, Factor 2 and the Result Field, as appropriate. Allowable operations are summarized in Table 9-1. Operation codes must be left-justified. Detailed rules for each code are given in subsequent paragraphs. CALCULATION SPECIFICATIONS -- FORM C Page 9-11 TABLE 9-1 Operations for Calculation Specifications Class Code Operation _____ ____ _________ Arithmetic ADD Add Z-ADD Zero and Add SUB Subtract Z-SUB Zero and Subtract MULT Multiply DIV Divide MVR Move Remainder SQRT Square Root XFOOT Crossfoot - Sum Elements of an Array Move MOVE Move MOVEL Move Left MOVEA Move Array Move Zone MHHZO Move High to High Zone MHLZO Move High to Low Zone MLLZO Move Low to Low Zone MLHZO Move Low to High Zone Compare, Bit, and Test COMP Compare BITON Set Bit On BITOF Set Bit Off TESTB Test Bit TESTZ Test Zone Branch and Tags GOTO Go To TAG Provide a Branching Label EXSR Execute an RPG II Subroutine BEGSR Begin an RPG II Subroutine ENDSR End an RPG II Subroutine EXIT Enter a non-RPG II Subroutine RLABL Pass Parameters to a non-RPG II Subroutine Indicator SETON Set Indicator On SETOF Set Indicator Off Table LOKUP Table or Array Lookup Input/Output EXCPT Force Output Printing FORCE Force Record to be Read DSPLY Print and/or Accept Data at the Console Device READ Read from Demand File CHAIN Retreive Defined Record Debugging DEBUG Aid in Finding Programming Errors Miscellaneous TIME Retreive Time of Day from RPGLIB CALCULATION SPECIFICATIONS -- FORM C Page 9-12 9.4.1 Arithmetic Operations The fields and literals used in arithmetic operations must be numeric. None of the fields specified as Factor 1, Factor 2, or the Result Field can exceed 15 digits. RPGLIB aligns decimal points before all arithmetic operations. The arithmetic operation codes and their corresponding fields are listed below: Factor 1 Operation Factor 2 Result Field ______ _ _________ ______ _ ______ _____ required ADD blanks Z-ADD required SUB blanks Z-SUB required required required MULT required DIV MVR blanks blanks SQRT required XFOOT required Up to three distinct names may be in a single statement. Factor 1 and 2 fields are not altered by the operations unless one or both of the names are the same as the Result Field Name. The previous contents of a Result Field are lost after an arithmetic operation. Table 9-2 describes Arithmetic Operations. 9.4.2 Move Operations When using the MOVE, MOVEL or MOVEA operations the form of the data may be changed from alphanumeric to numeric and vice versa. When an alphanumeric field is moved to a numeric field, blanks are converted to zeroes. Move operations do not align decimal positions. Factor 1 and the resulting indicators columns must be blank for move operations. Table 9-3 describes Move Operations. 9.4.3 Move Zone Operations These operations are used to move the zone portion of a character. There are four varieties of the move zone operation. Note: Generally, whenever the word high is used, the field involved must be alphanumeric; whenever low is used, the field involved may be either alphanumeric or numeric. CALCULATION SPECIFICATIONS -- FORM C Page 9-13 9.4.3.1 MHHZO - This operation moves the zone from the leftmost position of Factor 2 to the leftmost position of the Result Field. Factor 2 and the Result Field must be alphanumeric. 9.4.3.2 MHLZO - This operation moves the zone from the leftmost position of Factor 1 to the rightmost position of the Result Field. Factor 2 can only be alphanumeric. The Result Field can be either numeric or alphanumeric. 9.4.3.3 MLLZO - This operation moves the zone from the rightmost position of Factor 2 to the rightmost position of the result field. Factor 2 and the Result Field may be either alphanumeric or numeric. 9.4.3.4 MLHZO - This operation moves the zone from the rightmost position of Factor 2 to the leftmost position of the Result Field. Factor 2 can be either numeric or alphanumeric, but the Result Field can only be alphanumeric. 9.4.4 Compare, Bit And Test Operations 9.4.4.1 COMP - The operation COMP compares the literal or the contents of the field in Factor 1 against the literal or contents of the field in Factor 2. The Factor 1 and Factor 2 fields must have identical formats--both numeric or both alphanumeric. An entire array cannot be specified as either Factor. The Result Field must be left blank. At least one resulting indicator (columns 54-59) must be specified. Depending upon the results of the comparison, the appropriate indicators are turned on: High Factor 1 is greater than Factor 2. Low Factor 1 is less than Factor 2. Equal Factor 1 equals Factor 2. Table 9-4 gives rules for comparisons. CALCULATION SPECIFICATIONS -- FORM C Page 9-14 TABLE 9-2 Arithmetic Operations Operation Description _________ ___________ ADD Factor 2 is added to Factor 1 and the sum is placed in the Result Field. Z-ADD Factor 2 is placed in the Result Field. SUB Factor 2 is subtracted from Factor 1 and the difference is placed in the Result Field. When Factor 1 and Factor 2 have the same name, the Result Field is zeroed. Z-SUB Factor 2 is placed in the Result Field with its sign reversed. MULT Factor 1 is multiplied by Factor 2 and the product is placed in the Result Field. DIV Factor 1 is divided by Factor 2 and the quotient is placed in the Result Field. Factor 2 can not be zero. The remainder of a divide is lost, unless an MVR operation follows on the next Calculation Specifications line; when a move remainder operation is specified, half-adjusting can not be requested for the divide, and the MVR must be the next line. MVR The remainder from the immediately preceding divide operation is moved to the Result Field. Since the DIV and MVR operations go together they should be conditioned by the same indicators, if any. The number of significant decimal positions in the remainder is the greater of: 1. The number of decimal positions specified for the Factor 1 field of the divide 2. The sum of the number of decimal positions specified for the Factor 2 and Result fields of the preceding divide operation. SQRT The square root of Factor 2 is calculated, half-adjusted and placed in the Result Field. Factor 2 can not be a negative number. The number of significant whole number and decimal positions in the Result Field is one-half that of Factor 2, half-adjusted to the next highest whole number. CALCULATION SPECIFICATIONS -- FORM C Page 9-15 TABLE 9-2 (cont'd) Arithmetic Operations Operation Description _________ ___________ XFOOT The sum of all the elements of the Factor 2 array is placed in the single element Result Field. Half-adjusting can be specified for the Result Field If the Result Field is an element of the Factor 2 array, the original value of the element is used in the addition, and then replaced by the sum. CALCULATION SPECIFICATIONS -- FORM C Page 9-16 Table 9-3 Move Operations Operation Description _________ ___________ MOVE Causes characters, starting at the rightmost character, to be moved from the data field or literal specified in Factor 2 to the rightmost positions of the Result Field. The contents of the data specified by Factor 2 remain unchanged in all cases. If the Result Field length is shorter than the length of the Factor 2 data field, RPGLIB moves only enough to fill the Result Field. If the Result Field is longer than the Factor 2 data field, RPGLIB moves all available characters, and leaves excess characters of the Result Field unaffected. A numeric Result Field assumes the sign associated with Factor 2. MOVEL This operation is similar to the MOVE, except that characters are moved from the leftmost position of the Factor 2 data field to the leftmost characters position of the Result Field. If a numeric Result Field is the same length as Factor 2, it assumes the sign associated with Factor 2. If a numeric Result Field is longer than Factor 2, it retains its sign, but a spurious sign will appear over the rightmost result character contributed by Factor 2. A numeric Result Field shorter than Factor 2 will have no sign. MOVEA Moves the data starting at the leftmost position of Factor 2 to the leftmost position of the Result Field. The shorter field (Factor 2 or the Result Field) determines the length of the move. If Factor 2 is longer than the Result Field, the excess rightmost characters of Factor 2 will not be moved. If the Result Field is longer than Factor 2, the characters to the right of the data moved into the Result Field will remain unchanged. All arrays an field referenced by a MOVEA instruction must be alphanumeric. The MOVEA operation makes it possible to move such things as: 1. Several contiguous array elements to a single field. 2. A single field to several contiguous array elements. CALCULATION SPECIFICATIONS -- FORM C Page 9-17 Table 9-3 (cont'd) Move Operations Operation Description _________ ___________ XFOOT (cont'd) 3. Contiguous elements of one array to contiguous elements of another array. The movement of data starts with the first element of an array or field. If the array is indexed, the move starts with the element referenced. The movement of data is terminated when the last array element has been moved or filled, or when the number of characters moved equals the length of the shorter field specified in Factor 2 or the Result Field. This may cause the move to be terminated in the middle of an array element. Note: Both Factor 2 and the Result Field cannot reference the same array. Table 9-4 Rules for Comparisons TYPE TOPIC RULE ____ _____ ____ Numeric Length Maximum length is 15 digits. Alignment RPGLIB aligns decimal points before comparison. Padding When necessary, RPGLIB pads with zeroes until lengths are equal. Comparison The comparison is algebraic. Alphanumeric Length Maximum length is 256 characters. Alignment RPGLIB aligns the left-most characters before the comparison. Padding RPGLIB pads with blanks on the right when lengths are unequal. Comparison Characters are compared according to the normal collating sequence. CALCULATION SPECIFICATIONS -- FORM C Page 9-18 9.4.4.2 BITON, BITOF, TESTB - The bit operations allow users to set (BITON), clear (BITOF), and test (TESTB) bits which can be used for conditioning operations. The Result Field specification must be a 1-character alphanumeric field or element in a table or array. The Factor 2 specification can have two formats: 1. Bit numbers (0-5) can be specified. The numbers specify which bits are to be set on, set off, or tested. Up to 6 bits can be specified in any order. Bits are numbered 0-5 from left to right in the 1-character Result Field. Bits specified in Factor 2 are enclosed in apostrophes. When Factor 2 has the value '0', the leftmost bit of the Result Field is to be set or tested. An entry of '5342' causes bits 2-5 (the rightmost four bits) to be set or tested. 2. Factor 2 can also be a 1-character field or element in a table or array. In this case, the contents of the Factor 2 specification (that is, those bits which are equal to one--set) indicates the bits to be set or tested. No matter which format is used for Factor 2, unspecified bit positions cause the corresponding Result Field bits to be ignored. Bit operations can be conditioned by entries in columns 7-17. If field length is specified, the value must be 1. Factor 1, Decimal Positions, and Half-Adjust must be blank for bit operations. Resulting Indicators (columns 54-59) are blank for BITON and BITOF, but must have at least one entry for TESTB operations. The BITON operation causes bits specified in Factor 2 to be set equal to one in the corresponding Result Field bit positions. That is, RPGLIB places the inclusive OR of Factor 2 and the Result Field into the Result Field. The BITOF operation causes bits specified in Factor 2 to be cleared to zero in the corresponding Result Field bit positions. (RPGLIB ANDs the Result Field with the complement of Factor 2.) Bits specified in Factor 2 of a TESTB operation cause corresponding bit positions in the Result Field specification to be tested for an on or off condition and resulting indicators to be set accordingly. (RPGLIB ANDs the Result Field with Factor 2.) At least one indicator must be specified in the Resulting Indicators field. A user may specify up to three, but a single indicator may not be specified in more than two positions. If Factor 2 is a field which is all zeroes, no indicators are set by a TESTB operation. Otherwise, RPGLIB sets resulting indicators according to the following conditions: 1. An indicator in columns 54-55 is set if each Result Field bit specified by the Factor 2 entry is off (0). CALCULATION SPECIFICATIONS -- FORM C Page 9-19 2. An indicator in columns 56-57 is set if the Result Field bits specified by the Factor 2 entry are in a mixed condition (some on, some off). If the Factor 2 entry causes only one bit to be tested, an indicator specified here will not be set. 3. An indicator in columns 58-59 is set if each Result Field bit specified by the Factor 2 entry is one (1). 9.4.4.3 TESTZ - This operation tests the zone of the leftmost character in the result field (see Appendix D for information on character structure). The Result Field must be alphanumeric since this operation can only be done on alphanumeric characters. Resulting indicators are used to determine the results of the test. The zone portion of characters & and A-I causes the plus indicator to turn on. The zone portion of the characters } (right curly-bracket), - (minus), and J-R causes the minus indicator to turn on. All other characters, when tested, cause the blank indicator to turn on. Factor 1 and Factor 2 are not used in this operation. 9.4.5 Branch And Exit RPGLIB usually does calculations in the order in which they are entered on specifications lines. Operations listed in this section, however, can alter this sequence for the following sample reasons: 1. Some operations should be skipped as a result of certain conditions. 2. Operations defined on preceding specifications forms should be repeated as a result of certain conditions. 3. A sequence of operations is to be performed over and over again. It is also desireable, at times, to be able to access subroutines not written in RPG II, in order to do system-dependent functions not possible in RPG II. For this reason subroutine linkages to accomplish this are provided. Branch and exit operations: GOTO (Branch) TAG (Provide a name for a branch) EXSR (Transfer to an RPG II subroutine) BEGSR (Begin an RPG II subroutine) ENDSR (End an RPG II subroutine) EXIT (Transfer to a non-RPG II subroutine) RLABL (Pass a parameter to a non-RPG II subroutine) CALCULATION SPECIFICATIONS -- FORM C Page 9-20 Branch and exit operations and their corresponding fields are listed below: 9.4.5.1 GOTO - If the conditions specified in columns 7-17 are met, control is transferred to the point in the program specified by the name in Factor 2. (See TAG, next paragraph.) Both forward and backward referencing is allowed. WARNING: (1) Control may not be transferred to a TAG within a subroutine from outside that subroutine. Transfer may not be made from a calculation not conditioned by indicators in columns 7-8 to one that is; or vice versa. When conditions are not specified for the GOTO operation, the transfer always occurs. Factor 1 and Result Field must be blank for a GOTO operation. 9.4.5.2 TAG - The TAG operation defines names to which a GOTO operation may transfer control. The name goes in Factor 1 and may be 1 to 6 characters long. The first character must be alphabetic and be placed in column 18. No special characters or embedded blanks may be used. Columns 9-17 must be blank for a TAG operation code, but a control level indicator can be specified in columns 7-8 to signal that the branch is to occur at total time. 9.4.5.3 EXSR - The EXSR operation causes a transfer of control to an internal subroutine written in RPG II as a part of the same program. After the subroutine has been performed, control returns to the next specification following the EXSR operation. The name of the subroutine is left-justified in Factor 2. EXSR operations may be conditioned by entries in columns 7-17. Nesting (an EXSR for a second subroutine in an RPG II subroutine) may occur, but a subroutine may not call itself, nor any subroutine that called itself and so on. CALCULATION SPECIFICATIONS -- FORM C Page 9-21 9.4.5.4 BEGSR - The BEGSR operation defines the entry point of an RPG II subroutine. The left-justified name of the subroutine goes in Factor 1. Columns 7-8 must contain SR; all other columns except COMMENTS (columns 60-74) must be blank. 9.4.5.5 ENDSR - An ENDSR operation is the last statement of an RPG II subroutine. The Factor 1 field may contain a name which is referenced by GOTO operations within the subroutine. Columns 7-8 must contain SR. 9.4.5.6 EXIT - The EXIT operation generates a call to an external subroutine, using linkages compatible with such standard DECsystem-10 language processors as MACRO, FORTRAN, and COBOL. See Appendix G for more information on this calling sequence. Factor 2 must contain the name of the external subroutine. Factor 2 must therefore contain a legal RAD50 symbol, compatible with LINK-10. (A legal RAD50 name may contain the characters A-Z, 0-9, ".", "$", "%", or " ".) 9.4.5.7 RLABL - The RLABL operation allows the passing of a field, table or array, as a parameter to an external non-RPG II subroutine. The parameter passing procedure is compatible with most other DECsystem-10 language processors (see Appendix G for more information). 9.4.6 Indicator Operations RPG II provides two indicator operations. Both may be conditioned by entries in columns 7-17. 9.4.6.1 SETON (Set Indicators On) - This operation turns on the indicators specified in columns 54-55, 56-57, 58-59. Any indicators may be referenced except 1P, MR, L0, and U1-U8. When LR is set on by an operation conditioned by a control level indicator (columns 7-8). processing stops after all total output operations are completed. If the SETON is not conditioned by a control level indicator, processing stops after the next total output sequence is completed. If one or more halt indicators (H1-H9) is SETON and not turned off before detail operations are completed, processing stops at that time. Setting a control level indicator (L1-L9) on does not set lower CALCULATION SPECIFICATIONS -- FORM C Page 9-22 control level indicators on. A control level indicator which has been SETON is automatically turned off at the completion of the detail output operation cycle. Record identifying indicators (01-99) are conditioned by a new record, regardless of previous SETON and SETOF operations. That is, SETON or SETOF only lasts until the next input record is identified. 9.4.6.2 SETOF (Set Indicators Off) - This operation is identical to SETON, except specified indicators are turned off rather than on, and LR cannot be set off. 9.4.7 Table Operation RPG II provides a table lookup operation, encoded LOKUP. Factor 1 specifies the search argument and Factor 2 specifies the name of the internally stored argument table or array to be searched. RPGLIB begins all table searches with the first element and stops searching when conditions have been satisfied. At least one indicator must be designated in columns 54-59 to specify the type of search. The search argument (Factor 1) may be: 1. An alphanumeric or numeric constant. 2. A field name. 3. A table name. 4. An array element. As described below, when a table is named as Factor 1, the table element last selected by LOKUP operation is the search argument. Factor 1 and Factor 2 must have equal lengths and data type (i.e., both numeric or both alphanumeric), and decimal points of the two items are ignored. The type of search is specified by entries in the resulting indicators field (54-59). Before the search, all indicators are turned off. The specified indicators are turned on when the conditions are met. Conditions possible are: HIGH (columns 54-55) -- RPGLIB turns on the indicator specified in 54-55 and stops searching when it finds the smallest entry which is greater than Factor 1 (search argument). LOW (columns 56-57) -- Same as HIGH, except RPGLIB searches for the largest entry which is less than Factor 1 (search argument). EQUAL (columns 58-59) -- Same as HIGH, except RPGLIB searches for CALCULATION SPECIFICATIONS -- FORM C Page 9-23 the first entry equal to Factor 1 (search argument). Combinations of HIGH and EQUAL may be specified with EQUAL given precedence. Thus, if there is an entry which is equal, RPGLIB will find it. HIGH and LOW may not be specified simultaneously. Comparisons made during a search are algebraic for numeric quantities. Alphanumeric quantities are compared by the ASCII collating sequence. Tables and arrays to be searched by a LOKUP operation must have an entry in column 45 (sequence specification) of Form E unless the search is for an equal condition only (entry in columns 58-59 and none in columns 54-55 and 56-57). LOKUP operations can be conditioned by entries in columns 7-17. 9.4.7.1 LOKUP With One Table - If a single-table search is successful, RPGLIB retrieves the table value and stores it in a holding area. Previous contents of the holding area (i.e., the result of a prior LOKUP) are destroyed. If the search is unsuccessful, RPGLIB does not change the holding area. References to a table name in later operations (other than another LOKUP) actually refer to the item currently in the holding area. Thus, the later operations should be conditioned by indicators set by a successful search. When a table name is used as a search argument (Factor 1) of a LOKUP, RPGLIB uses the current value in the holding area in the search. When a table name which has been Factor 2 in a successful search is named as the result field of a calculation operation, the holding area and the last element retrieved receive the result of the operation. This allows object programs to change table items. 9.4.7.2 LOKUP With Two Tables - Chapter 12 describes related tables. Related tables can be specified as Factor 2 and Result Field in a LOKUP operation. Factor 2 names the first table to be searched. When a search is successful, two items are moved to the holding area: the Factor 2 item resulting from the successful search and the corresponding item from the related table. Both holding area values remain available according to the rules specified above. When the number of elements does not match, the shorter number of elements determines the number to be searched. Thus, the last elements in the longer table are ignored. 9.4.7.3 LOKUP With Arrays - When a LOKUP operation is performed with an array named as Factor 2, the result field must be blank. Searching an array is similar to searching a table except that RPGLIB does not move an item to a holding area when a search is successful. RPGLIB does set appropriate indicators after a successful array search. CALCULATION SPECIFICATIONS -- FORM C Page 9-24 When Factor 2 is an unindexed array, RPGLIB begins the search at the first element of the array. When Factor 2 is an array name and index, the search begins with the element indicated by the index. The Factor 2 format in this case is [array name],[index] where the index can be a field name or a numeric literal. If the index is a field name, a successful search causes RPGLIB to place the appropriate element number in the field used as the index. The array element can then be referenced like a found table item in calculation and output, using the array and index names. RPG II places a 1 in the index field if the search was unsuccessful. This resets the index for a subsequent search. When the index is a literal, only the indicators tell if the search conditions are satisfied. That is, RPGLIB does not change the value of the literal or identify the array element satisfying a search. Figure 9-3 illustrates LOKUP operations on tables and arrays. At lines 010-030, TABLE1 is searched for an argument stored at ACTNO. If RPGLIB finds a match it adds the matching element to a value stored at TOTAL and stores the sum at TOTAL. When the HIGH indicator is set by the search, that indicator conditions a branch to a TAG called ERROR. Calculations at lines 080 and 090 are conditioned by the Equal indicator of the LOKUP operation at 010. If the LOKUP at line 080 is performed, RPGLIB searches TABA for an element which equals the element retrieved at line 010. If this search is successful, RPGLIB sets indicator 01 and squares the associated element in TABB. At line 130, RPGLIB searches ARRAY for an element equal to a value stored at ARG. If a match is not found, control is transferred to a TAG named FILL. At lines 170 and 180, RPGLIB searches array ARRAY for the first element having a value less than 0556. The field INDX initially contains the number of the array element at which the search should begin. If the search is unsuccessful, RPGLIB sets INDX to value 1. When the search is successful, INDX contains the number of the element that satisfied the search. The next line causes RPGLIB to move the element satisfying the condition to a field named HOLD. CALCULATION SPECIFICATIONS -- FORM C Page 9-25 Figure 9-3 LOKUP with Tables CALCULATION SPECIFICATIONS -- FORM C Page 9-26 Figure 9-4 LOKUP with Arrays CALCULATION SPECIFICATIONS -- FORM C Page 9-27 9.4.8 Input/Output Operations In the RPG II program logic outlined in Appendix C, RPGLIB reads records, performs calculations, and outputs records. Deviation from this pattern is possible via five operation codes which allow input or output at calculations time: 1. EXCPT (exception) 2. FORCE (force) 3. DSPLY (display) 4. READ (read) 5. CHAIN (chain) 9.4.8.1 EXCPT - The EXCPT operation allows records to be written at calculations time. Use this primarily when you like to have a number of similar or identical records to be written in one program cycle. When the EXCPT operation is used, except columns 28-32 and only columns 7-17 may have entries. The line or lines which are to be written out are indicated by an E in column 15 of the output sheet. 9.4.8.2 FORCE - The FORCE operation overrides normal record selection, and allows the user to select the file that will supply input for the next cycle. The forced file can be a primary or secondary input or update file. Factor 2 names the file from which a record is to be forced. The FORCE can be conditioned by columns 7-17, but all other columns except COMMENTS on the line must be blank. If a FORCE operation is executed, the next program cycle will process the next available record from the FORCEd file. If several FORCE operations occur in one calculations cycle, RPGLIB executes the last one only. The effect of a FORCE lasts only one cycle. In multi-file processing, RPGLIB selects the first record to be processed in the normal fashion, but thereafter records can be forced in an abnormal manner. At end of file on a forced file, normal record selection resumes. See also 1.1.2, 5.3 and 13.1.1 CALCULATION SPECIFICATIONS -- FORM C Page 9-28 9.4.8.3 DSPLY - Through a DSPLY operation, either or both of the following can occur: 1. Up to 125 characters are printed from storage onto the console device without a halt in program execution. Programs may display characters from a literal, a field, or a table or array element named as Factor 1. 2. Up to 125 characters of a field or table or array element named as the Result Field are printed on the console device. The program then halts, allowing the contents of the field or element to be altered from the console. A display file is described completely on Form F; it needs no record descriptions. The filename goes in Factor 2 on the DSPLY operation line. The operation can be conditioned by entries in columns 7-17. The rules for entering data during program execution: 1. A literal cannot be altered (i.e., cannot be entered in the Result Field). 2. Numeric data need not be entered with leading zeroes; the data is right-justified in the result field or element. 3. Alphameric data is left-justified in the receiving field or element. 4. Typing a single space causes a numeric field or element to be cleared to zeroes and an alphanumeric field or element to be set to blanks. 5. A field or element is not changed if characters are not entered. 9.4.8.4 READ - The READ operation causes RPGLIB to read and process a record from a demand file during the calculations cycle. Unlike a record read by a FORCE operation, RPGLIB reads it immediately, not at the start of the next program cycle. Demand files are processed sequentially. The demand file is described on Forms F and I, and the filename is entered as Factor 2 for the READ operation. The READ can be conditioned by entries in columns 7-17. All other columns should be blank except 58 and 59, in which an indicator may be specified, and COMMENTS. RPGLIB turns on the indicator when it reaches end-of-file in the demand file. When columns 58-59 are blank, program execution halts at end-of-file. A demand file's record identifying indicator remains on throughout the program cycle after a record has been READ from the file. CALCULATION SPECIFICATIONS -- FORM C Page 9-29 A demand file must have a D in column 16 on Form F and must be input or update. Demand file records can be accessed only through READ operations. Control levels, matching records, and look-ahead fields can not be specified for demand files, nor can numeric sequence checking be requested. When a demand file is conditioned by an external indicator (U1-U8) which is not on, no records are read from the file and the end-of-file indicator (columns 58-59) is not set on. 9.4.8.5 CHAIN - The CHAIN operation is used for two purposes: 1. Random processing of an indexed, sequential, or direct file. 2. Loading (creating) a direct file. The operation requires Factor 1 and Factor 2 entries, but columns 43-53 and 56-59 must be blank. A CHAIN may be conditioned by entries in columns 7-17. An indicator should be specified in columns 54-55. This indicator is set when a record is not found; output can not occur to a chained file when the specified record is not found unless the operation indicator was intended to ADD a record (see 10.4). If columns 54-55 are blank and the record is not found, program execution halts. When RPGLIB processes Chained files, more than one record identifying indicator may be on at the same time. 9.4.8.5.1 Random Input Processing - The entry in Factor 1 identifies the record to be retrived. The value is either a numeric relative record number (for sequential and direct files) or a record key (for indexed files). The entry in Factor 2 identifies the file. This file must be described on Forms F and I. 9.4.8.5.2 Direct File Output Load - When a direct file is created (loaded), the file is described as a chained output file on forms F and O. Factor 1 names a relative record number and Factor 2 names the file. The relative record number can be all or part of a field in an input record, or it can be generated by the RPG II program. When direct file load is to occur, RPGLIB clears to blanks the entire area reserved for the file. As a record is being output, the relative record number points to the disk record to which output occurs. Records not specified in the load are left blank. CALCULATION SPECIFICATIONS -- FORM C Page 9-30 When records are added to a sequential or indexed file, records are added at the end of existing records. Records are updated in a direct file, however, according to the relative record number. Once the direct file has been created, the file can be modified in later program executions by defining the file as an update file. It may be that duplicate record numbers will be entered as Factor 1. This could happen if information to be loaded is specified in different portions of several records. Since a direct file load implies a blank area, only the last record loaded for one relative record number will appear in the created file. The records can be completed in succeeding program executions, if direct file is declared an update file. 9.4.9 DEBUG Operation The DEBUG operation can assist in isolating programming errors in the object program. Whenever a DEBUG operation is executed, one or more records are written to the output file specified as Factor 2. All DEBUG statements in a program must refer to the same output file. A DEBUG operation is executed only if requested on the Control Specifications form (1 in column 15). When that column is blank, RPG II ignores DEBUG. Thus, DEBUG can be used during program checkout and only form H need be changed when the RPG II program is operational. The operation may be conditioned by entries in columns 7-17. Factor 1 is optional but may contain a literal or field name to identify the DEBUG output record. The Result Field is also optional but may name a field a table or array element, or an entire array. An entry in the Result Field causes the named item to be written to the output file when the DEBUG operation is executed. Columns 49-59 of the DEBUG line must be blank. The first record is automatically produced by a DEBUG operation and is a list of all the indicators which are currently on in the program. The format of the first record is: CALCULATION SPECIFICATIONS -- FORM C Page 9-31 Record Positions Values ______ _________ ______ 2-7 DEBUG 8 Blank 9-16 The constant specified as Factor 1 or the statement number of the DEBUG operation line. 17 Blank 18-31 INDICATORS ON- 32-end of record The names of all the indicators which are on, seperated by blanks. If the indicator list will not fit in one record, the list is con- tinued in the next record starting at position 2. RPGLIB writes additional records to the output file if a Result Field is specified for the DEBUG operation. Format of additional records: Record Positions Values ______ _________ ______ 2-12 FIELD VALUE or TABLE VALUE or ARRAY VALUE 13-14 Blanks 15-end of record The contents of the Result Field specification (up to 256 characters per element). A minus sign is appended to a negative element. When an entire array is written, the elements are seperated by blanks. The record will be continued starting in position 2 of the next record, if required. In Figure 9-4, a search is made of ARRAY for an element matching a value at ACTNO. If a match is not found, the following records are written to DBGFILE (assuming Form H contains a 1 in column 15): A list of indicators currently on. The word ACTNO and the value of that field. A list of indicators currently on. The contents of the entire array, ARRAY. CALCULATION SPECIFICATIONS -- FORM C Page 9-32 When the match is not found, RPGLIB bypasses the MOVE operation. When a match is found, the DEBUG operations are bypasses and the MOVE is executed. 9.4.10 TIME Operation This calculation operation code allows you to access the system time of day as well as the system date. To use this operation code, columns 28-32 must contain the operation code TIME and the Result Field must specify the name of a numeric field. To contain the time of day, the field specified by the Result Field must be six-digit numeric (with no decimals). To contain both the time of day and the date, the Result Field must specify the name of a 12-digit numeric field (with no decimals). Whole arrays cannot be specified in the Result Field. Columns 49-52 may be used to define the time of day field. Factor 1 and Factor 2 are not used and must be left blank. Half Adjust and Resulting Indicators (columns 53-59) are not used and must also be blank. If the field specified in the Result Field is six-digit numeric, time will be returned in the followin format: hhmmss Where hh is hours, mm is minutes, and ss is seconds. If the field specified in the Result Field is 12-digit numeric, both time and date will be returned as follows: hhmmssmmddyy Where hh is hours, mm is minutes, ss is seconds, mm is month, dd is day, and yy is year. 9.5 RESULT FIELD Columns Values _______ ______ 43-48 Name of field, table, array, or array element This entry names a location where the result of a calculation operation is placed. The name must conform to the rules for naming fields, tables, and arrays. The result field name together with entries in columns 49-52 define the result field for further references. If the name has not been defined in extension, input, or previous calculation specifications, appropriate entries must be made in columns 49-52 and the entry must not be referenced prior to this line. A field first defined in this entry is initialized to zeroes CALCULATION SPECIFICATIONS -- FORM C Page 9-33 (numeric) or blanks (alphameric) by the RPG II compiler. When the name has already been defined, entries in columns 49-52, if any, must agree with the previous definition. 9.6 FIELD LENGTH Columns Values _______ ______ 49-51 blanks or 1-256 The length of the result field may be entered in these columns, right-justified. Leading zeroes may be omitted. The maximum length for numeric fields is 15 characters; the maximum for alphanumeric fields is 256 characters. Unpacked lengths must be specified for numeric fields. If the field length for this field has been specified on an Input Specifications Form I, it need not go here. If it does, however, the length entered must agree with the Form I entry. If a result field length is first specified on Form C, subsequent references to the field for results need not give the length. 9.7 DECIMAL POSITIONS Columns Values _______ ______ 52 Blank or 0-9 For numeric result fields, this entry specifies the number of positions to the right of the decimal point. No entry is made for alphanumeric fields. A zero means the numeric field contains only an integer (whole number). A result field may have not more than 9 decimal positions. The number of decimal positions must never exceed the field length. When the number of decimal positions for a numeric result field has been specified, subsequent entries which reference the field do not need respecification. An entry in columns 49-51 is required when an entry is made here. When the result of a calculation produces fewer decimal positions than specified here, RPGLIB pads the low-order positions with zeroes. RPGLIB drops the low-order decimal positions when this specification is smaller than the number of decimal positions produced in a calculation. CALCULATION SPECIFICATIONS -- FORM C Page 9-34 9.8 HALF ADJUST Column Values ______ ______ 53 Blank or H An H in this column specifies that the result of an arithmetic operation is to be half-adusted (rounded). Half-adjusting is accomplished by adding a five to the position immediately to the right of the last position of the number to be stored in the result field. The addition is performed on the absolute value of the number to be stored. The correct sign is replaced before the rounded result is stored. If the move remainder (MVR) operation is used, half-adjusting must not be specified either for the MVR result or for the preceding divide (DIV) operation. 9.9 RESULTING INDICATORS Columns Values _______ ______ 54-59 blanks or 01-99, H1-H9, L1-L9, LR, OA-OG, OV Indicators specified in these columns serve four purposes: 1. To describe the value of a result field after an arithmetic operation. 2. To indicate the outcome of a CHAIN, LOKUP, COMP, or TESTB operation. 3. To specify indicators for SETON and SETOF operations. 4. To signal end-of-file for the READ operation code. The specified uses of this field have been defined in the preceding paragraphs, with one exception: When arithmetic operations are performed, the results are tested and indicators are turned on as follows: Indicator specified in columns 54-55 if result is positive. Indicator specified in columns 56-57 if result is negative. Indicator specified in columns 58-59 if result is zero. If a single resulting indicator is specified on more than one calculations line, its condition reflects the result of the last calculation performed. CALCULATION SPECIFICATIONS -- FORM C Page 9-35 9.10 COMMENTS Columns Values _______ ______ 60-74 Blanks or any alphanumeric characters These columns are not interpreted by the RPG II compiler, but are printed on the source program listing. 9.11 CALCULATION SPECIFICATIONS EXAMPLES Figure 9-5 highlights some of the principles just discussed. The meanings are explained below. Line 010 If halt indicator H1 and indicator 16 are both on, H1 and 15 are set off. Line 020 If indicator 13 is on and LR is not on, indicator 43 is set on. Line 030 As the comments field entry indicates, bits 0-7 of FLAGS are set off. Line 040 If indicator 23 is off, control is transferred to label LOOK. Line 050 Otherwise, FLD1 is compared with the numeric literal 21; if they are equal, indicator 12 is turned on. Line 060 If indicator 12 is on, control is transferred to subroutine SUBR. Line 070 Defines label LOOK, to which a transfer was made at line 040. Line 080 If bit 2 or 4 (but not both) is on in the flag word, indicator 77 is set. Line 090 If H2 is not on, a table lookup is performed using the content of a field named NAME as the argument in searching a table named TABNAM. TABADD is the name of a related table. If an equal case is found, indicator 77 is set on. Line 100 If indicator 77 is on, the value retrieved by the last executed table lookup is moved to a field ADDOUT which is defined as a 6-character numeric field with 2 decimal positions. Line 110 If a level 3 control break has occurred, a field named SUBTOT is added to a field named TOTAL and the result is half-adjusted and stored in TOTAL. TOTAL is an CALCULATION SPECIFICATIONS -- FORM C Page 9-36 8-character numeric field having 2 decimal positions. If the result is positive, indicator 63 is turned on. If the result is negative, indicator 64 is turned on. Line 120 If L3 and indicator 64 are on, an exception record(s) is output. Line 130 If L3 and 63 are on, ADDOUT is multiplied by the numeric literal 3 and the result is stored in TRIPLE, an 8-character numeric field with 2 decimal positions. Line 140 This entry names the beginning of a subroutine. Lines through 210 are part of the subroutine (SR in columns 7-8). Line 160 A record is read at this time from a demand file named NEWFILE. Indicator H2 is set on if end-of-file has been reached. Line 170 If H2 is on bit 2 is set on at FLAGS. Line 180 If H2 is not on, control is transferred to SUBXIT. Line 210 SUBXIT is named as the label of the last instruction and exit of the subroutine. CALCULATION SPECIFICATIONS -- FORM C Page 9-37 Figure 9-5 Calculations Examples CHAPTER 10 OUTPUT - FORMAT SPECIFICATIONS - FORM O Output specifications describe your output records. Logically these specifications may be divided into two portions. 1. Record description portions (columns 7-31) which describe the output file records to be written out. 2. Field description portion (columns 23-70) which indicates the position and the format of data on the output record. All output fields are initialized to blanks before each cycle. 10.1 FILENAME Columns Values _______ ______ 7-14 Blanks or a valid RPG II filename The filename must be one of those defined in the file description specification as output on update files. The filename must begin in column 7. You need to specify the output filename only once. It must be on the first line that identifies the file. 10.2 AND/OR RELATIONSHIPS Columns Values Meaning _______ ______ _______ 14-16 Blank Field Specfication AND Record Specification: Output Indicators on this line are in an AND relationship with those on the previous line. OR Record Specification: OR relationship with indicators on the previous line. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-2 One line in Form O allows up to three indicators for conditioning record output. If more than three indicators are needed for a record, an AND in columns 14-16 of the next line allows three more indicator codes. All codes are then considered in an AND relationship. An OR in columns 14-15 of the next line allows the user to specify up to three alternate output indicators for a record. For Example, a page heading line (record) usually goes on each new page. Forms eject to a new page may occur when the page is full, or when directed after certain control breaks. Thus, the heading record could be conditioned by overflow OR by Ln. When the OR conditions are used, the space and skip entries (columns 17-22) need not be filled in unless different spacing/skipping is desired for the alternate case. The AND/OR relationships may be used for record-definition lines only. Up to 20 AND, OR or mixed AND and OR lines are allowed for one output operation. AND/OR lines are not allowed in field definitions. 10.3 RECORD TYPE Column Values Meaning ______ ______ _______ 15 Blank Field Specification H Heading Record D Detail Record T Total Record E Exception Record Record type determines when a record should be output. Heading records apply only to print files, and normally are output at the beginning of printing by virtue of the first page indicator (1P) being defined as a condition. Subsequently, heading lines are usually printed as a result of overflow processing and skipping to a new page. Detail lines usually are output after each detail record has been processed. Total lines usually are output after control breaks have occurred and total calculations performed, and at end of job (LR indicator). Exception records are output when directed by the calculation operation EXCPT. Exception output conditioned by control level indicators or total output may not be specified for update files. The user may find it helpful to prepare Form O entries for each file in the following order: all heading records, followed by all detail records, followed by all total records, followed by exception records. It is not mandatory, however, that this sequence be followed. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-3 Figure 10-1 Form O OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-4 10.4 ADD RECORD This field allows records to be added to files. The corresponding files FORM F specification must have an A in column 66. Columns Value Meaning _______ _____ _______ 16-18 ADD This record will be added to an existing disk file. The ADD entry must be on the first Form O line describing a record to be added. 10.5 FETCH OVERFLOW An F in this column indicates that the overflow routine can be used for a printer file at this point. Column Values Meaning ______ ______ _______ 16 Blank Standard overflow F Fetch overflow An F can go on any total, detail or exception line except those conditioned by an overflow indicator. Table 10-1 describes the effect of overflow usage. An F in this column can cause printing of overflow lines and a forms advance to occur before the printing of detail and total lines is completed. Overflow can be fetched only if all the conditions specified in columns 23-31 are met and overflow has been sensed. Forms advance takes place only by explicit request (probably on the first heading line for a new page). When fetch overflow has not been specified, all detail and total lines conditioned for print during one cycle are printed. If any of those lines get printed on or below the overflow line, all remaining lines will be printed before output conditioned by the overflow indicator gets done. Thus, if there are more lines remaining to be printed than are available before the end of the page, unattractive output will result. Use of the fetch overflow feature can ensure the occurence of overflow processing before the page end is reached. Table 10-1 further describes the effects of overflow indicator usage. Figure 10-2 illustrates partial specifications for fetching overflow. Lines 030, 060, and 070 can fetch overflow. This can happen, however, only when indicators OA and L1 are set. After overflow has been fetched, the OA indicator is reset (following the forms advance OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-5 requested on line 010). When the output line specified on line 030 is ready to be printed, and OA and L1 are on, the forms advance occurs, the heading record (line 010) is printed, and records corresponding to lines 030 through 080 are printed on the new page. If overflow has not been sensed by line 030 but is set on when that line is printed, line 060 causes the overflow routine to be fetched. In that case, the forms advance occurs, the heading record is printed, and records described on lines 060 through 080 are printed on the new page. Notice that if line 060 fetches overflow, line 070 will not, because the overflow indicator will be reset at the forms advance. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-6 Table 10-1 Effects of Overflow Indicator Usage OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-7 10.6 FORMS CONTROL - SPACE/SKIP RPGLIB allows relative and absolute forms control. Columns 17 and 18 allow up to three lines of spacing, before and/or after a print line, relative to adjacent lines. Columns 19-22 allow absolute spacing to any particular line on a page, before and/or after a print line. If both spacing and skipping are specified on the same line, the skip always precedes the space. Thus, entries in all four yields: 1. Skip before 2. Space before (print required line) 3. Skip after 4. Space after If all these columns are blank, single spacing occurs after each line is printed. Entries in these columns are only applicable to printer files. 10.6.1 Space Forms Control Column 17 specifies the spacing before and column 18 the spacing after printing a line. Columns Values Meaning _______ ______ _______ 17,18 Blank Default: blank in 17 = 0; blank in 18 = 1 1-3 Indicated number of spaces before (column 17) or after (column 18) printing. Entry in 17 yields same number blank lines; in 18 yields one less blank line. Use of columns 17 and 18 does not conflict with the ADD encoding described in 10.4 because records may not be ADDed to printer files, and line spacing is not germane to disk or magtape files. 10.6.2 Skip Forms Control Columns 19-20 and 21-22 specify skipping before and after printing a line. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-8 Columns Values Meaning _______ ______ _______ 19-20, or Blanks Skipping is not requested 21-22 01-99 Lines 01-99 A0-A9 Lines 100-109 B0-B2 Lines 110-112 The codes indicate the forms location of the next line to be printed. An entry in columns 19-20 specifies a skip before the line is printed; an entry in columns 21-22 specifies a skip after the line is printed. When the skip is to a lower line number, the forms are advanced. No action occurs when the forms are already positioned at the specified line. Exception: There is no way to obtain overprint. Thus, a skip to 5 before and after yields a skip to 5 on the next page after printing. If the destination of a skip (or space) is beyond the overflow line but before a top of form, the overflow indicator is set on and remains on until forms advance occurs. A skip code cannot exceed the forms length specified on Form L, or 66, if there is no Form L. The skip function is useful in moving form stock more than the lines possible by a spacing entry, or when the number of spaces to the de- sired print position may vary. The skip function is also useful in positioning for subtotal, total, and heading lines. 10.7 OUTPUT INDICATORS Columns Values _______ ______ 23-31 any indicators The output indicator entries can condition output of entire records and/or their component fields. Any of the indicators associated with RPG II may be specified. The indicator codes are entered in columns 24-25, 27-28, 30-31 and are in an AND relationship. If the indicator should be off for output to occur, N goes in the preceding column (23, 26 or 29). If no indicators, or only negative ones are specified for a heading or detail operation, the record will be output before the first cycle. Warning: Only one record can be written to an update file in one cycle, so the user must be careful not to specify multiple records in one cycle for update files. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-9 All total records conditioned by the LR indicator are produced last. Control level indicators condition when output records or fields are written. Total records (T in column 15) with no overflow indicator in columns 23-31, are written only after the last record in a control group has been processed. Detail records (D in column 15) with no overflow indicator in 23-31, are written only after the first record of the new control group has been processed. When columns 23-31 contain both a control level indicator and an overflow indicator, the record is produced only when overflow has been sensed and the control break has occurred. Print records conditioned by an overflow indicator are produced only when overflow has been sensed. An overflow indicator cannot condition an E (exception) record but can condition a field of an exception record. A specified overflow indicator must be identical to the overflow indicator named on the Form F for the file that will receive the record. An overflow indicator may have an OR condition with the 1P indicator if identical heading records will go on every page. The 1P indicator, however, can be specified only for heading and detail print lines. 10.8 FIELD NAME Entries in columns 32-37 identify each field to be included in the output record or print line last specified. Columns Values _______ ______ 32-37 1. Any field name previously defined in the program. 2. The special words PAGE, PAGE1, PAGE2, *PLACE, UDATE, UDAY, UMONTH, and UYEAR. 3. The name of a table, array, or array element. If a constant is to be included in the output, columns 32-37 are left blank and the constant is defined in columns 45-70. If an entry is made in the field name columns, columns 7-22 must be blank. 10.8.1 Field Names The order in which the fields appear in the output record is determined by the entries in columns 40-43 (described in paragraph 13), not by the order of the field name entries of Form O. A field name is entered left-justified in columns 32-37. It must be previously defined as a field of an input record in columns 53-58 of the Input Specifications Form I or as a result field of an operation in columns 43-48 of the Calculation Specifications Form C. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-10 If overlapping fields are specified in one record, the field listed last overlays prior specifications, resulting in lost data. 10.8.2 PAGE, PAGE1, PAGE2 RPGLIB will automatically number print file pages if PAGE, PAGE1, or PAGE2 is entered in columns 32-37 instead of a field name. (The three names provide three page counters for multiple sections of a printed output file). Each page of the output will be numbered consecutively in the print position called out by columns 40-43. The page number is taken from a four-digit numeric counter which RPGLIB increments by one before using it on each page. Page numbering usually starts with the number 1. The user can, however, start with any number via a Calculation result or by specifying a record on the Input Specification Form I containing a field named PAGE, PAGE1, or PAGE 2. The field may be constant (one less than the desired number) or dependent on input. A page number may be reset to zero by use of the blank after code (B in column 39) in the line where the page counter label is entered. The reset function also may be conditioned by an output indicator such as L1-L9. The output indicators for PAGE, PAGE1 or PAGE2 mean this: Whenever indicator conditions assigned to PAGE, PAGE1 or PAGE2 are satisfied, the specified page counter is reset to zero and incremented by one before printing. Z-ADD or MOVE with the desired reset value entered as a numeric literal in Factor 2 are two of the ways a Calculation can change a counter value. Conditioning indicators may be used in this case also. 10.8.3 *PLACE The RPG II special word *PLACE allows fields to occupy more than one position in an output record without being respecified. When *PLACE is encountered, all fields previously specified for the record are repeated in the same relative position, ending at the character position named in columns 40-43 of the *PLACE line. Rules for using *PLACE: 1. *PLACE goes on the line following the last field specification which is to be repeated. 2. *PLACE entries may be made on successive lines. 3. An *PLACE specification causes all prior field specifications for the record to be moved. 4. The end position specified for an *PLACE must be at least twice the previously named end position for the record. (This does not include previous *PLACE specifications.) If OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-11 not, some output fields will overlap, and characters will be lost. 5. The starting (left-most) character position for an *PLACE move is always position 1 of the record. 6. An *PLACE line cannot be conditioned by indicators in columns 23-31. *PLACE movements are automatically conditioned by indicators listed in the preceding field specifications. 10.8.4 Date Field The special words UDATE, UMONTH, UDAY, UYEAR refer to the current system date. A reference to UDATE yields a six-character numeric field in the format mmddyy. UMONTH refers to the 2-character mm, UDAY to dd, and UYEAR to yy. When a UDATE field is edited (paragraph 10.11), the result is of the form mm/dd/yy. None of these special words can be specified in the result field of a calculations specification. Any of the words, however, can be Factor 1 and Factor 2 names on Form C. 10.9 EDIT CODES (COLUMN 38) This entry is used to specify editing for numeric fields. No entry should be made for alphanumeric fields, or if an editing word is entered in columns 45-70. Modifiers affecting the editing function specified in column 38 may be encoded in columns 45-47. There are two kinds of edit codes. Codes in the first category do not cause punctuation of the numeric output field, and entries in columns 45-47 are not allowed. Codes in the second category may cause punctuation of the output field and affixing of negative balance indicators, and entries in columns 45-47 are allowed. Table 10-2 summarizes the Edit codes. A plus or minus sign is encoded with the low-order digit of an numeric field. The sign is printed with the digit, producing a non-numeric character, unless the field is edited. 10.10 BLANK AFTER Column Values ______ ______ 39 Blank or B The entry of B in this column causes the source field to be reset to OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-12 blanks if alphanumeric, or zeroes if numeric after the content of the field has been placed in the output record. If no entry is made in column 39, the source field remains unchanged. A blank after operation can not be specified for a date field name (e.g., UDATE) a look-ahead field, or a field in an update file. When blank after is requested for a table name, RPGLIB blanks the element corresponding to the one in the holding area, and the holding area itself. When blank after is requested for a constant, the constant is set to blanks after its first use. Care must be taken in specifying blank after for a field which is used in output. The blank after should be designated in the last record in which the field is output to avoid premature clearing of the field. Blank after provides a convenient means for resetting control break accumulators after they are printed at total time. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-13 TABLE 10-2 Edit Codes Column Values Meaning ______ ______ _______ Category 1 (no punctuation; no entry in 45-47 allowed) 38 X Suppress a plus sign for non-negative fields. Y Causes a date field to be edited as follows: mm/dd/yy where the first digit of the date is suppressed if zero. Z Causes suppression of leading zeroes in the output field and removal of the sign. Category 2 (punctuation; entry in 45-47 allowed) 1 Print with commas, print zero balance, suppress sign. 2 Print with commas, suppress zero balance, suppress sign. 3 Print without commas, print zero balance, suppress sign. 4 Print without commas, suppress zero balance, suppress sign. A Print with commas, print zero balance, print sign as CR. * B Print with commas, suppress zero balance, print sign as CR. C Print without commas, print zero balance, print sign as CR. D Print without commas, suppress zero balance, print sign as CR. J Print with commas, print zero balance, print sign as -. K Print with commas, suppress zero balance, print sign as -. L Print without commas, print zero balance, print sign as -. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-14 TABLE 10-2 (cont'd) Edit Codes Column Values Meaning ______ ______ _______ M Print without commas, suppress zero balance, print sign as -. * For codes A through M if the field is positive, no sign indication is printed. 10.11 END POSITION IN OUTPUT RECORD This entry specifies the rightmost or least significant position of the designated field or constant in the output record. Columns Values _______ ______ 40-43 any number less than or equal to the record length. The entry is numeric and right-justified. Leading zeroes may be omitted. The end position entry must not exceed the record length specification for the file. If punctuation or other charaters are added to the field by editing, the effective field length is increased. The entry in columns 40-43 must reflect the length of the edited field. If columns 32-35 contain PAGE columns 40-43 must show the low order position of the page number in the print line. The end position of an *PLACE specification is the rightmost character position to which the move occurs. 10.12 FIELD TYPE Column Value Meaning ______ _____ _______ 44 Blank Alphanumeric or unpacked decimal data 10.13 CONSTANT OR EDIT WORD, COLUMNS 45-70 The entries in these columns (1) define a constant to be placed in the output record, (2) indicate a modification to the edit function coded in column 38, or specify an edit word for output format. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-15 10.13.1 Constants An alphanumeric constant may be defined by encoding an apostrophe in column 45 followed by up to 24 characters in any combination terminated by another apostrophe. Any alphanumeric characters including blanks may be used. An apostrophe within the constant is encoded by entering two consecutive apostrophes. EXAMPLE: IT'S is defined as a constant by encoding 'IT''S' beginning in column 45. When a constant is used as a source field for data in an output record, Field Name (columns 32-37) must be left blank. When a constant exceeding 24 characters is required, subsets of characters go on successive lines, as if they were independent. Each line must have an appropriate entry in columns 40-43. 10.13.2 Edit Code Modifiers -- * And $ Two edit code modifiers may be entered in columns 45 and 46, left-justified, for use in conjunction with the Edit Code (column 38). An asterisk (*) says that all leading zeroes of the numeric field shall be replaced by the asterisk character. '$' indicates that a dollar sign shall be placed just preceding the high order non-zero digit of the numeric output field. This is called the floating dollar sign function. The asterisk and dollar sign allow check protection. 10.13.3 Edit Words The Edit Codes for column 38, plus asterisk and dollar signs provide normal editing of typical numeric fields. The edit word facility allows more unusual or complex editing. An edit word is like a mask or framework which allows insertion of numeric characters from the source field named in columns 32-37. Edit words allow inclusion of decimal points, commas, dollar signs, negative balance indicator (if any), even whole words between one digit and the next. Table 10-3 gives the rules for edit words. OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-16 Table 10-3 Rules for Edit Words OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-17 10.14 OUTPUT-FORMAT SPECIFICATIONS EXAMPLES Figure 10-3 shows various examples of the Output-Format Specifications Form O. The examples are discussed below. Page 08 Lines 010 and 020--A header record for a file named PRTFIL is to be spaced two lines after printing (column 18) and a skip before printing should be made to line 6 (columns 19-20). The line is printed if indicators 17, U3 and 06 are on, (AND in columns 14-16), and 05 is not on. Line 030--The same header record is printed if overflow indicator OA is on. Lines 040 through 070--The contents of UDATE are to be edited and placed in the print line ending in position 68; the contents of page counter PAGE1 are to end in position 100. The remainder of the heading, consisting of the title PRINT FILE LIST and the captions DATE and PAGE are supplied as constants to be placed to end in positions 59 and 95. (Notice that the length of the heading line required that components be split.) Line 080--A detail record of PRTFIL is printed if indicator 02 is on--the carriage is spaced one line after printing, since no skip or space is indicated. Lines 090 and 100 describe the fields of this record. Line 090--FLD1 is placed to end in position 60 of the print line. Leading zeroes are suppressed (Z in column 38). Line 100--FLDX is zero suppressed and placed to end in position 45 of the print line. RPGLIB will print FLDX only if indicator 15 is on (15 in columns 24-25), and the record conditioner 02 is on. Line 110--If indicator L1 is on, RPGLIB will print a total record of PRTFIL after a skip to line 60. Lines 120 and 130 describe the fields of this record. Lines 120 and 130--The total line is made up of the caption SUBTOTAL supplied as a constant and the field named ATOTAL. RPGLIB will set this field to zeroes after printing (B in column 39). Line 140--If indicator LR is on RPGLIB will print a total record of PRTFIL after spacing three lines. After printing it, RPGLIB will skip to line 06. Line 150 through 200--The total record has the following configuration: OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-18 Figure 10-3 Output Example OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-19 Figure 10-3 (cont'd) Output Example OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-20 Page 09 Line 010--A record is added (ADD in columns 16-18) to DSKFIL if indicator 22 is on. Line 020--The record consists of a field named DTL to be output in binary format ending in position 80. Line 030--RPGLIB will print a detail record of LISTFIL, with one space after (default) if indicator 23 is on. Lines 040 and 050--The detail line contains an account code (ACCT in Field Name) and an amount (AMT in Field Name). The source field AMT is edited according to the edit word given in columns 45-62. The trailing asterisk entered in column 61 of the edit word is placed in position 30 of the print line. The edit word provides for the fixed dollar sign, comma and explicit decimal point punctuation, zero suppression and asterisk protection ending just before the decimal point, a space after the cents position, the CR symbol if the source field is negative, and a trailing asterisk. CHAPTER 11 USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Chapter 6 describes specification of tables and arrays. This chapter describes their use and formation. Tables are systematically arranged sets of information more limited in scope than other files. Examples: tables of freight rates, withholding percentages, prices, conversion coefficients. RPGLIB treats tables much as clerks do in manual systems. A document (or record) provides a piece of known information such as item stock number. The clerk (or RPGLIB) then uses it to obtain another piece of information from a table by search or lookup. Thus, item stock number may be used in looking up the item price in a table of prices listed by stock number. Tables might be used to provide verification only. For example, an input account code may be used to search a table of all active account codes to determine the input code's validity. RPGLIB may extract an element from a table with a MOVE operation. RPG II allows table updating, whereby entries may be changed during processing. An example is the substitution of new prices in a price table. Arrays are also systematically arranged sets of information which can be searched for a uniquely identified data item. In addition, an array element may be referenced by position number. Another difference is that an unindexed reference to an array name is a reference to the entire set of data rather than to an item in a holding area (paragraph 9.4.6). RPGLIB can use an array element or the entire array as an operand in a calculation. Advantages of table and array formats over file formats: (1) A table or array is compact and may be completely contained in computer memory for random accessing. (2) Any member of the entire set of entries comprising the table or array may be retrieved for use once or repeatedly during the course of processing by an RPG II object program. Table names begin with TAB; array names do not. Both follow the rules for naming fields. USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-2 Each element in a table or array has the same length, format (alphanumeric or numeric), and number of decimal positions. DEFINITIONS: 1. Compile Time Table or Array. A compile time table or array is compiled with the source program and becomes part of the object program. A compile time table or array can be permanently changed only through recompilation, but it can be output after other processing is completed at end of job, if requested on Form E. 2. Pre-Execution Time Table or Array. A pre-execution time table or array is loaded with the object just prior to reading the first non-table or array input record. A pre-execution time table or array can be modified by the program and output at program termination. 3. Execution Time Array. An execution time array is read or created during the input or calculations phase of an object program cycle but cannot be output at program termination. 4. Related Tables and Arrays. Related tables and arrays are files which are used together. They may be specified separately or in alternating format. Whereas all items in one table or array must have the same characteristics (element length, etc.), related tables or arrays need not have identical characteristics, nor must they contain the same number of elements. When a search of related tables is successful, corresponding items of the two tables are brought to the holding areas. A successful search of related indexed arrays causes the index field to point to the corresponding items in the related arrays. Figure 11-1 illustrates a use of related tables. A shipping transaction file (at 1) is sequenced by a stock number within record type within customer number. There is one type 1 record for each customer and a variable number of type 2 records. The type 1 record shows the date of shipment and the address to which shipment was made. Each type 2 record shows a stock number for each item shipped and the quantity shipped. Item stock numbers and associated item prices are maintained in related tables (at 2). The stock number from the type 2 transaction record is used as a search argument for item price from the price table (at 3). The price then is used in extending the item quantity to produce line item price. A record for the line item is output for invoicing. Figure 11-2 illustrates two methods for specifying related tables. USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-3 Figure 11-1 A Use for Related Tables USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-4 Figure 11-2 Two Methods for Specifying Related Tables USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-5 5. Short Tables and Arrays. A short table or array contains some null elements. Null elements equal zero, if numeric, or blanks if alphanumeric. Significant elements may replace the null elements at a later time. A short table or array must have at least one non-null element. 6. Full Table or Array. Every element of a full table or array contains significant data. 11.1 FORMING TABLES AND ARRAYS Tables and arrays may be formed inside or outside the computer. Elements formed on the outside may be entered through any input device. Any computer program, including an RPG II program, may also form them, and they may be output to any sequential file medium. Tables and arrays have the same format and structure rules whether they are formed outside or within the computer. The complete set of entries comprising a table or array is considered a sequentially organized file, although the entries need not be in sequence within the table or array. A table or array file must have a unique name consistent with the file naming rules stated in Paragraph 1.6. The filename must not be confused with the table or array name described earlier in this chapter. Table and array files may be assigned to the same device, if required. The files are read from the device in the order they are specified on Form F. Chapter Six describes rules for table files. An array file can abide by the rules for table files or it can be described as any other input file on the Input Specifications form, Form I. Exception: An execution time array to be read by the program can only be described on Form I. The definition on Form I specifies whether the array is a single record or many records, and whether the elements are contiguous in a record. If the array name appears as the field name (paragraph 8.11) then the array is contained in one record, and the elements are contiguous. Otherwise, each array element must be specified on its own Form I line, with the appropriate field positions specified. An array cannot be used until every element is in core. Calculation and output operations, therefore, may have to be suspended for several program cycles until RPGLIB has read all array file records. Figures 11-3 and 11-4 illustrate the coding required to fill an array from contiguous elements of a single input record. Figure 11-5 illustrates that required when elements are separated by 1-character values which serve as index values for the array. Rules for entering a compile time table or array: USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-6 1. The table or array must be on the device that holds the source program and follow the RPG II source program. 2. Each distinct table or array must be preceded by a record having **b in positions 1-3. As this record is a delimiter, the first element of a table or array record must not contain those characters in the first three positions. 3. The last compile time table or array is followed by a record reading /* in positions 1 and 2. 4. The tables and arrays must be loaded in the order specified on Form E, ignoring any pre-execution time table and array definitions that may be interspersed with compile time entries on that form. 5. Numeric tables and arrays must be in unpacked decimal form. Figure 11-6 illustrates the placement of compile time tables and arrays in the compiler input stream. In this example, the user has two of his own compile time tables, TABA and TABB. Pre-execution time tables and arrays are not loaded with the source program but rather just prior to execution of the object program. Rules for pre-execution time tables or arrays: 1. Each table and array is terminated by an end of file. The /* record is not used. 2. The tables and arrays are loaded before the first input record is read. 3. Pre-execution time tables and arrays must be arranged in the order specified on form F. An execution time array is loaded or created during execution of the object program. The array is not checked for sequence, but column 45 of Form E (Sequence) must contain an A or D code if high or low LOKUP is specified for the array. If the execution time array is in packed decimal or binary format, an appropriate entry must be specified in column 43 of Form I. Length specified for arrays in these formats reflect the packed or binary length of an element, in numbers of bytes. Columns 19-26 and 46-57 of Form E must be blank for execution time arrays. That is, the array cannot be output at end of job, and an alternating array cannot be specified. In Figure 11-7, an array is to be built during the calculations phases of execution. It is to contain square roots of the numeric values contained in two input records. The first input record is defined by a 1 in position 80; the second record type has a 2 in position 80. The conventions for naming arrays have been established in preceding USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-7 paragraphs. The names must be shorter, however, when indexing is used with the array name. When the array is used as the result field in calculations specifications, the array name plus comma and index can not exceed six characters, so the array name must be four characters or less. USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-8 Figure 11-3 Coding to Fill an Array from Contiguous Elements of a Single Input Record USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-9 Figure 11-4 Coding for Contiguous Elements of a Single Input Record USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-10 Figure 11-5 Illustration of Required Array Elements Supported by One-Character Values USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-11 Figure 11-6 Placement of Compile Time Tables and Arrays USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-12 11.2 USING TABLES AND ARRAYS LOKUP operations specify table and array search. Paragraph 9.4.6 describes LOKUP. When elements in a short table or array are being added, deleted (replaced by zeroes or blanks), or changed, the number of entries per table or array is not altered by the operations. This number is fixed on the Extention Specifications, Form E. Rather, the number of meaningful entries in a table or array can be altered. By selection of proper search arguments and criteria, the non-meaningful entries can be ignored during processing. The following rules apply when using arrays in Calculations Specifications. 1. When Factor 1, Factor 2, and the Result Field specifications are all unindexed array names, RPGLIB does the operation using the first element of each array, then the second element of each array, and so on until at least one of the arrays is exhausted. Result field array elements not participating in the calculations (i.e., unreferenced elements in a longer array) remain the same. 2. When one of the factors is a field or constant and the other factor and result field are unindexed arrays, RPGLIB does the operation once for each element in the shorter array. RPGLIB uses the field or constant in each operation, and does not change unreferenced result field array elements. 3. Resulting indicators can not be specified unless the operation code is LOKUP or XFOOT (yielding one result). 4. In arithmetic operations, arrays must be numeric. Half-adjusting can be specified. 5. A Result Field can not be specified for the LOKUP operation. In Output-Format Specifications, a table element and an indexed array element are treated like any other field specification. Blank after codes can be used. When an unindexed array name is specified as a field name of Form O, The value specified as the end position in the output record is the position of the right-most character of the last element in the array. Any editing specified for the array applied to each element in the array. Elements, therefore, must be individually specified as indexed elements if uniform editing can not be used. RPGLIB automatically inserts two blank characters in front of each element of the array unless an edit word is used. Edit words for unindexed arrays must contain explicit leading blanks, if desired. The following example illustrates the use of arrays in Output-Format Specifications, and shows how they can reduce the number of coding USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-13 lines required. In this program three levels of totals are maintained and output at specified control breaks. In Figure 11-8, as input records are read and record identifying indicator 25 is set, fields FLDA, FLDB, FLDC, and FLDD are added to level 1 subtotals L1TA, L1TB, L1TC, and L1TD, respectively. At a level 1 control break, the level 1 subtotals are added to subtotals L2TA, L2TB, L2TC, and L2TD, respectively. At a level 2 control break, totals L3TA, L3TB, L3TC, and L3TD are updated. Total lines are output when the appropriate control level indicators are on, and totals are blanked to zeroes after printing. Since L1TA-L1TD, L2TA-L2TD, and L3TA-L3TD are first defined as result fields in Form C, the fields have already been initialized to zeroes by RPG II. They do not, therefore, require initial clearing by the source program. In Figure 11-9, execution time arrays SL1, SL2, and TL3 are defined for accumulation of the various subtotals and totals. The output produced by Figures 11-8 and -9 is identical. Figure 11-9, however, eliminates most of the repetitious coding lines of Figure 11-8. Since the array elements are defined on Form E in Figure 11-9, the definitions are not repeated on Form C. Whereas in Figure 11-8 the level 1-3 fields are defined with lengths of 6, 7, and 8 characters, respectively, each element of each array is defined as 8 characters, for equal spacing on the output line. The equal spacing occurs in Figure 11-8 as a result of individual end position specifications for the fields. USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-14 Figure 11-7 Example of an Array Built During the Calculations Phase of Execution USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-15 Figure 11-7 (cont'd) Example of an Array Built During the Calculations Phase of Execution USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-16 Figure 11-8 Input Records USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-17 Figure 11-8 (cont'd) Input Records USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-18 Figure 11-9 Definition of Execution Time Arrays USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-19 Figure 11-9 (cont'd) Definition of Execution Time Arrays CHAPTER 12 RPG II FILE PROCESSING The various file structures and modes of processing available in RPG II were described briefly in Chapter 5. This chapter discusses in detail the subject of record selection and the significance of file structures to the modes of processing. 12.1 SEQUENTIAL FILE PROCESSING All records in files with Sequential organization are written to the storage medium with no intervening logical gaps -- each one followed by the next. Files may be in sequential organization on any medium subject to specification for RPG II. Frequently, the records of a sequentially organized file are logically in sequence. For RPG II, logical sequence implies keys in the file that are in ascending or descending order. RPG II can handle ordered and unordered sequentially organized files. The SORT-10 program can put sequential files in order or RPG II object programs can create them in order, if the input data is in the correct sequence. All files on any medium can be created in sequential order by RPG II. Files on disk may be created with indexed organization to permit random processing later. Other sequential disk files may be processed non-sequentially as well through use of a record address file of tags (ADDROUT file). RPG II object programs process records of sequential files as they appear from the beginning of the file. RPGLIB can process to end of file, or stop in the middle (see paragraph 5.4, END OF FILE). Example: A customer billing address file is referenced in preparing bills for mailing. When the record of the last customer to be billed has been reached, there is no further use for the mailing address file in this run, although there may be many address records remaining in the file. An indexed file may be processed from beginning to end of the index or within limits supplied by a record address file. Example: A program must process an inventory file to generate an inventory valuation RPG II FILE PROCESSING Page 12-2 report for selected warehouses. If the file is sequenced by stock number within warehouse, the record address file specifies the lowest and highest possible record keys for the warehouses for which the report is desired. When there is only one input file it is the primary file (P in col. 16 of Form F). The entire file is processed beginning with the first record and continuing until end of file. At end of file, RPGLIB sets on the LR (last record) indicator, and starts end of job activities. With multiple input files, one is primary and the other(s) are secondary. If there is no relationship between the processing of the files, RPGLIB processes the primary file to end of file before it processes the secondary file(s). RPGLIB processes two or more secondary files in the order of their Form F descriptions. When a record matching relationship exists among multiple files, the file which controls processing is primary and the others are secondary. In the example of mailing bills, the billing transaction input file would be primary and the billing address file would be secondary. The problem determines primary and secondary designations. In a file update involving posting, posting occurs to the record currently being processed. In this case, the posting file is designated a secondary file, ensuring that individual records to be posted (from the primary file) have already been read and are available. In the following discussion of primary and secondary input files, note that RPGLIB first reads records into a read area, and then moves them to a process area. When a control break occurs, RPGLIB executes all control break processing and then moves the record to the process area. 12.1.1 Matching Records Interrelated multiple files are processed via the matching record technique. The matching field entries on Form I (columns 61-62) determine when records of a secondary file are to be processed. Rules for matching field entries: There can be up to nine matching field specification entries (M1-M9) per record. The locations of the matching fields within a record type of file must be the same for all records of that type. The locations of the matching fields in different record types may be different. Not all the record types in a file need have a matching field. RPG II FILE PROCESSING Page 12-3 Records can be matched by one field, many fields, or the entire record. The same number of matching field entries must be specified for records of two or more files being matched. The combined lengths of the matching fields for a given record must equal the combined lengths for any record to be matched. The combined lengths must not exceed 256 bytes. If matching fields are specified for a single input file, they are used in sequence checking of the file. Matching fields can be specified for a file even if not all records are to be matched. A matching field entry is not made for records which are not to be matched. RPGLIB turns on the Matching Record Indicator (MR) when a match occurs among records of a primary file and secondary file(s). This indi- cator may condition calculation operations and output functions specified on Forms C and O. RPGLIB leaves the MR indicator on during the complete processing of the record and turns it off after all calculations and printing specified for the record are completed. If no matching occurs among records of a primary file and secondary file(s), the MR indicator is not turned on. Its off status may con- dition calculations for unmatched records or selection of unmatched records for output. If there is more than one matching field entry for a record, the codes M1-M9 must be assigned in turn to the fields of increasing significance, in the order of significance of the match. If a matching field in any record is defined as numeric, the fields at that same level (i.e., having the same value of Mn, will be treated as numeric in all records to be matched. If all fields at a given level are defined as alphanumeric, they will be compared logically. In matching records of primary and secondary files, four situations can occur: 1. There is a matching primary record. 2. There is a matching secondary record. 3. There is an unmatched primary record. 4. There is an unmatched secondary record. Rule for order of processing: Records having no designated matching fields are processed before records having matching fields. When records match, the primary file record is processed first; when the RPG II FILE PROCESSING Page 12-4 records do not match, the record first in sequence according to the matching field value is processed regardless of file. Matching records of additional secondary files are processed in the order of specification of the files on Form F. Figure 12-1 illustrates the selection based on matching fields of records from one primary and one secondary file. The result is shown as a merger of the two files. The MR indicator is on (set) during processing of the shaded records. The files shown are in ascending sequence; the record selection would be inverted if the files were in descending sequence. RPG II FILE PROCESSING Page 12-5 Figure 12-1 Selection Based on Matching Fields RPG II FILE PROCESSING Page 12-6 Figure 12-2 Read and Process Areas for Records in Figure 12-1 RPG II FILE PROCESSING Page 12-7 Figure 12-2 (cont'd) Read and Process Areas for Records in Figure 12-1 RPG II FILE PROCESSING Page 12-8 12.1.2 Look-Ahead Fields Look-ahead extends the matching record capability by allowing fields in the read area to be used before the record has been selected for processing. Look-ahead can not be specified for chained or demand files, as records in these files are not held in a read area before processing. Figure 12-2 illustrates the read and process areas as the records in Figure 12-1 are being selected. In picture 1, the first record of each file has been read. In picture 2, the secondary record with no matching field specification has been selected for processing. In pictures 2 through 4, the records selected for processing and available for look-ahead are charted below: Records Picture Record Being Processed Available _______ ______ _____ _________ _________ 2 S1 P1 and S2 3 P1 P2 and S2 4 P2 P3 and S2 Look-ahead can be specified for an update file, but it applies to the current record of the file only. A copy of the current update record remains in the read area until the end of cycle; thus, the next record is not available for look-ahead until the next cycle. If the primary file in Figure 12-1 were an update file, the read and process areas would take the configurations shown in Figure 12-3. In pictures 2 through 4, the following list indicates the current record being processed and the records available for look-ahead. Records Picture Record Being Processed Available _______ ______ _____ _________ _________ 2 S1 U1 and S2 3 U1 U1 and S2 4 U2 U2 and S2 Figure 12-4 illustrates an application for look-ahead fields. A price table is defined as a primary update file named PTABLE. Price changes for some items in the table are contained in a secondary file named SFILE. When matching occurs, the new price is taken from SFILE and placed in positions 11-18 of the PTABLE record. When matching does not occur and a secondary record is being processed, the erroneous record is printed out. RPG II FILE PROCESSING Page 12-9 Figure 12-3 Read and Process Areas if Figure 12-1 Were an Update File RPG II FILE PROCESSING Page 12-10 Figure 12-3 (cont'd) Read and Process Areas if Figure 12-1 Were an Update File RPG II FILE PROCESSING Page 12-11 Figure 12-4 An Application for Look-Ahead Fields RPG II FILE PROCESSING Page 12-12 Figure 12-4 (cont'd) An Application for Look-Ahead Fields RPG II FILE PROCESSING Page 12-13 12.2 INDEXED FILE PROCESSING Indexed (ISAM) files may be loaded by RPG II as output files. As this occurs (through use of the indexed access method -- ISAM), RPGLIB uses the record keys to form an index. Once the file has been loaded, ISAM may be used to access records in later runs on a random basis. RPGLIB uses the record key of the desired record to find the index that points to the right record. The record then may be used as an information source for other processing or changes may be made to the record, after which it is returned to its position in the disk file. NOTE It is very important that the user understand that RPG II is not capable of actually creating indexed files. In order for RPG II to utilize the ISAM access method, the file must first be created using the ISAM program. This program will create an empty indexed file, which can then be loaded with data via an RPG II program. RPGLIB can add new records to an indexed file which is being accessed randomly. ISAM provides for changing the index as required to accommodate the new record. Processing an indexed file with specific keys using CHAIN allows greater selectivity than processing within limits. Further, while processing within limits reduces the number of records to be handled, it still requires sequential accessing within those limits. With CHAIN the order of processing may be completely non-sequential. This mode of processing allows retrieval of specific information in an indexed file. For example, an inventory manager may be concerned about the balances of certain critical stock items. Inquiry can be accomplished by entering the critical item numbers in a file to be used with the CHAIN operation. Figure 12-5 illustrates the creation of an indexed file on disk or DECtape. In the example, the values in parentheses are the re- cord key values (one digit numbers for simplicity in this case). D1, D2, etc. are disk addresses. 12.3 DIRECT FILE PROCESSING Direct access files are sequentially organized disk files which also may be processed randomly. Records are retrieved through ADDROUT files or with the CHAIN operation. A direct file is created in RPG II through the CHAIN operation. Because a direct file is not organized according to a known key RPG II FILE PROCESSING Page 12-14 sequence, sequential processing of the file by key or limits is not possible. Figure 12-6 illustrates the organization of a direct file on disk. At file creation, relative record numbers are supplied with the records to be loaded. The shaded areas in the illustration indicate null records (containing blanks) into which a record was not loaded. RPG II FILE PROCESSING Page 12-15 Figure 12-5 Indexed File Organization Figure 13-6 A Direct File Load APPENDIX A SUMMARY OF RPG II SPECIFICATIONS This appendix is provided as a brief summary of Chapters 3-10. It is intended as a quick reference for programmers who are acquainted with RPG II. On any form, columns for which specifications are not listed are to be left blank. A.1 COMMON ENTRIES RPG II specifications forms should be ordered in ascending numeric sequence based on columns 1-5. Pages should be arranged in the following order and numbered accordingly: 1. Control Specification (Form H) 2. File Description Specifications (Form F) 3. Extension Specifications (Form E) 4. Line Counter Specifications (Form L) 5. Input Specifications (Form I) 6. Calculation Specifications (Form C) 7. Output-Format Specifications (Form O) Columns 1-2 (Page) Numeric page number Columns 3-5 (Line) Numeric line number within page Column 6 (Form Type) Enter an H, F, E, L, I, C, or O to indicate the specifications form type. Column 7 (Comments) An asterisk in this position indicates that the entire line is commentary. SUMMARY OF RPG II SPECIFICATIONS Page A-2 Columns 75-80 (Program ID) Enter any valid character into these columns to identify the object program. Only the entry on Form H is used to identify the program. SUMMARY OF RPG II SPECIFICATIONS Page A-3 A.2 CONTROL SPECIFICATIONS - FORM H Column 15 (Debug) Blank DEBUG operation not used. 1 DEBUG operation used. Column 41 (Forms Positioning) Blank 1P line printer only once 1 First 1P line printed repeatedly to allow forms positioning. SUMMARY OF RPG II SPECIFICATIONS Page A-4 A.3 FILE DESCRIPTION SPECIFICATION - FORM F Columns 7-14 (Filename) Enter a 1-8 character RPG II filename, beginning in column 7. Each name must be unique in the first six characters. Column 15 (File Type) I Input O Output U Update C Combined D Display Column 16 (File Designation) Blank Display or output file other than chained output file. P Primary S Secondary C Chained R Record address T Table or array D Demand Column 17 (End of File) Blank Program can end before end of file is reached on this file. E Program termination not possible before end of file on this file. If column 17 is blank or E for all files, every record of every input and update file is processed before the program terminates. An E in this column requires an I, U, or C in column 15, and a P, S, or R in column 16. Column 18 (Sequence) Blank Sequence checking not requested. A Records to be checked for ascending sequence. SUMMARY OF RPG II SPECIFICATIONS Page A-5 D Records to be checked for descending sequence. An entry is required here when matching fields are used. Column 18 applies to primary and secondary files; these files must conform to the same sequence specification. Column 19 (File Format) F Fixed length records All files are required to have fixed length records. Columns 20-23 (Block Length) 2-4096 Block length must be an even integral multiple of record length. Columns 24-27 (Record Length) Device Maximum Record Length ______ _______ ______ ______ TAPEn, DISK 4096 READ01 80 CONSOLE, MFCUn 96 PRINTER 132 Column 28 (Mode of Processing) Blank Sequential by key Consecutive R Random by relative record number Random by key By ADDROUT file Direct file load (Random load) This column applies only to file-structured devices. Column 29-30 (Length of Field or Record Address Field) Indexed Length of record key file ADDROUT Length of record file Maximum record key length is 64 characters. SUMMARY OF RPG II SPECIFICATIONS Page A-6 Column 31 (Record Address Type) Blank Sequential, direct, or consecutive A Indexed file, alphanumeric key I ADDROUT file or processed by ADDROUT file This column applied to input, update, or chained output files. Column 32 (File Organization or Additional I/O Area) I Indexed organization T ADDROUT file Blank Sequential or direct file; uses one I/O area for the file Columns 33-34 (Overflow Indicator) OA-OG, OV Overflow indicator used to condition records in the file Blank No overflow indicator is used Column 35-38 (Key Field Starting Location) For indexed files, enter the beginning position of the key field in the record. Column 39 (Extension Code) E The file described on this line is a table file, array file or record address file further described on extension specifications (Form E). L The File described on this line is a printer file further described on line counter specifications (Form L). Columns 40-46 (Device) Enter the device code for the input/output unit used by the file specified in columns 7-14, as follows: SUMMARY OF RPG II SPECIFICATIONS Page A-7 Actual Device RPG Device System Device Name ______ ______ ___ ______ ______ ______ ____ Multi-Function Card Unit 1 MFCU1 DSK:??????.MF1 Multi-Function Card Unit 2 MFCU2 DSK:??????.MF2 Card Reader READ01 CDR: Line Printer PRINTER LPT: Line Printer PRINTR LPT: Interactive Terminal CONSOLE TTY: Disk DISK DSK: Magnetic Tape Unit n TAPEn TAPEn: Columns 47-52 (Physical File Name) Specify a six character (alphanumeric with leading alphabetic) name which can be used as the system filename, under which the file is to be stored in the user's directory. The three character extension is defaulted as follows: Extension Type of File _________ ____ __ ____ MFn MFCU input hopper n file STn MFCU output stacker n IDA ISAM data file IDX ISAM index file RGA RPG II ADDROUT address file RGD Miscellaneous data file (anything other than above) Column 60-65 (Unused) Column 66 (File Addition) A New records will be added to the file. This position applies to sequential and indexed disk files. Column 70 (Tape Rewind) Specifies what is to be done to the tape after processing is done. Entry Action _____ ______ R Rewind tape at end of file. U Unload tape at end of file. N or Blank Leave tape at end of file. SUMMARY OF RPG II SPECIFICATIONS Page A-8 A.4 EXTENSION SPECIFICATIONS - FORM E Columns 11-18 (From Filename) 1. The filename of a pre-execution time table or array; 2. The filename of a record address file named on Form F. Columns 19-26 (To Filename) 1. The output file to which the compilation or pre-execution time table or array is to be written at job termination. Leave To Filename blank if the table or array is not written out. 2. The name of the file for which the From Filename record address file controls record selection. Columns 27-32 (Table or Array Name) Enter the name of a table or array used in the program. Table names start with the three characters TAB; array names must not start with TAB. If alternating tables or arrays are specified on this line, enter here the name of the table or array to which the first element of the input record(s) belongs. Columns 33-35 (Number of Entries per Record) Enter the number of table or array elements contained in each record. An entry must be made here for compilation and pre-execution time tables and arrays; these positions must be blank for execution time arrays. Columns 36-39 (Number of Entries per Table or Array) Enter here, right-justified, the maximum of entries in the table or array named in columns 27-32. When alternating format is used, a pair of elements is considered to be one entry. Columns 40-42 (Length of Entry) Enter, right-justified, the length of each table or array entry. The maximum length is 256 for alphanumeric entries and 15 for numeric entries. For packed binary tables and arrays, enter the number of bytes of storage required to represent the data in unpacked format. Column 43 (Field Type) Blank Alphanumeric or unpacked data in table or array SUMMARY OF RPG II SPECIFICATIONS Page A-9 Column 44 (Decimal Positions) Blank Alphanumeric table or array 0-9 Number of positions to be right of the decimal (0 of integers) Column 45 (Sequence) Blank No particular sequence A Ascending sequence D Descending sequence This position describes the sequence of data in a table or array. Column 45 must contain an entry if high or low look-up is to be used. Columns 46-57 (Alternate Table or Array) These positions, corresponding in definitions to columns 27-45, describe a table or array which is in alternating format with the table or array named in columns 27-32. Columns 58-74 (Comments) An entry in these columns is assumed by the compiler to be entirely commentary. SUMMARY OF RPG II SPECIFICATIONS Page A-10 A.5 LINE COUNTER SPECIFICATIONS - FORM L Columns 7-14 (Filename) Enter the name of a printer file for which you wish to specify a form size and overflow line. Columns 15-17 (Line Number - Number of Lines per Page) 1-112 Number of lines available for printing on the printer form Blank Standard value of 59 is assumed Columns 18-19 (Form Length) Enter FL to indicate that the previous entry is the forms length. Columns 20-22 (Line Number - Overflow Line) 1-112 Number of the overflow line Blank Standard value of 65 is assumed Columns 23-24 (Overflow Line) Enter OL to indicate that the previous entry is the overflow line. SUMMARY OF RPG II SPECIFICATIONS Page A-11 A.6 INPUT SPECIFICATIONS - FORM I Entries must be made on this form for every input and update file used in the program. Columns 7-14 (Filename) The filename of an input or update file. Columns 15-16 (Sequence) Enter a 2-digit number to assign a special sequence to record types in a file and to request that the record type sequence be checked by the program. Enter two alphabetic charaters to indicate that record type sequence is not checked. Alphabetic characters must be used for a chained file. Within a file, record types with an alphabetic sequence entry must be described before record types with a numeric sequence entry. Column 17 (Number) Blank Positions 15-16 contain alphabetic characters (record type sequence is not being checked) 1 Positions 15-16 contain numeric characters; only one record of this type is present in each N Positions 15-16 contain numeric characters; one or more records of this type can be present in the sequenced group Column 18 (Option) Blank Record type must be present O Optional. Record type may or may not be present This position is used when columns 15-16 contain a numeric entry. SUMMARY OF RPG II SPECIFICATIONS Page A-12 Columns 19-20 (Record Identifying Indicator, **) 01-99 Record identifying indicator L1-L9 Control level indicator used as a record identifying indicator when record type rather than control field signals start of a new control group LR Last record indicator H1-H9 Halt indicator used as a record identifying indicator when checking for a record type that causes an error condition ** Look-ahead fields Columns 21-41 (Record Identification Codes) This field is divided into three identical sub-fields. An AND relationship exists between the sub-fields. Columns 21-24 (Position) Blank A record identification code is not specified 1-4096 Character position of the record identification code Column 25 (Not) Blank Either columns 21-24 are blank or the character (or zone or digit) must be present to identify the record N the character, zone, or digit must not be present in the position being described Column 26 (C) C Entire character Additional record identification codes are specified as above in columns 27-32 and 33-41, if necessary. If more than three codes are needed to identify a record, enter AND in columns 14-16 of the next line and enter additional codes. Enter OR in columns 14-15 of the next line if an OR relationship exists between the codes. Up to 20 AND or OR lines in any combination can be specified for one record. Column 43 (Field Type) Blank Input field in unpacked decimal or alphanumeric format SUMMARY OF RPG II SPECIFICATIONS Page A-13 Columns 44-51 (Field Location) Enter two 1-4 digit numbers to identify the beginning of a field (From) and the end of a field (To) in the input record. These entries are identical for a one-position field. Column 52 (Decimal Position) Blank Alphanumeric field 0-9 The number of decimal positions in the numeric field named in positions 53-58 (zero for an integer) Columns 53-58 (Field Name) These positions name the field specified in columns 43-52. The following entries can be made here: A valid RPG II field name An array name element The special words PAGE, PAGE1, OR PAGE2 Columns 59-60 (Control Level) Blank The field being described is not a control field L1-L9 The level of the control field being defined These columns must be blank for chained or demand files. Columns 61-62 (Matching Fields) Enter a matching-level identifier (M1-M9) to indicate matching fields and sequence checking when you have two or more input or update files with matched fields. When you have just one input or update file with match fields this entry causes only sequence checking. Columns 63-64 (Field Record Relation) 01-99 Record identifying indicator assigned to a record type. L1-L9 Control level indicator previously used. MR Matching record indicator. U1-U8 External indicator previously set H1-H9 Halt indicator previously used. SUMMARY OF RPG II SPECIFICATIONS Page A-14 The following general rules apply to this entry: 1. All fields without field record relation should be specified before fields with field record relation 2. All fields with the same field record relation entry should be entered on consecutive lines. 3. All parts of a split control field must have the same field record relation entry and must be described on consecutive specification lines. Columns 65-70 (Field Indicators) 01-99 Field indicator H1-H9 Halt indicator (when checking for an error condition in the field data) When indicators are specified in these positions, RPG II make appropriate settings when the field is input. When the field is numeric, indicators are specified for positive, negative, and zero conditions in columns 65-66, and 69-70, respectively. One, two, or three indicators can be specified, but only the indicator which reflects the result of the test is set on; other specified indicators are set off. An alphanumeric field can be tested only for all blanks (columns 69-70). SUMMARY OF RPG II SPECIFICATIONS Page A-15 A.7 CALCULATION SPECIFICATIONS - FORM C Columns 7-8 (Control Level) Blank Operation done at detail time L0 Calculation is performed at total time (always on) L1-L9 Calculation operation is done when the appropriate control break occurs or the specified indicator is set on LR Calculation operation is done after the last record has been processed or after LR has been set on SR Calculation operation is part of a subroutine Calculation specifications must be ordered by the sequence listed above. AND or OR can be entered in these positions to indicate that indicators (columns 0-17) on the line are in an AND or OR relationship with indicators on the preceding line. Columns 9-17 (Indicators) Enter one to three indicators. Any RPG II indicators except 1P and LO can be used. Columns 9, 12, and 15 may contain blank or N. An AND relationship exists between indicators on a line. Additional lines may be used containing indicators in columns 9-17 which are in an AND or OR relationship with those on the first line by entering AND or OR in columns 7-8. Columns 18-27 (Factor 1) and Columns 33-42 (Factor 2) Factor 1 and Factor 2 may contain the following entries: 1. Name of any field that has been defined 2. Alphanumeric or numeric literal 3. Subroutine, table or array name, or array element 4. Date field name (UDATE, UMONTH, UDAY, UYEAR) 5. Special name (PAGE, PAGE1, OR PAGE2) 6. Label for a TAG, BEGSR, or ENDSR operation (Factor 1) or a label for a GOTO or EXSR operation (Factor 2) 7. Filename (first 6 characters) for a CHAIN, DEBUG, DSPLY, READ, or FORCE operation (Factor 2) SUMMARY OF RPG II SPECIFICATIONS Page A-16 Columns 28-32 (Operation) ADD EXCPT MOVE SUB BEGSR EXIT MOVEA TAG BITOF EXSR MOVEL TESTB BITON FORCE MULT TESTZ CHAIN GOTO MVR TIME COMP LOKUP READ XFOOT DEBUG MHHZO RLABL Z-ADD DIV MHLZO SETOF Z-SUB DSPLY MLHZO SETON ENDSR MLLZO SQRT Columns 43-48 (Result Field) Enter the name of the field, table, array, or array element that holds the result of the operation specified in positions 28-32. If the field named in Result Field has not been defined in extension, input, or previous calculation specifications, it must be defined by making entries in positions 49-52. Columns 49-51 (Field Length) Blank The result field entry was defined elsewhere 1-256 Result field length (right-justified) The maximum length of a numeric field is 15 digits; the maximum length of an alphanumeric field is 256 characters. Column 52 (Decimal Positions) Blank Field designated elsewhere or alphanumeric field 0-9 Number of decimal places in a numeric field Column 53 (Half Adjust) Blank Do not adjust the result field H Half adjust the result field Half adjusting can be specified only with arithmetic operations. Columns 54-59 (Resulting Indicators) Enter any of the following indicators: 01-99, H1-H9, L1-L9, LR, OA-OG, and OV. Columns 54-59 are used: 1. To test the value of the result field after an arithmetic operation. Enter up to 3 indicators to test for a positive result (columns 54-55), negative result (columns SUMMARY OF RPG II SPECIFICATIONS Page A-17 56-57), or a result of zero (columns 58-59). 2. To check the outcome of a CHAIN, LOKUP, COMP, or TESTB operation. With the CHAIN operation, an indicator specified in columns 54-55 is set on if the record is not found. With the LOKUP operation, up to 3 indicators are specified to indicate that Factor 2 is HIGH (columns 54-55). LOW (columns 56-57), or equal (columns 58-59). For the COMP operation, up to 3 indicators are specified to indicate that Factor 1 is greater than (columns 54-55), less than (columns 56-57), or equal to (columns 58-59) Factor 2. With the TESTB operation, resulting indicators have the following meanings: Positions 54-55: An indicator in these positions is turned on if each bit specified in Factor 2 is off in the Result Field. Positions 56-57: An indicator in these positions is turned on if two or more bits were tested and of mixed status (some bits on and some bits off). Positions 58-59: An indicator in these positions is turned on if each bit specified in Factor 2 is on in the Result Field. 3. To specify up to 3 indicators to SETON or SETOFF. 4. To indicate end of file for the READ operation code. An indicator specified in columns 58-59 is set on if an end-of-file condition is reached through a READ operation. Columns 60-74 (Comments) The compiler treats entries in these columns as entirely commentary. SUMMARY OF RPG II SPECIFICATIONS Page A-18 A.8 OUTPUT - FORMAT SPECIFICATIONS - FORM O Columns 7-14 (Filename) Enter a valid RPG II filename for each output and update file used. Each filename need be specified only once, on the first line describing that file. Columns 14-16 (AND/OR Relationship) Enter AND in positions 14-16 or OR in positions 14-15 if output records are in an AND or OR relationship. Column 15 (Type) H Heading record description D Detail record description T Total record description E Exception record description Columns 16-18 (Add a Record) Enter ADD in these columns if the record is added to an input, update or output disk file. An A must also be coded in position 66 of the File Description sheet for the file to which a record is added. Column 16 (Fetch Overflow) Blank Standard overflow procedures in effect F Fetch overflow routine used Columns 17-22 (Space/Skip) If these columns are blank, single spacing occurs after each line is printed. Spacing and skipping are not allowed on the printer/keyboard. Columns 17-18 (Space) Enter a number (1-3) to specify how many lines to skip before (column 17) and after (column 18) a line is printed. Columns 19-22 (Skip) Blank No skipping 01-99 Lines 1-99 A0-A9 Lines 100-109 B0-B9 Lines 110-112 Enter one of the two-character specifications listed above to indicate the next line to be printed. A skip before printing is specified in columns 19-20, a skip after, in columns 21-22. SUMMARY OF RPG II SPECIFICATIONS Page A-19 If the skip line number is less than the current line number, a skip to a new page occurs. Columns 23-31 (Output Indicators) Enter one to three indicators to condition the output record. Any RPG II indicators can be specified. An N may be entered in columns 23, 26, and 29 to indicate negative conditioning. An AND relationship exists between indicators on a line. Up to 20 additional sets of indicators can be specified following lines having AND in columns 14-16 or OR in columns 14-15. Columns 32-37 (Field Name) Enter one of the following to name every field written out: Any field name previously defined in this program. The special words, PAGE, PAGE1, PAGE2, *PLACE, UDATE UDAY, UMONTH, and UYEAR. A previously defined table name, array name, or array element. These positions must be blank if a constant is entered on positions 45-70 of the line. If an entry is made under field name, positions 7-22 must be blank. Column 38 (Edit Codes) Enter an edit code in position 38 when you want to: 1. Suppress leading zeros for a numeric field. 2. Omit a sign from the low order position of a numeric field. 3. Punctuate a numeric field without setting up your own edit word. A table summarizing the edit codes that can be used is printed above positions 45-70 on the Output-Format Sheet. Column 39 (Blank Option) Blank Field is not modified after output B Field is reset to blanks (if alphanumeric) or zeros (if numeric) after being output This column must be blank for look-ahead and update fields. If field name is a table name, the last table element retrieved is reset. Column 40-43 (End Position in Output Record) SUMMARY OF RPG II SPECIFICATIONS Page A-20 Positions 40-43 indicate the location on the output record of the field or constant written. Enter the number of the position occupied by the right-most character of the output field. The end position entry must not be greater than the record length. Column 44 (Packed or Binary Field) Blank Field is unpacked numeric or alphanumeric data Position 44 must be blank with *PLACE fields. Column 45-70 (Constant or Edit Word) Constant ________ 1. Field name (positions 32-37) must be blank. 2. A constant is enclosed in apostrophes. Enter the leading apostrophe in position 45. 3. An apostrophe is represented in a constant by two apostrophes. 4. Up to 24 characters of constant information can be placed in one line. Additional lines may be used, but each line must be treated as a separate line of constants. The end position of each line must appear in positions 40-43. Edit Word ____ ____ Enter any edit word to specify editing of numeric fields. Edit words must be enclosed by apostrophes. Constants are allowed within edit words. Edit words are not used with edit codes. However, when edit codes 1-4, A-D, and J-M are used, positions 45-47 may contain an * (to denote asterisk fill) or a $ (to denote a floating dollar sign). APPENDIX B REFERENCE TABLES Table B-1 Edit Codes Edit Decimal Sign for Negative Value Zero Code Commas Point No Sign CR - Suppress ____ ______ _____ __ ____ __ _ ________ 1 Yes Yes No Sign Yes 2 Yes Yes No Sign Yes 3 No Yes No Sign Yes 4 No Yes No Sign Yes A Yes Yes CR Yes B Yes Yes CR Yes C No Yes CR Yes D No Yes CR Yes J Yes Yes - Yes K Yes Yes - Yes L No Yes - Yes M No Yes - Yes X No No No Y No No Yes (1) Z No No Yes (1) The left-most zero, only, is suppressed. REFERENCE TABLES Page B-2 Table B-2 Operation Codes REFERENCE TABLES Page B-3 Table B-2 (cont'd) Operation Codes Table B-3 Summary of Program Indicators REFERENCE TABLES Page B-4 Table B-3 (Cont'd) Summary of Program Indicators REFERENCE TABLES Page B-5 Table B-4 Valid Indicators APPENDIX C RPG II CYCLE RPG II CYCLE Page C-2 RPG II CYCLE Page C-3 RPG II CYCLE Page C-4 For each record that is processed, the RPG II object program goes through the same general cycle of operations. After a record is read, there are two different instances in time when calculations are performed, and records written out. These instances are called total _____ time and detail time. During total time, all total calculation ____ ______ ____ operations (those conditioned by control level indicators in columns 7-8 of the Calculation Sheet) and all total output operations (those conditioned by control level indicators) are done. During detail time, all detail calculation operations (those not conditioned by control level indicators in columns 7-8) and all detail output operations are done. Total time includes steps 18 and 19 of the RPG II object program cycle; detail time includes steps 25 and 3 of the cycle. Total calculations are performed before the information on the record selected for processing is made available. Detail calculations are performed after the information on the selected reocrd is made available. The following discussion describes this concept in detail. Whenever a record is read, a check is made to determine if information in a control field (when one has been specified) is different from control field information on the previous record. A change in the control field information indicates that all records from a particular group have been read, and that a new group is starting. When all records from a group have been read (indicated by control level indicators turning on), operations may be done using information accumulated from all records in that group. At this time, all calculations conditioned by control indicators in columns 7-8 are done. Total output operations are performed immediately after all total calculations are completed. Remember that information on the record read at the beginning of the program cycle is not used in these operations; only information from records in the previous control group is used. Detail calculations (all calculations not conditioned by control level indicators in columns 7-8) occur after the information on the selected record has been made available. Detail calculations are used to calculate values needed each time a record is processed. They are also used to calculate totals for the current control group (if control fields are specified). Immediately after detail calculation operations are completed, detail output operations are performed. The specific steps taken in the program cycle are shown in Figure C-1. The item numbers in the following description refer to the numbers in the figure. A program cycle begins with step 3 and continues through step 25. 1. All data files to be used by the RPG II object program are opened; that is, they are prepared to be processed by the object program. Pre-execution time tables and arrays are loaded before the first program cycle. 2. The object program performs all output conditioned by the 1P indicator. This output is performed only once per job, and does not fall within the program cycle (steps 3 through 25). RPG II CYCLE Page C-5 3. The object program performs all specified heading and detail output operations whose conditions are satisfied. This includes specifications that are conditioned by the overflow indicator if the overflow indicator has been fetched. 4. The object program performs a test to determine if the overflow line was encountered during detail calculations in the previous cycle or when heading and detail output was written in the current cycle. If it was, the overflow indicators turns on. Otherwise, the indicator turns off, unless overflow was fetched in step 3. 5. The object program tests the halt indicators. If the halt indicators are off, the program branches to step 6. 5A. The execution of the program is stopped once for each halt indicator that is on. The operator can select one of three options: continue, controlled cancel, or immediate cancel. See Appendix E for an explanation of operator options. 5B. If the operator desires to continue the job, the program returns to step 5 to test for other halt indicators. If the operator selects one of the cancel options, a branch is taken to step 34. 6. All record identifying indicators and indicators 1P, L1-L9, an H1-H9 are turned off. 7. The program tests to see if the LR indicator is on. If it is, the program branches to step 26. 8. The program reads the next input record. At the beginning of processing, one record from each input file (except forced files and demand files) is read. If the file has look-ahead fields, it is read only on the first cycle. After that, records with look-ahead fields are identified only. 9. The program performs a test to determine of the record is an end-of-file record. If an end-of-file condition has occured, the program branches to step 11. 10. If an end of file has not occurred, the program performs a test to determine if the input records are in the sequence specified for them on the Input Sheet. If the sequence is incorrect, the program branches to step 32. The program also branches to step 32 if non-sequential input records are specified and the record cannot be identified. 11. If end-of-job conditions have been met, a branch to step 26 is taken. All files for which an E has been specified in columns 17 of the File Description Sheet must be at end of file. RPG II CYCLE Page C-6 12. When multiple input files are used, it is necessary to select the next record to process. A branch to step 27 is made. 13. If there is only one input file, no record selection is needed. A test is made to determine if sequence checking has been requested. If so, a branch is taken to step 30. 14. The record identifying indicator specified for the current record type turns on. Data from the current record type is not available for processing until step 24. 15. If the record contains control fields, the object program preforms a test to determine if a control break has occured ( the contents of the control field are not equal to the contents of a previously stored field). If a control break has not occurred or control fields are not specified, the program branches to step 17. 16. If a control break has occurred, the control level indicator reflecting this condition is turned on. All lower control level indicators are also turned on. 17. If this is the first program cycle or first control break, the program bypasses all total calculation and output operations and branches to step 20. 18. All calculations conditioned by control level indicators (columns 7-8 of calculation specifications) are performed and resulting indicators are turned on or off as speccified. If the LR indicator is on, calculations conditioned by LR are done after all other total calculations. Fetch overflow is performed if it is required by exception output. If the overflow line has been reached because of exception output, the overflow indicator is turned on. 19. All total output that is not conditioned by an overflow indicator is performed. The program performs a test to determine if an overflow condition has occurred. If an overflow condition has occurred at any time during this cycle, the overflow indicator turns on. If the LR indicator is on, output conditioned by LR is done after other total output. Fetch overflow is performed if required. 20. The program performs a test to determine is the last record (LR) indicator is on. If the indicator is on, the program branches to step 37. 21. The program performs a test to determine if any overflow indicators are on. If no overflow indicators are on, the program branches to step 23. 22. All output operations conditioned by a positive (no N preceding the indicator) overflow indicator are performed. RPG II CYCLE Page C-7 23. The MR indicator turns on if this is a multifile job and the record to be processed is a matching record. Otherwise MR turns off. 24. Field indicators are turned on or off as specified. Data from the last record read and from specified look-ahead fields is made available for processing. 25. Any calculations not conditioned by control level indicators (columns 7-8 of the calculation specifications) are performed, and resulting indicators are turned on or off as specified. Fetch overflow is performed if it is required by exception output. If the overflow line has been reached because of exception output, the overflow indicator is turned on. Processing continues with step 3. 26. The last record indicator (LR) and all control level indicators (L1-L9) are turned on and processing continues with step 18. 27. If a file has been forced, the next record in that file is selected for processing and a branch is taken to step 14. 28. If a record with no matching fields is found in a normal input file which is not at end of file, it is selected. 29. When matching fields are specified, the normal file with the highest priority matching record field is selected. If two or more files have the equal and highest priority matching record fields, the highest priority file of those is selected. (The primary file has the highest priority, the first specified secondary file is next, and so forth.) 30. The match field value is compared to the match field value of the last record. If it is in sequence, the record is accepted and processing continues with step 14. If the record is out of sequence, processing goes to step 31. 31. The execution of the program is stopped because a file with matching fields is out of sequence. The operator's option, indicated in step 33, is to bypass (read the next record from the same file) or cancel the job. 32. The execution of the program is stopped because of a record type sequence error or an unidentified record. 33. Step 33 tests the operator's decision either to bypass the record which causes the error condition (branch to step 4) or to cancel the job. 34. If the operator elects to terminate the job by means of a controlled cancel, steps 35 through 39 are performed. If the operator selects an immediate cancle, the job is terminated. RPG II CYCLE Page C-8 35. All operations conditioned by the LR indicator are done. 36. Same as 35. 37. The program writes out any tables or arrays for which a To Filename is specified on the Extension Sheet. 38. All files used by the program are closed (final termination functions are done). 39. End of job occurs. APPENDIX D CHARACTER SETS DECsystem-10 RPG II uses the sixbit subset of the ASCII character set for all internal calculation. While this works fine for most operations, it presents a problem when using the move and test zone operations. Because the DECsystem-10 does not normally work with the EBCDIC character set, nor with 8-bit bytes, the implementation of these operations is marginal at best. When a zone operation is encountered, the character that must have its zone moved/modified/examined is converted to an 8-bit EBCDIC character from its native SIXBIT. The zone operation is then carried out on this 8-bit quantity. When all operation have been completed on the character, it is converted back to SIXBIT. Because the conversion between character sets (shown in Table D-1) is not always totally accurate, due to fundamental differences between the different sets, the zone operations do not always give the same results that they would under a System/3 RPG II. It is recommended that the zone operations only be used as an aid in conversion of existing RPG II programs, and not be used in new ones. CHARACTER SETS Page D-2 Table D-1 shows ASCII and SIXBIT collating sequence and the conversions from ASCII to EBCDIC, and SIXBIT to EBCDIC. If the ASCII character does not convert to the same character in EBCDIC, the EBCDIC character is shown in parentheses next to the EBCDIC code. Note that the first and last 32 characters do not exist in SIXBIT. Also, characters in the first column (NULL, SOH, STX, etc.) are control characters, which are nonprinting. Table D-1 ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC CHARACTER SETS Page D-3 Table D-1 (cont'd) ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC CHARACTER SETS Page D-4 Table D-2 shows the conversion of ASCII code to SIXBIT code. The table does not show ASCII codes 000 through 037 because they all convert to SIXBIT 74 (\), except 22 (TAB) which converts to SIXBIT 00 (space). Table D-2 ASCII to SIXBIT Conversion CHARACTER SETS Page D-5 Table D-2 (cont'd) ASCII to SIXBIT Conversion CHARACTER SETS Page D-6 Table D-3 shows the EBCDIC collating sequence and the conversion from EBCDIC to ASCII. When conversion is from EBCDIC to SIXBIT, it is done as if the code was converted to ASCII, and then from ASCII to SIXBIT. Table D-3 EBCDIC Collating Sequence and Conversion to ASCII CHARACTER SETS Page D-7 Table D-3 (cont'd) EBCDIC Collating Sequence and Conversion to ASCII CHARACTER SETS Page D-8 Table D-3 (cont'd) EBCDIC Collating Sequence and Conversion to ASCII CHARACTER SETS Page D-9 Table D-3 (cont'd) EBCDIC Collating Sequence and Conversion to ASCII APPENDIX E RPG II HALT PROCEDURES When an error occurs during the execution of an RPG II program, a halt procedure is entered. The runtime system (RPGLIB) notifies the user of this by typing: %Entered Halt Procedure xx error-text Please select a halt option: Where xx is the two character halt code and error-text is a brief summary of the error. An optional third line tells which file is affected by the error. The halt codes have been chosen to be compatible with those given by IBM System-3 RPG II. In respone to the above message, the user should enter one of the follwing responses: CONTINUE Control is returned to the program, and processing continues. BYPASS The remainder of the program cycle is bypassed, and the next record is read. CONTROLLED CANCEL End-of-job operations (conditioned by an LR indicator) are done, tables are dumped and files are closed. IMMEDIATE CANCEL Files are closed and the job stops. DEFAULT Use the default operation (see table E-1). DDT DDT is entered if it was loaded during compiler generation. Same as DEFAULT. 0 Same as CONTINUE. 1 Same as BYPASS. 2 Same as CONTROLLED CANCEL. RPG II HALT PROCEDURES Page E-2 3 Same as IMMEDIATE CANCEL. 4 Same as DDT Table E-1 Halt Procedure Definitions Halt Display Error Description Options Default ____ _______ _____ ___________ _______ _______ H1 Indicator H1 is on 0234 none H2 Indicator H2 is on 0234 none H3 Indicator H3 is on 0234 none H4 Indicator H4 is on 0234 none H5 Indicator H5 is on 0234 none H6 Indicator H6 is on 0234 none H7 Indicator H7 is on 0234 none H8 Indicator H8 is on 0234 none H9 Indicator H9 is on 0234 none 11 Square root of a neg- 0234 2 ative number asked 12 Overflow during div- 0234 2 ide 13 Division by zero 0234 2 14 Zero, negative, or 0234 2 invalid array index 15 Table out of sequence 0234 2 16 No table data found 0234 2 17 Too much data for 0234 2 table 1A Exceeded specified 34 3 object core 1E End-of-file on 0234 2 demand file 1F Attempting to ac- 234 2 cess beyond extent RPG II HALT PROCEDURES Page E-3 Table E-1 (cont'd) Halt Procedure Definitions Halt Display Error Description Options Default ____ _______ _____ ___________ _______ _______ 1H Attempting to add 0234 2 duplicate key 1P 1P forms allignment 014 none 1U Record not found. 1234 2 Key not in index or record number too large. 1Y Invalid response 1234 2 to display 1b Prepare for 034 none table output J1 Record out of 1234 2 sequence L1 File out of match- 1234 2 ing sequence U1 Unidentified record 1234 2 APPENDIX F COMMAND STRINGS The general form of the command string is as follows: RELFIL,LSTFIL=SRC1,SRC2,... Table F-1 Explanation of Command String Terms Term Meaning ____ _______ RELFIL The file that is to hold the generated code. If no generated code is desired, the descriptor for RELFIL is replaced by a hyphen. Example: -,LSTFIL=SRC1,SRC2... LSTFIL The file that is to hold the generated listing. If no listing is desired, the descriptor for LSTFIL is replaced by a hyphen. Example: RELFIL,-=SRC1,SRC2,... SRC1,SRC2 The source files required to from one input program. Each file description has the following form: DEVICE:FILE.TYP[PROJECT,PROGRAMMER]/SWITCH Certain default assignments are made by the compiler whenever terms are omitted from the command strings or file descriptions. 1. If the device is omitted in any output file description, DSK is assumed. If the device is omitted in an input file description, either the preceding device or DSK (if no preceding device was specified) is assumed. 2. If the filename for RELFIL and/or LSTFIL is omitted, the filename of the first source file is used. COMMAND STRINGS Page F-2 3. If the file type is omitted from RELFIL, .REL is assumed; if it is omitted from LSTFIL, .LST is assumed. If the type is omitted from the source file desriptor, the compiler looks in the file area for the named file with the type .RPG. If that file is not found, the compiler looks for the named file without a type. 4. If the [PROJECT,PROGRAMMER] option is omitted on any file, the users directory is used. Table F-2 Explanation of File Description Terms Term Meaning ____ _______ DEVICE The name of a device. The name is composed of 6 or fewer letters and/or digits. FILE The name of a file. The name is composed of 6 or fewer letters and/or digits. TYP The file type (extension). It is composed of 3 or fewer letters and/or digits. PROJECT A user's project number. PROGRAMMER A user's programmer number. SWITCH Any of the switches shown in Table F-3. Table F-3 RPG II Switch Summary Switch Action by Compiler ______ ______ __ ________ A Allows the listing of the code generated (the source program is listed whenever a listing file is specified). E Checks the program for errors but does not generate code. H Types a description of RPG II command strings and lists the switches. When this switch is used, the other parts of the command string are ignored. N The source errors are not typed on the user's terminal. W Rewinds the device before reading or writing. (This is valid for magnetic tape only.) APPENDIX G RPG II STANDARD CALLING SEQUENCE Subroutines written in FORTRAN or MACRO may be called from an RPG II program by use of the EXIT and RLABL operations. These operations generate the standard calling sequence used by FORTRAN, MACRO, and COBOL programs. G.1 EXIT OPERATION The rules for use of the EXIT operation in RPG II calculation specification are as follows: Columns Entry _______ _____ Operation EXIT Factor 1 Blank Factor 2 The name of the subroutine to which control is to be passed. Result Field Blank Resulting Indicators Blank The EXIT operation can be conditioned by control level entries (columns 7-8) and indicator entries (columns 9-17). If not conditioned by control level entries, the EXIT operation occurs at detail calculation time. G.2 RLABL SPECIFICATION Through the RLABL operation, a field, table, or array defined in the RPG II program can be referenced by the subroutine to which the EXIT operation gives control. The rules for use of RLABL in RPG II programs are as follows: RPG II STANDARD CALLING SEQUENCE Page G-2 Columns Entry _______ _____ Operation RLABL Result Field Field, table or array name Field Length Length of field (optional) Decimal Positions Decimal indication (optional) The RLABL specifications must immediately follow the EXIT specifications for the subroutine which references the RPG II field. A name specified by a TAG, BEGSR, or ENDSR specification cannot be used in an RLABL specification. Page Index-1 INDEX *place . . . . . . . . . . . . . . 10-10 1p . . . . . . . . . . . . . . . . 4-2 Add operation . . . . . . . . . . 9-12, 9-14 Alphabetic characters . . . . . . 1-7 Alphanumeric characters . . . . . 1-7 Alphanumeric fields . . . . . . . 1-7 Arithmetic operations . . . . . . 9-12 Ascii . . . . . . . . . . . . . . 1-7, D-1 Ascii files . . . . . . . . . . . 5-8, 5-16 Begsr operation . . . . . . . . . 9-21 Bitof operation . . . . . . . . . 9-18 Biton operation . . . . . . . . . 9-18 Block length . . . . . . . . . . . 5-7 Blocking factor . . . . . . . . . 5-7 Calculation factors . . . . . . . 9-7 Calculations operations add . . . . . . . . . . . . . . 9-12, 9-14 begsr . . . . . . . . . . . . . 9-21 bitof . . . . . . . . . . . . . 9-18 biton . . . . . . . . . . . . . 9-18 chain . . . . . . . . . . . . . 5-5, 5-11, 9-29 comp . . . . . . . . . . . . . . 9-13 debug . . . . . . . . . . . . . 4-1, 9-30 div . . . . . . . . . . . . . . 9-12, 9-14, 9-34 dsply . . . . . . . . . . . . . 5-3, 9-28 endsr . . . . . . . . . . . . . 9-21 excpt . . . . . . . . . . . . . 9-27 exit . . . . . . . . . . . . . . 9-21, G-1 exsr . . . . . . . . . . . . . . 9-20 force . . . . . . . . . . . . . 9-27 goto . . . . . . . . . . . . . . 9-20 lokup . . . . . . . . . . . . . 9-22, 9-24 mhhzo . . . . . . . . . . . . . 9-13 mhlzo . . . . . . . . . . . . . 9-13 mlhzo . . . . . . . . . . . . . 9-13 mllzo . . . . . . . . . . . . . 9-13 move . . . . . . . . . . . . . . 9-12, 9-16 movea . . . . . . . . . . . . . 9-12, 9-16 movel . . . . . . . . . . . . . 9-12, 9-16 mult . . . . . . . . . . . . . . 9-12, 9-14 mvr . . . . . . . . . . . . . . 9-12, 9-14, 9-34 read . . . . . . . . . . . . . . 5-6, 9-28 rlabl . . . . . . . . . . . . . 9-21, G-1 setof . . . . . . . . . . . . . 8-9, 9-22 seton . . . . . . . . . . . . . 9-3, 9-21 sqrt . . . . . . . . . . . . . . 9-12, 9-14 sub . . . . . . . . . . . . . . 9-12, 9-14 tag . . . . . . . . . . . . . . 9-20 testb . . . . . . . . . . . . . 9-18 testz . . . . . . . . . . . . . 9-19 time . . . . . . . . . . . . . . 9-32 xfoot . . . . . . . . . . . . . 9-15 z-add . . . . . . . . . . . . . 9-12, 9-14 z-sub . . . . . . . . . . . . . 9-12, 9-14 Chain operation . . . . . . . . . 5-5, 5-11, 9-29 Character sets . . . . . . . . . . D-1 Character zones . . . . . . . . . D-1 Command strings . . . . . . . . . F-1 Comp operation . . . . . . . . . . 9-13 Compilation time . . . . . . . . . 1-7 Console . . . . . . . . . . . . . 5-3 Continuation lines . . . . . . . . 5-16 Control levels . . . . . . . . . . 9-3 Control specifications . . . . . . 4-1 Date field names . . . . . . . . . 9-9 Debug operation . . . . . . . . . 4-1 Demand files . . . . . . . . . . . 9-28 Detail time . . . . . . . . . . . 1-8 Device code . . . . . . . . . . . 5-14 Direct load . . . . . . . . . . . 5-4, 9-29 Div operation . . . . . . . . . . 9-12, 9-14 Dsply operation . . . . . . . . . 5-3, 9-28 Ebcdic . . . . . . . . . . . . . . 1-8, D-1 Edit codes . . . . . . . . . . . . 10-11 End of file processing . . . . . . 5-6 Endsr operation . . . . . . . . . 9-21 Entries per record . . . . . . . . 6-3 Excpt operation . . . . . . . . . 9-27 Execution time . . . . . . . . . . 1-8 Exit operation . . . . . . . . . . 9-21, G-1 Exsr operation . . . . . . . . . . 9-20 Extension code . . . . . . . . . . 5-13 Extensions . . . . . . . . . . . . 5-15, A-7 Fetch overflow . . . . . . . . . . 10-4 Field indicators . . . . . . . . . 8-13 Field record relation . . . . . . 8-11 Field type alphanumeric . . . . . . . . . . 1-7 numeric . . . . . . . . . . . . 1-8 File description . . . . . . . . . 5-1 File designation chained . . . . . . . . . . . . 5-5 demand . . . . . . . . . . . . . 5-6 primary . . . . . . . . . . . . 5-4 record address . . . . . . . . . 5-5 secondary . . . . . . . . . . . 5-4 table or array . . . . . . . . . 5-5 File format . . . . . . . . . . . 5-7 File organization . . . . . . . . 5-12 File processing direct . . . . . . . . . . . . . 12-13 indexed . . . . . . . . . . . . 12-13 sequential . . . . . . . . . . . 12-1 File type combined . . . . . . . . . . . . 5-3 display . . . . . . . . . . . . 5-3 input . . . . . . . . . . . . . 5-2 output . . . . . . . . . . . . . 5-2 update . . . . . . . . . . . . . 5-3 Filename extensions . . . . . . . 5-15, A-7 Force operation . . . . . . . . . 9-27 Form length . . . . . . . . . . . 7-2 Forms positioning . . . . . . . . 4-2 From filename . . . . . . . . . . 6-1 Goto operation . . . . . . . . . . 9-20 H card . . . . . . . . . . . . . . 4-1 Half-adjust . . . . . . . . . . . 9-34 Halt procedures . . . . . . . . . E-1 Indicators control level . . . . . . . . . 8-9, 8-11, 9-3 to 9-4, 9-21 external . . . . . . . . . . . . 8-11, 9-4 field . . . . . . . . . . . . . 8-13 halt . . . . . . . . . . . . . . 8-11, 8-13, 9-4, 9-21 last record . . . . . . . . . . 9-4, 9-21 matching record . . . . . . . . 8-10 to 8-11, 9-4, 12-3 mr . . . . . . . . . . . . . . . 8-10 to 8-11 output . . . . . . . . . . . . . 10-8 overflow . . . . . . . . . . . . 9-4 record identifying . . . . . . . 8-3, 8-5, 8-11, 8-13, 9-4, 9-22 resulting . . . . . . . . . . . 9-4, 9-34 Isam processing . . . . . . . . . 12-13 Key field . . . . . . . . . . . . 5-11, 5-13 Lines per page . . . . . . . . . . 7-1 default . . . . . . . . . . . . 7-1 Lokup operation . . . . . . . . . 9-22, 9-24 Look-ahead fields . . . . . . . . 8-3 to 8-4, 12-8 Matching fields . . . . . . . . . 8-10 Matching records . . . . . . . . . 12-2 Mfcu . . . . . . . . . . . . . . . 5-3 Mhhzo operation . . . . . . . . . 9-13 Mhlzo operation . . . . . . . . . 9-13 Mlhzo operation . . . . . . . . . 9-13 Mllzo operation . . . . . . . . . 9-13 Mode of processing by addrout . . . . . . . . . . . 5-10 consecutive . . . . . . . . . . 5-10 random . . . . . . . . . . . . . 5-11 sequential by key . . . . . . . 5-10 Move operation . . . . . . . . . . 9-12, 9-16 Movea operation . . . . . . . . . 9-12, 9-16 Movel operation . . . . . . . . . 9-12, 9-16 Mult operation . . . . . . . . . . 9-12, 9-14 Multi-file processing . . . . . . 5-4, 5-6, 9-27, 12-2 Mvr operation . . . . . . . . . . 9-12, 9-14 Numeric characters . . . . . . . . 1-8 Numeric field . . . . . . . . . . 1-8 Overflow indicator . . . . . . . . 5-12 Overflow line . . . . . . . . . . 7-2 default . . . . . . . . . . . . 7-1 Overflow line number . . . . . . . 7-2 Pre-execution time . . . . . . . . 1-8 Program identification . . . . . . 3-3 Random files . . . . . . . . . . . 9-29 Read operation . . . . . . . . . . 5-6, 9-28 Record address field . . . . . . . 5-11 Record address type . . . . . . . 5-11 Record key . . . . . . . . . . . . 1-8 Record length . . . . . . . . . . 5-8 Result field . . . . . . . . . . . 9-32 Rlabl operation . . . . . . . . . 9-21, G-1 Sequence checking . . . . . . . . 5-7 Setof operation . . . . . . . . . 8-9, 9-22 Seton operation . . . . . . . . . 9-3, 9-21 Single file processing . . . . . . 5-6 Sixbit . . . . . . . . . . . . . . D-1 Special characters . . . . . . . . 1-8 Special words page . . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10 page1 . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10 page2 . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10 udate . . . . . . . . . . . . . 9-7, 9-9, 10-11 uday . . . . . . . . . . . . . . 9-7, 9-9, 10-11 umonth . . . . . . . . . . . . . 9-7, 9-9, 10-11 uyear . . . . . . . . . . . . . 9-7, 9-9, 10-11 Sqrt operation . . . . . . . . . . 9-12, 9-14 Sub operation . . . . . . . . . . 9-12, 9-14 Subroutines . . . . . . . . . . . 9-3 Tables and arrays . . . . . . . . 11-1 advantages . . . . . . . . . . . 11-1 alternate . . . . . . . . . . . 6-7 compile time . . . . . . . . . . 11-5 execution time . . . . . . . . . 11-6 files . . . . . . . . . . . . . 5-5 forming . . . . . . . . . . . . 11-5 full . . . . . . . . . . . . . . 11-5 naming . . . . . . . . . . . . . 11-1 output . . . . . . . . . . . . . 5-5 pre-execution time . . . . . . . 11-6 sequence . . . . . . . . . . . . 6-6 short . . . . . . . . . . . . . 11-5 Tag operation . . . . . . . . . . 9-20 Tape rewind . . . . . . . . . . . 5-17 Testb operation . . . . . . . . . 9-18 Testz operation . . . . . . . . . 9-19 Time operation . . . . . . . . . . 9-32 To filename . . . . . . . . . . . 6-2 Total time . . . . . . . . . . . . 1-8 Xfoot operation . . . . . . . . . 9-15 Z-add operation . . . . . . . . . 9-12, 9-14 Z-sub operation . . . . . . . . . 9-12, 9-14