Data-Area  Datastructures Operations

The data area operations are:

• IN (Retrieve a Data Area)
• OUT (Write a Data Area)
• UNLCK (Unlock a Data Area or Release a Record).

The IN and OUT operations allow you to retrieve and write one or all data areas in a program, depending on the factor 2 entry.

The IN and OUT operations also allow you to control the locking or unlocking of a data area. When a data area is locked, it can be read but not updated by other programs.

The following lock states are used:

• For an IN operation with *LOCK specified, an exclusive allow read lock state is placed on the data area.
• For an OUT or UNLCK operation, the exclusive allow read lock state is released.

During the actual transfer of data into or out of a data area, there is a system-internal lock on the data area. If several users are contending for the same data area, a user may get an error message indicating that the data area is not available.

Remember the following when using the IN, OUT, and UNLCK operations:

• A data-area operation cannot be done on a data area that is not defined to the operating system.
• Before the IN, OUT, and UNLCK operations can be done on a data area, you must specify that data area in the result field of an *NAMVAR DEFN statement. (For further information on the DEFN statement, see DEFN (Field Definition).)
• The data-area operations can be done on a data-area data structure that is implicitly retrieved only if the data-area data structure name is specified in the result field of an *NAMVAR DEFN statement.
• A locked data area cannot be updated or locked by another RPG/400 program; however, the data area can be retrieved in your own program by an IN operation with factor 1 blank.
• A data-area name cannot be the name of a multiple-occurrence data structure, an input record field, an array, an array element, or a table.
• A data area cannot be the subfield of a multiple occurrence data structure, a data-area data structure, a program-status data structure, a file-information data structure (INFDS), or a data structure that appears on an *NAMVAR DEFN statement.

A data structure defined with a U in position 18 of the input specifications form indicates that the data structure is a data area. The data area is automatically read and locked at program initialization time, and the contents of the data structure are written to the data area when the program ends with LR on.

Specify *LDA in factor 2 of a *NAMVAR DEFN statement to define the LDA data structure.

Use the *NAMVAR DEFN operation with *PDA in factor 2 to define the name in the result field as the PDA data area. The result field follows the current conventions for *NAMVAR DEFN.

RPG IV (RPG ILE) and AS400 Data Area Programming

Data Area processing in ILE RPG program

All examples in this section of article use a data area created by the following command

CRTDTAARA DTAARA(EMP_INFO) TYPE(*CHAR) LEN(10) VALUE('01TutoIndi')

To use a data area in an RPG IV program we need to first declare the data area as a variable in the source code of the program. This variable can either be a stand-alone or a data structure. In RPG IV a data area can be declared in the following two ways.

1. One line declaration ( RPG IV method of declaring a data area; Recommended)

   
   DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++
   DW@DtaAra         S             10A   DTAARA(EMP_INFO)
   
   

   Notice that the data type of the stand alone variable should be same as the data type of the data area. However, if you need to declare a data area which has multiple data formats you should declare it as a data structure. The above dclaration can be made as

   
   DW@DtaAra         DS                  DTAARA(EMP_INFO)
   DW@Emp#                   1      2  0                 
   DW@EmpName                3     10                    
   
   

2. Declaration Using Like Definition (Old method)
   This section is given for the sake of completion of this article as I've found such declaration at several places in RPG III and even RPG IV, both types of programs!
   This method of declaration is usually a two step method.
   Firstly, an RPG variable is declared. A stand alone variable is declared in the C Spec result section or D-Spec and a data structure is defined in the I Specification or D Spec in RPG IV.
   After that, The data area is declared in the C-Spec using the opcode "Define" as given below. Notice that the first factor of this opcode is *DTAARA which tells the compiler that the factor 2 is a data area and look for it in the library list when compiling.

   
   C     *DTAARA       Define    EMP_INFO      W@DtaAra
   

   Here, W@DtaAra can be a data structure or a stand alone variable. If it's a stand alone variable, it can be defined here itself.
   Note:- The idea is to declare variable and then the Data area. How you achieve this is upto you. Due to this flexibility, I have found several combinations of declaration of data area.

---

Read a Data Area in ILE RPG (IV)
Reading a data area in an RPG IV program is a two step process. The first step is to read a data area using the opcode IN as given blow.

