In this lesson we dig into one of the most fundamental parts of ILE RPG: symbolic names and the reserved words that have special meaning to the compiler. Get these rules right and your code will compile cleanly, stay readable, and avoid those mysterious "name already defined" errors that waste hours of your time.
Valid Character Set for RPG ILE
RPG IV lets you use these characters in symbolic names:
- Letters: A through Z (the compiler accepts lowercase but converts everything to uppercase internally)
- Numbers: 0 through 9
- Special characters: + - * , . ' & / $ # : @ _ > < = ( ) %
- Blank (space)
On some code pages the characters $, #, and @ look slightly different. Check the IBM i Information Center globalization section if you ever run into strange display issues.
What Is a Symbolic Name?
A symbolic name is simply a name you create to identify something in your program. RPGLE uses symbolic names for:
- Arrays
- Conditional compile names
- Data structures
- EXCEPT output records
- Fields
- KLIST names
- Labels (TAG / ENDSR)
- Named constants
- PLIST names
- Prototype names
- Record names
- Subroutine names
- Table names
General Rules for All Symbolic Names
Follow these rules unless a specific exception is listed later:
- The first character must be alphabetic (including $, #, or @).
- Remaining characters can be alphabetic, numeric, or underscore (_).
- The name must be left-adjusted in the specification entry (except in definition specs, keyword fields, and extended factor 2 where it can float).
- A symbolic name cannot be an RPGLE reserved word.
- Length: 1 to 4096 characters. In practice, definition and procedure specification name fields hold up to 15 characters; longer names use continuation lines.
- The name must be unique within the procedure where it is defined.
Special Rules for Specific Symbolic Names
Array Names
An array name in a standalone field cannot start with the letters TAB. However, arrays defined inside a data structure with the DIM keyword (or as prototyped parameters) can start with TAB.
Conditional Compile Names
These names have nothing to do with other symbolic names in your program. Example: You can have a file called MYFILE and still use /DEFINE MYFILE for conditional compilation. They are completely separate. Maximum length is 50 characters.
Data Structure Names
A data structure is treated internally as one big character field.
EXCEPT Names
The same EXCEPT name can be used on multiple output records. This is the only name type that allows duplicates.
Field Names
- You can define the same field name more than once only if every definition has the exact same type, length, and decimal positions. All references point to the same storage.
- In a data structure, a subfield name can appear only once unless the DS is qualified (QUALIFIED or LIKEDS). When qualified, you must use the format dsname.subfieldname.
- A subfield name cannot be used as the result field on an *ENTRY PLIST parameter.
KLIST Names
Used to define a list of key fields for older keyed access.
Labels
Used with TAG and ENDSR operations to mark a location in the code.
PLIST Names
Used for parameter lists (mostly legacy).
Prototype Names
The name you give a prototype. This is the name you use when you call the procedure or program.
Record Names
- If the file uses QUALIFIED or LIKEFILE, you must qualify the record name: FILENAME.FMTNAME.
- Otherwise use the format name directly.
- Record names must be unique within the file and within the scope (global or local to a subprocedure).
Subroutine Names
Defined in Factor 1 of the BEGSR operation.
Table (File) Names
- Must be 3 to 10 characters long.
- Must start with the letters TAB.
- Cannot be defined inside a subprocedure.
RPG IV Words with Special Functions (Reserved Words)
These words have built-in meaning to the compiler. Never use them as your own field, array, or subroutine names.
User Date Special Words: These give you access to the job date or parts of it:UDATE *DATE UMONTH *MONTH UYEAR *YEAR UDAY *DAY
Page Numbering Words: PAGE PAGE1 through PAGE7
Figurative Constants: (implied literals)*BLANK / *BLANKS*ZERO / *ZEROS*HIVAL *LOVAL *NULL *ON *OFF*ALLX'x1..' *ALLG'oK1K2i' *ALL'X..'
File Positioning: *START *END
Indicator Access: *IN *INxx
Date and Time Format Words: *CDMY *CMDY *CYMD *DMY *EUR *HMS *ISO *JIS *JOB *JOBRUN *JUL *LONGJUL *MDY *SYS *USA *YMD
Translation and Other Special Words: *ALTSEQ *EQUATE *FILE *FTRANS *PLACE *ALL
Expression Operators: AND NOT OR (NOT can only be used inside expressions)
Parameter Passing Options: *NOPASS *OMIT *RIGHTADJ *STRING *TRIM *VARSIZE *NULLIND *EXACT *CONVERT
XML-SAX Event Handling Words: XML_ATTR_UCS2_REF XML_ATTR_NAME ... (and all the other XML_xxx words listed in the reference)