The Modern RPG IV Language

The CRTBNDRPG command performs a single source-file-to-program compilation. It checks the syntax source file for errors and, upon successful syntax checking, it generates a *MODULE object. The command automatically evokes the CRTPGM command upon successful *MODULE generation. After a successful bind, a *PGM is generated. This *PGM object can be called through the conventional program interfaces, such as the CL CALL command of the OS/400 operating system.

Note that the actual native AS/400 interface displays full-text descriptions for command parameters. These keywords are the CL command interface to the various parameters. For example, the CL command prompter displays "Program ......" for the program name parameter, but the keyword for this parameter is PGM. The keyword form of the parameter name is used in this appendix.

PGM (Program Name)

The name of the program and library of the program (*PGM) being created. The program name and library name must conform to AS/400 naming conventions. If no library is specified, the created program is stored in the current library.

• *CTLSPEC The name of the program object is retrieved from the DFTNAME keyword of the header specification of the source file member.

• program-name The name of the program object to create. The special value *CTLSPEC can be specified. When *CTLSPEC is specified, the program name is retrieved from the DFTNAME keyword of the header specification of the source file.

• library-name The name of the library where the created program is stored. The special value *CURLIB can be specified. When *CURLIB is specified, the program is stored in the library assigned to the current library position in the job's library list. This library can be established with the CHGCURLIB or CHGLIBL commands.

SRCFILE (Source File Name)

Specify the name of the source file that contains the RPG IV source member being compiled. A fully qualified source file name can be specified. The default source file name is QRPGLESRC. Other names, such as QRPGSRC, also are used.

If a program-development environment is being used, such as Program Development Manager (PDM), the source file name is generally established based on the source file being worked with.

SRCMBR (Source File Member)

Specify the name of the member of the file specified on the SRCFILE parameter. The member name is where the RPG IV source code resides.

• *PGM The special value *PGM can be specified. This indicates that the name of the source member is derived from the PGM parameter. If *PGM is specified and PGM(*CTLSPEC) is also specified, the generated program name is RPGPGM.

• source-file-member-name Specify the name of the source file member containing the RPG IV source code to be compiled.

GENLVL (Generation Severity)

Specify the maximum error severity that is acceptable while still generating the program object. The program is created only when any errors generated are less than or equal to the generation severity.

• 10 Severity 10 creates programs when the error severity level is 10 or less. Severity 11 or higher messages cause the compile to fail.

• severity-level-value Specify a severity between 0 and 20. In most cases the default of 10 is sufficient. In some situations, however, a severity of 20 is necessary. Severity higher than 20 with program creation is not supported under this version of the RPG IV compiler.

TEXT

Specify some descriptive text for the program being compiled. This text is embedded into the program object, and is visible through several system interfaces, such as DSPOBJD, WRKOBJ, DSPPGM, and PDM.

• *SRCMBRTXT The special value *SRCMBRTXT can be specified to cause the text description for the program to be retrieved from the text description of the source-file member being compiled.

• *BLANK Specify *BLANK when no text description should be embedded into the compiled program.

• 'description' Specify the text description that is embedded within the compiled program object. Up to 50 characters can be specified. The description is normally enclosed in single quotes (i.e., apostrophes). However, the apostrophes are not part of the text description.

DFTACTGRP (Default Activation Group)

Specify *YES for this option when the program must be run in the default activation group. The default activation group name is *DFTACTGRP. DFTACTGRP(*NO) is recommended for RPG IV programs that take advantage of procedures. Activation groups are an integrated language environment (ILE) construct and are beyond the scope of this appendix.

*YES Specify DFTACTGRP(*YES) to force the program to run in the default activation group. When DFTACTGRP(*YES) is specified, the ACTGRP parameter is ignored.

Specifying DFTACTGRP(*YES) causes the RPG IV program to behave like traditional RPG III program objects. The override scoping, open scoping, and resource use are the same as that of RPG III programs. This option allows programmers to plug-in replacements for legacy RPG III and RPG II applications with RPG IV without concern for the common runtime environment built around the newer AS/400 compilers.

Stand-alone RPG IV programs without procedure calls can typically use this option without impacting performance or runtime. There are several limitations in this configuration, however. These limitations may cause the experienced RPG IV programmer to choose DFTACTGRP(*NO). The following restrictions are placed on an RPG IV program when DFTACTGRP(*YES) is specified:

• ILE static binding is not available when a program is created with DFTACTGRP(*YES). This means the CALLB and CALLP operations are not supported.

• The BNDDIR parameter cannot be specified. Hence, binding directories are not supported.

• User-written functions, commonly known as procedures, cannot be used. Procedures are statically bound and, because static binding is not supported, procedures cannot be called.

