ILE RPG Reference

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 an S in position 23 of the data structure statement. 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 will be greatly 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 is costly to obtain.

Table 9 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 9. Contents of the Program Status Data Structure

From (Pos. 26-32)	To (Pos. 33-39)	Format	Length	Keyword	Information
1	10	Character	10	*PROC	Name of the main procedure, if there is one; otherwise, the name associated with the main source section.
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 a OS/400 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. CPF messages are placed in this subfield when location *STATUS contains 09999.
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	429	Character	76		Unused.
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	429	Character	62		Unused.

Program Status Codes

Any code placed in the subfield location *STATUS that is greater than 99 is considered to be an exception/error condition. When the status code is greater than 99; the error indicator -- if specified in positions 73 and 74 -- is set on, or the %ERROR built-in function -- if the 'E' extender is specified -- is set to return '1', |or control passes to the appropriate ON-ERROR group within a MONITOR |block; otherwise, the program exception/error subroutine receives control. Location *STATUS is updated when an exception/error occurs.

The %STATUS built-in function returns the most recent value set for the program or file status.

The following codes are placed in the subfield location *STATUS for the program status data structure:

Normal Codes

Code

Condition

00000

No exception/error occurred

00001

Called program returned with the LR indicator on.

00050

Conversion resulted in substitution.

Exception/Error Codes

Code

Condition

00100

Value out of range for string operation

00101

Negative square root

00102

Divide by zero

00103

An intermediate result is not large enough to contain the result.

00104

Float underflow. An intermediate value is too small to be contained in the intermediate result field.

00112

Invalid Date, Time or Timestamp value.

00113

Date overflow or underflow. (For example, when the result of a Date calculation results in a number greater than *HIVAL or less than *LOVAL.)

00114

Date mapping errors, where a Date is mapped from a 4-character year to a 2-character year, and the date range is not 1940-2039.

00115

Variable-length field has a current length that is not valid.

00120

Table or array out of sequence.

00121

Array index not valid

00122

OCCUR outside of range

00123

Reset attempted during initialization step of program

00202

Called program or procedure failed; halt indicator (H1 through H9) not on

00211

Error calling program or procedure

00222

Pointer or parameter error

00231

Called program or procedure returned with halt indicator on

00232

Halt indicator on in this program

00233

Halt indicator on when RETURN operation run

00299

RPG IV formatted dump failed|

|00301

|Class or method not found for a method call, or error in method |call.|

|00302

|Error while converting a Java array to an RPG parameter on entry to a Java |native method.|

|00303

|Error converting RPG parameter to Java array on exit from an RPG native |method.|

|00304

|Error converting RPG parameter to Java array in preparation for a Java |method call.|

|00305

|Error converting Java array to RPG parameter or return value after a Java |method.|

|00306

|Error converting RPG return value to Java array.

00333

Error on DSPLY operation

00401

Data area specified on IN/OUT not found

00402

*PDA not valid for non-prestart job

00411

Data area type or length does not match

00412

Data area not locked for output

00413

Error on IN/OUT operation

00414

User not authorized to use data area

00415

User not authorized to change data area

00421

Error on UNLOCK operation

00425

Length requested for storage allocation is out of range

00426

Error encountered during storage management operation

00431

Data area previously locked by another program

00432

Data area locked by program in the same process

00450

Character field not entirely enclosed by shift-out and shift-in characters|

|00451

|Conversion between two CCSIDs is not supported.

00501

Failure to retrieve sort sequence.

00502

Failure to convert sort sequence.

00802

Commitment control not active.

00803

Rollback operation failed.

00804

Error occurred on COMMIT operation

00805

Error occurred on ROLBK operation

00907

Decimal data error (digit or sign not valid)

00970

The level number of the compiler used to generate the program does not agree with the level number of the RPG IV run-time subroutines.

09998

Internal failure in ILE RPG compiler or in run-time subroutines

09999

Program exception in system routine.

PSDS Example

To specify a PSDS in your program, you code the program status data structure and the subfields you wish to use on a definition specification.

Figure 36. Example of Coding a PSDS

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DMYPSDS SDS D PROC_NAME *PROC * Procedure name D PGM_STATUS *STATUS * Status code D PRV_STATUS 16 20S 0 * Previous status D LINE_NUM 21 28 * Src list line num D ROUTINE *ROUTINE * Routine name D PARMS *PARMS * Num passed parms D EXCP_TYPE 40 42 * Exception type D EXCP_NUM 43 46 * Exception number D PGM_LIB 81 90 * Program library D EXCP_DATA 91 170 * Exception data D EXCP_ID 171 174 * Exception Id D DATE 191 198 * Date (*DATE fmt) D YEAR 199 200S 0 * Year (*YEAR fmt) D LAST_FILE 201 208 * Last file used D FILE_INFO 209 243 * File error info D JOB_NAME 244 253 * Job name D USER 254 263 * User name D JOB_NUM 264 269S 0 * Job number D JOB_DATE 270 275S 0 * Date (UDATE fmt) D RUN_DATE 276 281S 0 * Run date (UDATE) D RUN_TIME 282 287S 0 * Run time (UDATE) D CRT_DATE 288 293 * Create date D CRT_TIME 294 299 * Create time D CPL_LEVEL 300 303 * Compiler level D SRC_FILE 304 313 * Source file D SRC_LIB 314 323 * Source file lib D SRC_MBR 324 333 * Source file mbr D PROC_PGM 334 343 * Pgm Proc is in D PROC_MOD 344 353 * Mod Proc is in

Note:

The keywords are not labels and cannot be used to access the subfields. Short entries are padded on the right with blanks.

---

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]