H-specs

Midware Ltd.

Control (or Header) specification allow you specify global parameters for how your program functions and is compiled. RPG III allowed one H-spec per program with the positional parameters.

RPG IV on the other hand uses free-form keywords for these parameters. Multiple H-specs may be used, and the keywords may be specified in any order.

For example, an H-spec coded in RPG III to format UDATE as YYMMDD would look like this:

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
H Y

The same H-spec in RPG IV looks like this (capitalization is up to you):

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
H Datedit(*YMD)

New H-spec keywords are added to each release. A great deal of the newer keywords are compile-option keywords that override the default or specified options on the CRTBNDRPG and CRTRPGMOD commands. This is potentially a very valuable feature, especially when using the more advanced features of ILE. If a program requires special compile-time parameters, they can be included in an H-spec instead of relying on programmers to remember those options when compiling future changes.

Some of the more useful H-spec keywords are described below. Many of these keywords deal with somewhat more advanced ILE functionality. Don't feel discouraged if you don't understand these yet - these ILE features will be covered in later sections.

BNDDIR('binding-directory-name' {:'binding-directory-name'...})
Allow you to indicate which binding directory(s) to use at compile time. See ILE section for more information on binding directories.

DATEDIT(fmt{separator})
This keyword allows you to specify the format of UDATE and *DATE within your program. The possible values are *DMY, *MDY, or *YMD. The default separator is "/". A separator character of "&" may be used to specify a blank separator. It is generally a good idea to explicitly specify the date format in the H-spec. If it is not used, the date format will be defaulted from the system date format. Otherwise, if the system date format is ever changed, or your program is distributed to and run on a different system, you may have unexpected results.

DATFMT(fmt{separator})
As opposed to the DATEDIT keyword which specifies the format of UDATE and *DATE, the DATFMT keyword specifies the default format for date-type data fields. The default format is *ISO (ccyy/mm/dd). Click here to see a complete list of date formats from IBM's V4R5 RPG documentation.

DEBUG{(*NO | *YES)}
Use this keyword to indicate whether or not to perform DUMP operations in your RPG program. The default is *NO, which means DUMP operations will not be performed. If you have an error handler that uses the DUMP op-code, you should specify DEBUG(*YES) in your H-spec.

NOMAIN
This parameter should be used in procedure modules (we'll cover this later). When used, the compiler will not generate the code to handle the RPG cycle.

OPTION(*{NO}SRCSTMT *{NO}DEBUGIO)
Over the past few releases, several new parameters have been added to the option keyword. I still think however that *SRCSTMT and *NODEBUGIO are the two most useful parameters. If OPTION(*NOSRCSTMT) is coded or omitted, the compile will re-number the source statements in the compiled module. What this means is that if your program gets a run-time exception, the statement it indicates will be virtually meaningless unless you saved the compile printout. This could be a major issue if the program blows up in production. The OPTION(*SRCSTMT) will prevent the compile process from renumbering the statements in the compile process. My opinion is that IBM should have made this the default, as I honestly can't think of a reason why you wouldn't code this in your program.

The *NODEBUGIO parameter is more of a convenience feature. If not specified, when stepping through a program using the interactive source debugger, a separate break will be inserted for each field returned from an I/O operation. When the *NODEBUGIO parameter is coded, the I/O statement only breaks once.

Click here to see a complete list of the available H-spec keywords (as of V4R5) from IBM's online documentation.

The minimum control specification that I personally use is as follows:

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
H datedit(*YMD) datfmt(*ISO) option(*SRCSTMT *NODEBUGIO)

Using more (or less) keywords is entirely up to you, depending on your requirements.

Using a Data Area to create a default H-spec

Instead of relying on every programmer to include the appropriate H-spec in their programs, it is possible to create a data area with your default keywords that will be automatically be included at compile time.

If an H-spec is included in the program, it will override any external H-specs in data areas.

If no H-spec is included however, the compiler will look for a data area named RPGLEHSPEC in your library list. If it is found, the contents of the data area will be used as your H-spec. There can be multiple data areas with this name in different libraries.

If RPGLEHSPEC is not found in the library list, the compiler will look for a data area named DFTLEHSPEC in library QRPGLE. If this if found, it's contents will be used as your H-spec.

The data areas must be type character, and can be whatever length you need.

Back to OPM vs. ILE

Next to F-specs

Last Modified: August 30, 2000