Program Status Data Structure

A program status data structure (PSDS) can be defined to make program exception/error information available to an RPG IV program. The PSDS must be defined in the main source section; therefore, there is only one PSDS per module.

A data structure is defined as a PSDS by the PSDS keyword in a free-form definition or by an S in position 23 of a fixed-form definition. A PSDS contains predefined subfields that provide you with information about the program exception/error that occurred. The location of the subfields in the PSDS is defined by special keywords or by predefined From and To positions. In order to access the subfields, you assign a name to each subfield. The keywords must be specified, left-adjusted in positions 26 through 39.

Information from the PSDS is also provided in a formatted dump. However, a formatted dump might not contain information for fields in the PSDS if the PSDS is not coded, or the length of the PSDS does not include those fields. For example, if the PSDS is only 275 bytes long, the time and date or program running will appear as *N/A*. in the dump, since this information starts at byte 276. For more information see DUMP (Program Dump).

Tip:

Call performance with LR on may be improved by having no PSDS, or a PSDS no longer than 80 bytes, since some of the information to fill the PSDS after 80 bytes may be costly to obtain.

Table 1 provides the layout of the subfields of the data structure and the predefined From and To positions of its subfields that can be used to access information in this data structure.

Table 1. Contents of the Program Status Data Structure
From

(Pos.

26-32)
To

(Pos.

33-39)


Format


Length


Keyword


Information
1 10 Character 10 *PROC If the module was compiled with CRTRPGMOD, this is the name of the module that was created; if the program was created using CRTBNDRPG, this is the name of the program that was created. For a cycle-main module, this is the name of the main procedure.
11 15 Zoned decimal 5,0 *STATUS Status code. For a description of these codes, see Program Status Codes.
16 20 Zoned decimal 5,0   Previous status code.
21 28 Character 8   RPG IV source listing line number or statement number. The source listing line number is replaced by the source listing statement number if OPTION(*SRCSTMT) is specified instead of OPTION(*NOSRCSTMT). The full statement number is included when it applies to the root source member. If the statement number is greater than 6 digits (that is, it includes a source ID other than zero), the first 2 positions of the 8-byte feedback area will have a "+ " indicating that the rest of statement number is stored in positions 354-355.
29 36 Character 8 *ROUTINE Name of the RPG IV routine in which the exception or error occurred. This subfield is updated at the beginning of an RPG IV routine or after a program call only when the *STATUS subfield is updated with a nonzero value. The following names identify the routines:
*INIT
Program initialization
*DETL
Detail lines
*GETIN
Get input record
*TOTC
Total calculations
*TOTL
Total lines
*DETC
Detail calculations
*OFL
Overflow lines
*TERM
Program ending
*ROUTINE
Name of program or procedure called (first 8 characters).
Note: *ROUTINE is not valid unless you use the normal RPG IV cycle. Logic that takes the program out of the normal RPG IV cycle may cause *ROUTINE to reflect an incorrect value.
37 39 Zoned decimal 3,0 *PARMS Number of parameters passed to this program from a calling program. The value is the same as that returned by %PARMS. If no information is available, -1 is returned.
40 42 Character 3   Exception type (CPF for an operating system exception or MCH for a machine exception).
43 46 Character 4   Exception number. For a CPF exception, this field contains a CPF message number. For a machine exception, it contains a machine exception number.
47 50 Character 4   Reserved
51 80 Character 30   Work area for messages. This area is only meant for internal use by the ILE RPG compiler. The organization of information will not always be consistent. It can be displayed by the user.
81 90 Character 10   Name of library in which the program is located.
91 170 Character 80   Retrieved exception data. The message causing the error is placed in this subfield.
171 174 Character 4   Identification of the exception that caused RNX9001 exception to be signaled.
175 184 Character 10   Name of file on which the last file operation occurred (updated only when an error occurs). This information always contains the full file name.
185 190 Character 6   Unused.
191 198 Character 8   Date (*DATE format) the job entered the system. In the case of batch jobs submitted for overnight processing, those that run after midnight will carry the next day's date. This value is derived from the job date, with the year expanded to the full four years. The date represented by this value is the same date represented by positions 270 - 275.
199 200 Zoned decimal 2,0   First 2 digits of a 4-digit year. The same as the first 2 digits of *YEAR. This field applies to the century part of the date in positions 270 to 275. For example, for the date 1999-06-27, UDATE would be 990627, and this century field would be 19. The value in this field in conjunction with the value in positions 270 - 275 has the combined information of the value in positions 191 -198.
Note: This century field does not apply to the dates in positions 276 to 281, or positions 288 to 293.
201 208 Character 8   Name of file on which the last file operation occurred (updated only when an error occurs). This file name will be truncated if a long file name is used. See positions 175-184 for long file name information.
209 243 Character 35   Status information on the last file used. This information includes the status code, the RPG IV opcode, the RPG IV routine name, the source listing line number or statement number, and record name. It is updated only when an error occurs.
Note: The opcode name is in the same form as *OPCODE in the INFDS
The source listing line number is replaced by the source listing statement number if OPTION(*SRCSTMT) is specified instead of OPTION(*NOSRCSTMT). The full statement number is included when it applies to the root source member. If the statement number is greater than 6 digits (that is, it includes a source ID other than zero), the first 2 positions of the 8-byte feedback area will have a "+ " indicating that the rest of statement number is stored in positions 356-357.
244 253 Character 10   Job name.
254 263 Character 10   User name from the user profile.
264 269 Zoned decimal 6,0   Job number.
270 275 Zoned decimal 6,0   Date (in UDATE format) the program started running in the system (UDATE is derived from this date). See User Date Special Words for a description of UDATE. This is commonly known as the 'job date'. The date represented by this value is the same date represented by positions 191 - 198.
276 281 Zoned decimal 6,0   Date of program running (the system date in UDATE format). If the year part of this value is between 40 and 99, the date is between 1940 and 1999. Otherwise the date is between 2000 and 2039. The 'century' value in positions 199 - 200 does not apply to this field.
282 287 Zoned decimal 6,0   Time (in the format hhmmss) of the program running.
288 293 Character 6   Date (in UDATE format) the program was compiled. If the year part of this value is between 40 and 99, the date is between 1940 and 1999. Otherwise the date is between 2000 and 2039. The 'century' value in positions 199 - 200 does not apply to this field.
294 299 Character 6   Time (in the format hhmmss) the program was compiled.
300 303 Character 4   Level of the compiler.
304 313 Character 10   Source file name.
314 323 Character 10   Source library name.
324 333 Character 10   Source file member name.
334 343 Character 10   Program containing procedure.
344 353 Character 10   Module containing procedure.
354 355 Binary 2   Source Id matching the statement number from positions 21-28.
356 357 Binary 2   Source Id matching the statement number from positions 228-235.
358 367 Character 10   Current user profile name.
368 371 Integer 10,0   External error code
372 379 Integer 20,0   Elements set by XML-INTO or DATA-INTO
380 395 Character 16   Internal job ID.
396 403 Character 8   System name.
404 429 Character 50   Unused.