C     *Lock         In        W@Dtaara

As soon as this statement is executed, the variable/s is/are populated with the data area value. Here it's important to note that the first factor '*LOCK' is required to maintain data integrity and hence can not be omitted. The exception to this rule is the local data area where no lock is required.
The second step would to unlock the data area. If you are using a data area for read only purpose, you need to Unlock the data area using the opcode UNLOCK as given blow.

CL0N01Factor1+++++++Opcode&ExtFactor2++
C                   Unlock    W@DtaAra 

Other way to unlock a data area will be to update it. To update a data area we use the opcode 'OUT'. The opcode OUT updates the date area with the current value of the RPG variable/Data structure. The syntax to update the data area is as given below.

CL0N01Factor1+++++++Opcode&ExtFactor2+
C                   Out       W@DtaAra

The OUT opcode requires a lock on the data area except in case of local data area where it's not required to take a lock beforehand.
That's all about data area processing in RPG IV. Now refer the examples given below to become more intimate with data area processing in RPG programs.

---

Program using Read only Data Area

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++
DW@DtaAra         DS                  DTAARA(EMP_INFO)
DW@Emp#                   1      2  0                 
DW@EmpName                3     10                    
 **                                                   
CL0N01Factor1+++++++Opcode&ExtFactor2+++++++Result++++
C     *Lock         In        W@Dtaara                
C     W@Emp#        Dsply                             
C     W@EmpName     Dsply                             
C                   Unlock    W@DtaAra                
 **                                                   
C                   Return                                              

Output:-
DSPLY 1
DSPLY TutoIndi

---

Program Updating Data Area

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++
DW@DtaAra         DS                  DTAARA(EMP_INFO) 
DW@Emp#                   1      2  0                  
DW@EmpName                3     10                     
 **                                                    
CL0N01Factor1+++++++Opcode&ExtFactor2+++++++Result+++++
C     *Lock         In        W@Dtaara                 
C     W@Emp#        Dsply                              
C     W@EmpName     Dsply                              
 **                                                    
C                   Eval      W@Emp# +=1               
C                   Out       W@DtaAra                 
 **                                                    
C     W@Emp#        Dsply                              
C     W@EmpName     Dsply                              
C                   Return                                                      

Output:-
DSPLY 1
DSPLY TutoIndi
DSPLY 2
DSPLY TutoIndi
The above program shows how to update specific portion of a data area. 'OUT' opcode in itself updates all values of the data area. However, with judicious use of data structure we accomplish partial update.

---

Summary
The Data Area article has been quite a long one hence a summary is given below.
1. Data area is an object. It stores data but it's not a physical file.
2. CRTDTAARA, DSPDTAARA, CHGDTAARA commands create, display and change a data area respectively. These commands are run from command line.
3. RTVDTAARA command return the current value of data area in a similar data type CL variable.
4. We can use specific portion of a data area using substring optional feature of RTVDTAARA and CHGDTAARA commands.
5. Data area should be defined in the D-Spec in an RPG program.
6. Reading a data area in an RPG program is a two step process (Except local data area). Read with lock and Unlock.
7. Data area is read using the opcode IN with *LOCK as factor 1. *LOCK is required if data area is not a local data area.
8. Data area can be unlocked by UNLOCK or OUT opcodes. Out opcode updates and unlocks the data area.

able 5. Contents of the File Feedback Information Available in the File Information Data Structure (INFDS)