DFTACTGRP(*YES) is useful when moving an application to the RPG IV environment. By using the CVTRPGSRC command to convert RPG III source code to its equivalent RPG IV source code, the CRTBNDRPG with DFTACTGRP(*YES) specified is one method to do a plug-in replacement of the original program.

*NO Specify DFTACTGRP(*NO) for most RPG IV compiles. When *NO is specified, the program runs in the activation group specified on the ACTGRP parameter.

DFTACTGRP(*NO) is useful when you intend to take advantage of advanced RPG IV features, such as procedure calls or ILE features such as named activation groups, calling service programs, or binding directories.

BNDDIR (Binding Directory)

Specify the name of one or more binding directories. These directories are used to locate *MODULE and *SRVPGM objects for binding with the compiled program. Several binding directory names can be specified.

• *NONE Specify *NONE when no binding directories are needed.

• binding-directory-name Specify the fully qualified name of one or more binding directories required by the program. Binding directories contain references to external symbols, service programs, and procedures.

ACTGRP (Activation Group)

Specify the ACTGRP parameter to indicate the activation group in which this program runs.

• QILE Specify QILE (the default) as the name of the activation group. QILE is a normal activation group and it is typically used when DFTACTGRP(*NO) is required. The QILE name provides a suggestion for a default named activation group. The default name could be any name, but QILE is the name shipped with the RPG IV compiler.

• *NEW Specify *NEW to cause OS/400 to generate a temporary activation group name. Use this option when the program should run in its own activation group.

• *CALLER Specify *CALLER to cause the program to run in the same activation group as the program that evoked it. *CALLER should not be used when the caller's activation group is the default activation group.

• activation-group-name Specify a unique name for the activation group to be created when this program is called. Suggested names for activation groups centers around the application. For example, all the programs for the accounts receivable application might be associated with the ACCTREC activation group. Payroll and human resources might be associated with a PAYROLL activation group. The name of the activation group is only important to the programmer.

OPTION

Specify the compile listing and object generation options to use when the source is compiled. Specify one or more of the following options in any order. Separate the individual options with one or more blanks or use the command prompter. When multiple or contradictory options are specified, the last option specified is used for the compile.

• *XREF Produce a name (fields, files, data structure, tokens, etc.) to the line number, cross-reference listing.

• *NOXREF No cross-reference listing is produced.

• *GEN Create the program object if the program compiles successfully. A program compiles successfully when the highest message severity level does not exceed the GENLVL option.

• *NOGEN Perform preprocessing and syntax checking only. Essentially, this option does everything except generate the compiled program. When only checking for syntax errors or producing a cross-reference listing, OPTION(*NOGEN) substantially improves the amount of time required to generate the desired output. No program object is created.

• *SECLVL The second-level message text is generated along with the message text description. The second-level message text is normally much more descriptive than the standard first-level message text that normally appears on the compiler listing.

• *NOSECLVL Second-level message text is not generated.

• *SHOWCPY The source code of all /COPY source-file members, included in place, on the compiler listing.

• *NOSHOWCPY /COPY compiler directives are printed as is, and are not included on the compiler listing.

• *EXPDDS The input and output specifications of externally described files is generated and included on the compiler listing.

• *NOEXPDDS The input and output specifications of externally described files are not included on the compiler listing.

• *EXT Generate a list of external references (procedures and field names) on the compile listing.

• *NOEXT Don't generate a list of external references (procedures and field names) on the compile listing.

• *NOEVENTF The events file is not generated.

• *EVENTF The events files is generated. The events file contains information, useful to client-server development environments, such as IBM CODE/400 (OS/2) and COZZI CodeStudio (Windows). The events file name is EVFEVENT. The member name is the same as the name specified on the PGM parameter. It is stored in the same library as the program object.

• *EXT External fields and procedures are included on the compiler listing.

• *NOEXT External fields and procedures are not included on the compiler listing.

DBGVIEW (Debug View Level)

Specify the level of debugging that will be available to debug the compiled program.

• *STMT Specify *STMT to allow debugging at the source-statement, line-number level. This view does not support the full-screen, source-level debugger of the AS/400.

• *SOURCE Specify *SOURCE to generate a source view for debugging the compiled program. When debugging the program, the source-level debugger uses the actual source file member specified on the SRCFILE and SRCMBR parameters.

• *COPY Specify *COPY to generate a source view for debugging that includes in-line /COPY directive source. The source code of each /COPY source member is inserted into the debug view. Specifying *COPY also implies the *SOURCE view.