From (Pos. 26-32)	To (Pos. 33-39)	Format	Length	Keyword	Information
1	8	Character	8	*FILE	The first 8 characters of the file name.
9	9	Character	1		Open indication (1 = open).
10	10	Character	1		End of file (1 = end of file)
11	15	Zoned decimal	5,0	*STATUS	Status code. For a description of these codes, see File Status Codes.
16	21	Character	6	*OPCODE	Operation code The first five positions (left-adjusted) specify the type of operation by using the character representation of the calculation operation codes. For example, if a READE was being processed, READE is placed in the leftmost five positions. If the operation was an implicit operation (for example, a primary file read or update on the output specifications), the equivalent operation code is generated (such as READ or UPDAT) and placed in location *OPCODE. Operation codes which have 6 letter names will be shortened to 5 letters. DELETE DELET EXCEPT EXCPT READPE REDPE UNLOCK UNLCK UPDATE UPDAT The remaining position contains one of the following: F The last operation was specified for a file name. R The last operation was specified for a record. I The last operation was an implicit file operation.
22	29	Character	8	*ROUTINE	First 8 characters of the name of the routine (including a subprocedure) in which the file operation was done.
30	37	Character	8		If OPTION(*NOSRCSTMT) is specified, this is the source listing line number of the file operation. If OPTION(*SRCSTMT) is specified, this is the source listing statement number of the file operation. 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 the statement number is stored in positions 53-54.
38	42	Zoned decimal	5,0		User-specified reason for error on SPECIAL file.
38	45	Character	8	*RECORD	For a program described file the record identifying indicator is placed left-adjusted in the field; the remaining six positions are filled with blanks. For an externally described file, the first 8 characters of the name of the record being processed when the exception/error occurred.
46	52	Character	7		Machine or system message number.
53	66	Character	14		Unused.
77	78	Binary	2		Source Id matching the statement number from positions 30-37.

Table 6. Contents of the File Feedback Information Available in the File-Information Data Structure (INFDS) Valid after a POST

From (Pos. 26-32)	To (Pos. 33-39)	Format	Length	Keyword	Information
67	70	Zoned decimal	4,0	*SIZE	Screen size (product of the number of rows and the number of columns on the device screen).
71	72	Zoned decimal	2,0	*INP	The display's keyboard type. Set to 00 if the keyboard is alphanumeric or katakana. Set to 10 if the keyboard is ideographic.
73	74	Zoned decimal	2,0	*OUT	The display type. Set to 00 if the display is alphanumeric or katakana. Set to 10 if the display is ideographic. Set to 20 if the display is DBCS.
75	76	Zoned decimal	2,0	*MODE	Always set to 00.

INFDS File Feedback Example

To specify an INFDS which contains fields in the file feedback section, you can make the following entries:

• Specify the INFDS keyword on the file description specification with the name of the file information data structure
• Specify the file information data structure and the subfields you wish to use on a definition specification.
• Specify special keywords left-adjusted, in the FROM field (positions 26-32) on the definition specification, or specify the positions of the fields in the FROM field (position 26-32) and the TO field (position 33-39).