• *LIST Specify *LIST to generate a listing of the compiled source-file member that is used by the debugger. The listing is embedded into the compiled program object and used by the source-level debugger when the program is debugged. This is the most common and useful debugging option. When used in conjunction with the OPTION(*NODEBUGIO) option on the program's source header specification, DBGVIEW(*LIST) provides the highest level of debugging capability.

• *ALL Specify *ALL to generate all available debug views.

• *NONE Specify *NONE to avoid generating any debug views. This option is normally used for a production release of the program. Debug views add unnecessary program-size overhead, and can cause security problems where source code should not be available.

OUTPUT (Compiler Output Listing)

Specify the output listing option to generate a listing or avoid generating a listing.

• *PRINT Specify *PRINT to have the compiler print the compiler listing.

• *NONE Specify *NONE to avoid having the compiler listing generated.

OPTIMIZE (Optimization Level)

Specify the level of optimization to be performed on the program. Optimization on the AS/400 is generally technologically superior to other compilers. The overall throughput of the program, however, is not always dependent on the level of optimization. Actually, for general-purpose business applications, optimizing RPG IV programs is only marginally affective.

• *NONE Specify *NONE to avoid any level of optimization. Avoiding optimization allows for a faster compile than optimizing. Also, OPTIMIZE(*NONE) should be specified when a debug view has been specified during development.

• *BASIC Specify *BASIC to perform some basic level of optimization on the generated program. This level of optimization is performed much more quickly than OPTIMIZE(*FULL). In addition, debugging can be performed on the program, as with OPTIMIZE(*NONE). A program variable, however, cannot be modified during debug when *BASIC is specified.

• *FULL Specify *FULL when a program is ready to be placed into the production environment. Fully optimized code takes the longest time to generate. Programs can still be debugged if necessary. However, the content of variables is not reliable under full optimization.

INDENT (Indented Compiler Listing)

Specify the INDENT option to control whether structured operations are printed in an indented source-listing format. The character used to highlight the indent levels also is specified on this parameter.

• *NONE Specify *NONE to have the normal (nonindented) compiler listing generated.

• 'character-value' Specify a character string (up to two characters) that is used to generate the indented compiler listing. By specifying these characters, an indented compiler listing is generated. The characters connect the beginning and ending lines of the structured operations, such as IF, DO, and SELECT-WHEN.

CVTOPT (Data Type Conversion Options)

Specify the CVTOPT option to control how certain data types of externally described files are handled by the compiled program. Each option converts its corresponding data type to a fixed-length character field.

• *NONE Specify *NONE for normal processing. No data type conversion is generated.

• *DATETIME Specify *DATETIME to convert externally described date, time, and timestamp database fields to fixed-length character fields.

• *GRAPHIC Specify *GRAPHIC to convert double-byte character set (DBCS) graphic data types to fixed-length character fields.

• *VARCHAR Specify *VARCHAR to convert variable-length character data types to fixed-length character fields.

• *VARGRAPHIC Specify *VARGRAPHIC to convert variable-length double-byte character set (DBCS) graphic data types to fixed-length character fields.

SRTSEQ (Sort Sequence Table)

Specify the SRTSEQ option to control the sort sequence table that is used in the RPG IV source program.

• *HEX No sort sequence table is used.

• *JOB Specify *JOB to retrieve the SRTSEQ setting from the job running when the program is compiled.

• *JOBRUN Specify *JOBRUN to retrieve the SRTSEQ setting from the job runtime environment when the program is run.

• *LANGIDUNQ Specify *LANGIDUNQ to use a unique weighted table, based on the language ID specified for the LANGID parameter.

• *LANGIDSHR Specify *LANGIDSHR to use a shared weighted table, based on the language ID specified for the LANGID parameter.

• sort-table-name Specify the fully qualified sort sequence table name.

LANGID (Language Identifier)

Use the LANGID parameter to specify the language identifier used when the sort sequence (SRTSEQ) parameter is *LANGIDUNQ or *LANGIDSHR. The LANGID parameter is used with the SRTSEQ parameter to specify the sort sequence table.

• *JOBRUN Specify *JOBRUN to retrieve the language identifier setting from the job runtime environment when the program is run.

• *JOB Specify *JOB to retrieve the language identifier setting from the job running when the program is compiled.

• language-identifier Specify the language identifier for the program.

REPLACE (Replace Existing Program upon Successful Compile)

Specify the REPLACE option to have the compiler replace an existing compiled program after this program compiles successfully.

• *YES Specify *YES to have an existing program (of the same name as the program being compiled) replaced with the newly compiled program. The existing program is moved to the QRPLOBJ (Replace Object) library and renamed. The renamed program's text description identifies the original program name.

• *NO Specify *NO to terminate the compilation if a program already exists with the same name and library as the program being compiled.