Figure 26. Example of Coding an INFDS with File Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE IF E DISK INFDS(FILEFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DFILEFBK DS D FILE *FILE * File name D OPEN_IND 9 9N * File open? D EOF_IND 10 10N * File at eof? D STATUS *STATUS * Status code D OPCODE *OPCODE * Last opcode D ROUTINE *ROUTINE * RPG Routine D LIST_NUM 30 37 * Listing line D SPCL_STAT 38 42S 0 * SPECIAL status D RECORD *RECORD * Record name D MSGID 46 52 * Error MSGID D SCREEN *SIZE * Screen size D NLS_IN *INP * NLS Input? D NLS_OUT *OUT * NLS Output? D NLS_MODE *MODE * NLS Mode?

Note:

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

Open Feedback Information

Positions 81 through 240 in the file information data structure contain open feedback information. The contents of the file open feedback area are copied by RPG to the open feedback section of the INFDS whenever the file associated with the INFDS is opened. This includes members opened as a result of a read operation on a multi-member processed file.

A description of the contents of the open feedback area, and what file types the fields are valid for, can be found in the |iSeries Information Center.

INFDS Open Feedback Example

To specify an INFDS which contains fields in the open feedback section, you can make the following entries:

• Specify the INFDS keyword on the file description specification with the name of the file information data structure
• Specify the file information data structure and the subfields you wish to use on a definition specification.
• Use information in the |iSeries Information Center database and file systems category to determine which fields you wish to include in the INFDS. To calculate the From and To positions (positions 26 through 32 and 33 through 39 of the definition specifications) that specify the subfields of the open feedback section of the INFDS, use the Offset, Data Type, and Length given in the Information Center and do the following calculations:

     From = 81 + Offset
     To = From - 1 + Character_Length
     Character_Length = Length (in bytes)
  

  
  For example, for overflow line number of a printer file, the |Information Center gives:
  

     Offset = 107
     Data Type is binary
     Length = 2
  Therefore,
     From = 81 + 107 = 188,
     To = 188 - 1 + 2 = 189.
     See subfield OVERFLOW in example below
  

Figure 27. Example of Coding an INFDS with Open Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE O F 132 PRINTER INFDS(OPNFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DOPNFBK DS D ODP_TYPE 81 82 * ODP Type D FILE_NAME 83 92 * File name D LIBRARY 93 102 * Library name D SPOOL_FILE 103 112 * Spool file name D SPOOL_LIB 113 122 * Spool file lib D SPOOL_NUM 123 124I 0 * Spool file num D RCD_LEN 125 126I 0 * Max record len D KEY_LEN 127 128I 0 * Max key len D MEMBER 129 138 * Member name D TYPE 147 148I 0 * File type D ROWS 152 153I 0 * Num PRT/DSP rows D COLUMNS 154 155I 0 * Num PRT/DSP cols D NUM_RCDS 156 159I 0 * Num of records D ACC_TYPE 160 161 * Access type D DUP_KEY 162 162 * Duplicate key? D SRC_FILE 163 163 * Source file? D VOL_OFF 184 185I 0 * Vol label offset D BLK_RCDS 186 187I 0 * Max rcds in blk D OVERFLOW 188 189I 0 * Overflow line D BLK_INCR 190 191I 0 * Blk increment D FLAGS1 196 196 * Misc flags D REQUESTER 197 206 * Requester name D OPEN_COUNT 207 208I 0 * Open count D BASED_MBRS 211 212I 0 * Num based mbrs D FLAGS2 213 213 * Misc flags D OPEN_ID 214 215 * Open identifier D RCDFMT_LEN 216 217I 0 * Max rcd fmt len D CCSID 218 219I 0 * Database CCSID D FLAGS3 220 220 * Misc flags D NUM_DEVS 227 228I 0 * Num devs defined

Input/Output Feedback Information

Positions 241 through 366 in the file information data structure are used for input/output feedback information. The contents of the file common input/output feedback area are copied by RPG to the input/output feedback section of the INFDS:

• If a POST for any file with factor 1 blank has been specified anywhere in your program:
  • only after a POST for the file.
• If a POST for any file with factor 1 blank has not been specified anywhere in your program:
  • after each I/O operation, if blocking is not active for the file.
  • after the I/O request to data management to get or put a block of data, if blocking is active for the file.

For more information see POST (Post).

A description of the contents of the input/output feedback area can be found in the |Information Center.

INFDS Input/Output Feedback Example

To specify an INFDS which contains fields in the input/output feedback section, you can make the following entries:

• Specify the INFDS keyword on the file description specification with the name of the file information data structure
• Specify the file information data structure and the subfields you wish to use on a definition specification.
• Use information in the |Information Center to determine which fields you wish to include in the INFDS. To calculate the From and To positions (positions 26 through 32 and 33 through 39 of the definition specifications) that specify the subfields of the input/output feedback section of the INFDS, use the Offset, Data Type, and Length given in the |Information Center and do the following calculations:

     From = 241 + Offset
     To = From - 1 + Character_Length
     Character_Length = Length (in bytes)
  

  For example, for device class of a file, the |Information Center gives:
  

     Offset = 30
     Data Type is character
     Length = 2
  Therefore,
     From = 241 + 30 = 271,
     To = 271 - 1 + 2 = 272.
     See subfield DEV_CLASS in example below
  

Figure 28. Example of Coding an INFDS with Input/Output Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE IF E DISK INFDS(MYIOFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DMYIOFBK DS D * 241-242 not used D WRITE_CNT 243 246I 0 * Write count D READ_CNT 247 250I 0 * Read count D WRTRD_CNT 251 254I 0 * Write/read count D OTHER_CNT 255 258I 0 * Other I/O count D OPERATION 260 260 * Cuurent operation D IO_RCD_FMT 261 270 * Rcd format name D DEV_CLASS 271 272 * Device class D IO_PGM_DEV 273 282 * Pgm device name D IO_RCD_LEN 283 286I 0 * Rcd len of I/O

Device Specific Feedback Information

The device specific feedback information in the file information data structure starts at position 367 in the INFDS, and contains input/output feedback information specific to a device.

The length of the INFDS when device specific feedback information is required, depends on two factors: the device type of the file, and on whether DISK files are keyed or not. The minimum length is 528; but some files require a longer INFDS.

• For WORKSTN files, the INFDS is long enough to hold the device-specific feedback information for any type of display or ICF file starting at position 241. For example, if the longest device-specific feedback information requires 390 bytes, the INFDS for WORKSTN files is 630 bytes long (240+390=630).
• For externally described DISK files, the INFDS is at least long enough to hold the longest key in the file beginning at position 401.

More information on the contents and length of the device feedback for database file, printer files, ICF and display files can be found in the |iSeries Information Center database and file systems category.

The contents of the device specific input/output feedback area of the file are copied by RPG to the device specific feedback section of the INFDS:

• If a POST for any file with factor 1 blank has been specified anywhere in your program:
  • only after a POST for the file.
• If a POST for any file with factor 1 blank has not been specified anywhere in your program:
  • after each I/O operation, if blocking is not active for the file.
  • after the I/O request to data management to get or put a block of data, if blocking is active for the file.

Notes:

1. After each keyed input operation, only the key fields will be updated.
2. After each non-keyed input operation, only the relative record number will be updated.

For more information see POST (Post).

INFDS Device Specific Feedback Examples

To specify an INFDS which contains fields in the device-specific feedback section, you can make the following entries:

• Specify the INFDS keyword on the file description specification with the name of the file information data structure
• Specify the file information data structure and the subfields you wish to use on a definition specification.
• Use information in the |Information Center to determine which fields you wish to include in the INFDS. To calculate the From and To positions (positions 26 through 32 and 33 through 39 of the definition specifications) that specify the subfields of the input/output feedback section of the INFDS, use the Offset, Data Type, and Length given in the |Information Center and do the following calculations:

     From = 367 + Offset
     To = From - 1 + Character_Length
     Character_Length = Length (in bytes)
  

  For example, for relative record number of a data base file, the |Information Center gives:
  

     Offset = 30
     Data Type is binary
     Length = 4
  Therefore,
     From = 367 + 30 = 397,
     To = 397 - 1 + 4 = 400.
     See subfield DB_RRN in DBFBK data structure in example below
  

Figure 29. Example of Coding an INFDS with Printer Specific Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE O F 132 PRINTER INFDS(PRTFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DPRTFBK DS D CUR_LINE 367 368I 0 * Current line num D CUR_PAGE 369 372I 0 * Current page cnt * If the first bit of PRT_FLAGS is on, the spooled file has been * deleted. Use TESTB X'80' or TESTB '0' to test this bit. D PRT_FLAGS 373 373 D PRT_MAJOR 401 402 * Major ret code D PRT_MINOR 403 404 * Minor ret code

Figure 30. Example of Coding an INFDS with Database Specific Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE IF E DISK INFDS(DBFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DDBFBK DS D FDBK_SIZE 367 370I 0 * Size of DB fdbk D JOIN_BITS 371 374I 0 * JFILE bits D LOCK_RCDS 377 378I 0 * Nbr locked rcds D POS_BITS 385 385 * File pos bits D DLT_BITS 384 384 * Rcd deleted bits D NUM_KEYS 387 388I 0 * Num keys (bin) D KEY_LEN 393 394I 0 * Key length D MBR_NUM 395 396I 0 * Member number D DB_RRN 397 400I 0 * Relative-rcd-num D KEY 401 2400 * Key value (max D * size 2000)

Figure 31. Example of Coding an INFDS with ICF Specific Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE CF E WORKSTN INFDS(ICFFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DICFFBK DS D ICF_AID 369 369 * AID byte D ICF_LEN 372 375I 0 * Actual data len D ICF_MAJOR 401 402 * Major ret code D ICF_MINOR 403 404 * Minor ret code D SNA_SENSE 405 412 * SNA sense rc D SAFE_IND 413 413 * Safe indicator D RQSWRT 415 415 * Request write D RMT_FMT 416 425 * Remote rcd fmt D ICF_MODE 430 437 * Mode name

Figure 32. Example of Coding an INFDS with Display Specific Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE CF E WORKSTN INFDS(DSPFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DDSPFBK DS D DSP_FLAG1 367 368 * Display flags D DSP_AID 369 369 * AID byte D CURSOR 370 371 * Cursor location D DATA_LEN 372 375I 0 * Actual data len D SF_RRN 376 377I 0 * Subfile rrn D MIN_RRN 378 379I 0 * Subfile min rrn D NUM_RCDS 380 381I 0 * Subfile num rcds D ACT_CURS 382 383 * Active window D * cursor location D DSP_MAJOR 401 402 * Major ret code D DSP_MINOR 403 404 * Minor ret code

Get Attributes Feedback Information

The get attributes feedback information in the file information data structure starts at position 241 in the INFDS, and contains information about a display device or ICF session (a device associated with a WORKSTN file). The end position of the get attributes feedback information depends on the length of the data returned by a get attributes data management operation. The get attributes data management operation is performed when a POST with a program device specified for factor 1 is used.

More information about the contents and the length of the get attributes data can be found in the |Information Center.

INFDS Get Attributes Feedback Example

To specify an INFDS which contains fields in the get attributes feedback section, you can make the following entries:

• Specify the INFDS keyword on the file description specification with the name of the file information data structure
• Specify the file information data structure and the subfields you wish to use on a definition specification.
• Use information in the |Information Center to determine which fields you wish to include in the INFDS. To calculate the From and To positions (positions 26 through 32 and 33 through 39 of the definition specifications) that specify the subfields of the get attributes feedback section of the INFDS, use the Offset, Data Type, and Length given in the |Information Center and do the following calculations:

     From = 241 + Offset
     To = From - 1 + Character_Length
     Character_Length = Length (in bytes)
  

  For example, for device type of a file, the |Information Center gives:
  

     Offset = 31
     Data Type is character
     Length = 6
  Therefore,
     From = 241 + 31 = 272,
     To = 272 - 1 + 6 = 277.
     See subfield DEV_TYPE in example below
  

Figure 33. Example of Coding an INFDS with Display file Get Attributes Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE CF E WORKSTN INFDS(DSPATRFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DDSPATRFBK DS D PGM_DEV 241 250 * Program device D DEV_DSC 251 260 * Dev description D USER_ID 261 270 * User ID D DEV_CLASS 271 271 * Device class D DEV_TYPE 272 277 * Device type D REQ_DEV 278 278 * Requester? D ACQ_STAT 279 279 * Acquire status D INV_STAT 280 280 * Invite status D DATA_AVAIL 281 281 * Data available D NUM_ROWS 282 283I 0 * Number of rows D NUM_COLS 284 285I 0 * Number of cols D BLINK 286 286 * Allow blink? D LINE_STAT 287 287 * Online/offline? D DSP_LOC 288 288 * Display location D DSP_TYPE 289 289 * Display type D KBD_TYPE 290 290 * Keyboard type D CTL_INFO 342 342 * Controller info D COLOR_DSP 343 343 * Color capable? D GRID_DSP 344 344 * Grid line dsp? * The following fields apply to ISDN. D ISDN_LEN 385 386I 0 * Rmt number len D ISDN_TYPE 387 388 * Rmt number type D ISDN_PLAN 389 390 * Rmt number plan D ISDN_NUM 391 430 * Rmt number D ISDN_SLEN 435 436I 0 * Rmt sub-address D * length D ISDN_STYPE 437 438 * Rmt sub-address D * type D ISDN_SNUM 439 478 * Rmt sub-address D ISDN_CON 480 480 * Connection D ISDN_RLEN 481 482I 0 * Rmt address len D ISDN_RNUM 483 514 * Rmt address D ISDN_ELEN 519 520 * Extension len D ISDN_ETYPE 521 521 * Extension type D ISDN_ENUM 522 561 * Extension num D ISDN_XTYPE 566 566 * X.25 call type D

Figure 34. Example of Coding an INFDS with ICF file Get Attributes Feedback Information

FFilename++IPEASFRlen+LKlen+AIDevice+.Keywords+++++++++++++++++++++++++++++Comments++++++++++ FMYFILE CF E WORKSTN INFDS(ICFATRFBK) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++Comments++++++++++ DICFATRFBK DS D PGM_DEV 241 250 * Program device D DEV_DSC 251 260 * Dev description D USER_ID 261 270 * User ID D DEV_CLASS 271 271 * Device class D DEV_TYPE 272 272 * Device type D REQ_DEV 278 278 * Requester? D ACQ_STAT 279 279 * Acquire status D INV_STAT 280 280 * Invite status D DATA_AVAIL 281 281 * Data available D SES_STAT 291 291 * Session status D SYNC_LVL 292 292 * Synch level D CONV_TYPE 293 293 * Conversation typ D RMT_LOC 294 301 * Remote location D LCL_LU 302 309 * Local LU name D LCL_NETID 310 317 * Local net ID D RMT_LU 318 325 * Remote LU D RMT_NETID 326 333 * Remote net ID D APPC_MODE 334 341 * APPC Mode D LU6_STATE 345 345 * LU6 conv state D LU6_COR 346 353 * LU6 conv D * correlator * The following fields apply to ISDN. D ISDN_LEN 385 386I 0 * Rmt number len D ISDN_TYPE 387 388 * Rmt number type D ISDN_PLAN 389 390 * Rmt number plan D ISDN_NUM 391 430 * Rmt number D ISDN_SLEN 435 436I 0 * sub-addr len D ISDN_STYPE 437 438 * sub-addr type D ISDN_SNUM 439 478 * Rmt sub-address D ISDN_CON 480 480 * Connection D ISDN_RLEN 481 482I 0 * Rmt address len D ISDN_RNUM 483 514 * Rmt address D ISDN_ELEN 519 520 * Extension len D ISDN_ETYPE 521 521 * Extension type D ISDN_ENUM 522 561 * Extension num D ISDN_XTYPE 566 566 * X.25 call type * The following information is available only when program was started * as result of a received program start request. (P_ stands for protected) D TRAN_PGM 567 630 * Trans pgm name D P_LUWIDLN 631 631 * LUWID fld len D P_LUNAMELN 632 632 * LU-NAME len D P_LUNAME 633 649 * LU-NAME D P_LUWIDIN 650 655 * LUWID instance D P_LUWIDSEQ 656 657I 0 * LUWID seq num * The following information is available only when a protected conversation * is started on a remote system. (U_ stands for unprotected) D U_LUWIDLN 658 658 * LUWID fld len D U_LUNAMELN 659 659 * LU-NAME len D U_LUNAME 660 676 * LU-NAME D U_LUWIDIN 677 682 * LUWID instance D U_LUWIDSEQ 683 684I 0 * LUWID seq num

Blocking Considerations

The fields of the input/output specific feedback in the INFDS and in most cases the fields of the device specific feedback information section of the INFDS, are not updated for each operation to the file in which the records are blocked and unblocked. The feedback information is updated only when a block of records is transferred between an RPG program and the OS/400 system. However, if you are doing blocked input on a data base file, the relative record number and the key value in the data base feedback section of the INFDS are updated:

• On every input/output operation, if a POST for any file with factor 1 blank has not been specified anywhere in your program.
• Only after a POST for the file, if a POST for any file with factor 1 blank has been specified anywhere in your program.

You can obtain valid updated feedback information by using the CL command OVRDBF (Override with Database File) with SEQONLY(*NO) specified. If you use a file override command, the ILE RPG compiler does not block or unblock the records in the file.

For more information on blocking and unblocking of records in RPG see ILE RPG Programmer's Guide.

File 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'; otherwise, the file exception/error subroutine receives control. Location *STATUS is updated after every file operation.

You can use the %STATUS built-in function to get information on exception/errors. It returns the most recent value set for the program or file status. If a file is specified, %STATUS returns the value contained in the INFDS *STATUS field for the specified file.

The codes in the following tables are placed in the subfield location *STATUS for the file information data structure:

Table 7. Normal Codes

Code	Device1	RC2	Condition
00000			No exception/error.
00002	W	n/a	Function key used to end display.
00011	W,D,SQ	11xx	End of file on a read (input).
00012	W,D,SQ	n/a	No-record-found condition on a CHAIN, SETLL, and SETGT operations.
00013	W	n/a	Subfile is full on WRITE operation.
Note: 1"Device" refers to the devices for which the condition applies. The following abbreviations are used: P = PRINTER; D = DISK; W = WORKSTN; SP = SPECIAL; SQ = Sequential. The major/minor return codes under column RC apply only to WORKSTN files. 2The formula mmnn is used to described major/minor return codes: mm is the major and nn the minor.

Table 8. Exception/Error Codes

Code	Device1	RC2	Condition
01011	W,D,SQ	n/a	Undefined record type (input record does not match record identifying indicator).
01021	W,D,SQ	n/a	Tried to write a record that already exists (file being used has unique keys and key is duplicate, or attempted to write duplicate relative record number to a subfile).
01022	D	n/a	Referential constraint error detected on file member.
01023	D,SQ	n/a	Error in trigger program before file operation performed.
01024	D,SQ	n/a	Error in trigger program after file operation performed.
01031	W,D,SQ	n/a	Match field out of sequence.
01041	n/a	n/a	Array/table load sequence error.
01042	n/a	n/a	Array/table load sequence error. Alternate collating sequence used.
01051	n/a	n/a	Excess entries in array/table file.
01071	W,D,SQ	n/a	Numeric sequence error.
011214	W	n/a	No indicator on the DDS keyword for Print key.
011224	W	n/a	No indicator on the DDS keyword for Roll Up key.
011234	W	n/a	No indicator on the DDS keyword for Roll Down key.
011244	W	n/a	No indicator on the DDS keyword for Clear key.
011254	W	n/a	No indicator on the DDS keyword for Help key.
011264	W	n/a	No indicator on the DDS keyword for Home key.
01201	W	34xx	Record mismatch detected on input.
01211	all	n/a	I/O operation to a closed file.
01215	all	n/a	OPEN issued to a file already opened.
012163	all	yes	Error on an implicit OPEN/CLOSE operation.
012173	all	yes	Error on an explicit OPEN/CLOSE operation.
01218	D,SQ	n/a	Record already locked.
01221	D,SQ	n/a	Update operation attempted without a prior read.
01222	D,SQ	n/a	Record cannot be allocated due to referential constraint error
01231	SP	n/a	Error on SPECIAL file.
01235	P	n/a	Error in PRTCTL space or skip entries.
01241	D,SQ	n/a	Record number not found. (Record number specified in record address file is not present in file being processed.)
01251	W	80xx 81xx	Permanent I/O error occurred.
01255	W	82xx 83xx	Session or device error occurred. Recovery may be possible.
01261	W	n/a	Attempt to exceed maximum number of acquired devices.
01271	W	n/a	Attempt to acquire unavailable device
01281	W	n/a	Operation to unacquired device.
01282	W	0309	Job ending with controlled option.
01284	W	n/a	Unable to acquire second device for single device file
01285	W	0800	Attempt to acquire a device already acquired.
01286	W	n/a	Attempt to open shared file with SAVDS or IND options.
01287	W	n/a	Response indicators overlap IND indicators.
01299	W,D,SQ	yes	Other I/O error detected.
01331	W	0310	Wait time exceeded for READ from WORKSTN file.
Notes: "Device" refers to the devices for which the condition applies. The following abbreviations are used: P = PRINTER; D = DISK; W = WORKSTN; SP = SPECIAL; SQ = Sequential. The major/minor return codes under column RC apply only to WORKSTN files. The formula mmnn is used to described major/minor return codes: mm is the major and nn the minor. Any errors that occur during an open or close operation will result in a *STATUS value of 1216 or 1217 regardless of the major/minor return code value. See Figure 9 for special handling.

The following table shows the major/minor return code to *STATUS value mapping for errors that occur to AS/400 programs using WORKSTN files only. See the |Information Center for more information on major/minor return codes.

Major	Minor	*STATUS
00,02	all	00000
03	all (except 09,10)	00000
03	09	01282
03	10	01331
04	all	01299
08	all	012851
11	all	00011
34	all	01201
80,81	all	01251
82,83	all	01255
Notes: The return code field will not be updated for a *STATUS value of 1285, 1261, or 1281 because these conditions are detected before calling data management. To monitor for these errors, you must check for the *STATUS value and not for the corresponding major/minor return code value.

---

[ Top of Page | Previous Page | Next Page | Table of Contents | I

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 ]