USRPRF (User Profile Authority Adoption)

Specify the USRPRF parameter to control how the program runs. The authority of the program's owner can be used when the program runs or the authority of the user running the program can be used.

• *USER Specify *USER to have the program run with the authority of the user running the program.

• *OWNER Specify *OWNER to have the program run with the authority of the program object's owner. Each object on the AS/400 has an associated owner. This owner is a user profile on the system. When *OWNER is specified, the program runs under the combined authority of both the user running the program and the program's owner. The combined authority of both user profiles is used to access objects while the program is running. Objects created during the program runtime are owned by the program's user.

AUT (User Authority)

Specify the AUT parameter to control the authority given to user profiles that don't have explicit authority to the program.

• *LIBCRTAUT Specify *LIBCRTAUT to grant user profiles authority to the program based on the CRTAUT (Object Creation Authority) from the library in which this program is being stored.

• *ALL Specify * ALL to grant user profile authority for all operations on the program except ownership authority, which is reserved to the owner of the program.

• *CHANGE Specify *CHANGE to grant user profiles all data access authorities and limited operations authority. This is the traditional authority granted to user profiles, and is typically that specified on the CRTAUT parameter for the library. Hence, AUT(*LIBCRTAUT) typically means AUT(*CHANGE).

• *USE Specify *USE to grant user profiles object-operational authority and read authority.

• *EXCLUDE Specify *EXCLUDE to avoid granting user profiles any access to the compiled program.

• authorization-list name Specify the name of the authorization list to which the program is added. The program is secured to this authorization list. The authorization list must exist when this program is created.

TRUNCNBR (Truncate Numbers on Overflow)

Specify the TRUNCNBR parameter to issue a message when a number is truncated during a move to the result field. This parameter applies only to traditional fixed-format operations and is for backward compatibility. Previous versions of RPG ignored truncation. The default for this parameter also causes truncation to be ignored. However, specifying TRUNCNBR(*NO) causes a message to be issued when truncation occurs.

• *YES Specify *YES to ignore numeric overflow (sometimes referred to as high-order truncation). Values are moved to the result field without notification. This is compatible with previous versions of RPG.

• *NO Specify *NO to cause a message to be generated when numeric overflow is detected. An RPG runtime error message is generated. This error can be trapped within the *PSSR subroutine of the RPG program. If it is noted, the operator (i.e., the end user of the program) is notified in a terse manner.

FIXNBR (Fix Decimal Data Errors for Zoned Numeric Fields)

Specify the FIXNBR parameter to cause the compiler to generate code that allows zoned numeric fields containing blanks or other non-numeric data to be converted to valid data.

• *NONE Specify *NONE to avoid fixing zoned decimal fields that contain decimal data errors. If decimal data errors are detected, an error is issued during program runtime.

• *ZONED Specify *ZONED to generate code that fixes decimal data errors detected in zoned decimal fields. This fix is performed when the zoned decimal data is being moved to a packed decimal field.

• *INPUTPACKED Specify *INPUTPACKED to generate code that fixes decimal data errors detected in packed decimal input fields. This fix is performed when the data is read into the program. Decimal data errors aren't allowed in on-input packed decimal fields, regardless of the option specified for the FIXNBR parameter.

TGTRLS (Target Operating System Release)

Specify the TGTRLS parameter to target prior versions and releases of the operating system. This option directs the compiler to generate code that is backward compatible with the targeted release. The IBM OS/400 operating system doesn't allow programs to run on back-releases. Only current and future versions and releases are reasonably guaranteed.

• *CURRENT Specify *CURRENT to indicate the current version and release is the target of the compiled program.

• *PRV Specify *PRV to indicate that the previous release of the operating system is the target of the compiled program.

• release-level Specify the version and release-level in the format VxRxMx, where Vx is the version, Rx is the release, and Mx is the modification level. For example, V3R7M0 is Version 3, Release 7, Modification level 0. The program can be used on an AS/400 running OS/400 with the specified release or with any subsequent release, unless program observability has been removed.

ALWNULL (Allow Null-Capable Fields in Database Records)

Specify the ALWNULL parameter to control whether the program allows records with null-capable fields to be read. Files declared as input-only support nulls in this manner. No other file processing supports nulls.

• *NO Specify *NO to restrict processing of null-capable fields. If the program reads a record containing a null value, a data-mapping error is issued and the record in not retrieved.

• *YES Specify *YES to allow processing of null-capable fields. To support null-capable fields, when a null value is detected, the default value for the field replaces the null value. For example, if a field containing a date is null-capable, and is null, when that field is retrieved, the default date value (either the current system date, or D'0001-01-01') replaces the null value for the field.