Using Externally Described WORKSTN Files

An RPG WORKSTN file can use an externally described display-device file or ICF-device file, which contains file information and a description of the fields in the records to be written. The most commonly used externally described WORKSTN file is a display file. (For information about describing and creating display files, refer to the DB2® for i section of the Database and File Systems category in the IBM® i Information Center at this Web site - http://www.ibm.com/systems/i/infocenter/.)

In addition to the field descriptions (such as field names and attributes), the DDS for a display-device file are used to:
  • Format the placement of the record on the screen by specifying the line-number and position-number entries for each field and constant.
  • Specify attention functions such as underlining and highlighting fields, reverse image, or a blinking cursor.
  • Specify validity checking for data entered at the display work station. Validity-checking functions include detecting fields where data is required, detecting mandatory fill fields, detecting incorrect data types, detecting data for a specific range, checking data for a valid entry, and processing modules 10 or 11 check-digit verification.
  • Control screen management functions, such as determining if fields are to be erased, overlaid, or kept when new data is displayed.
  • Associate indicators 01 through 99 with command attention keys or command function keys. If a function key is described as a command function key (CF), both the response indicator and the data record (with any modifications entered on the screen) are returned to the program. If a function key is described as a command attention key (CA), the response indicator is returned to the program but the data record remains unmodified. Therefore, input-only character fields are blank and input-only numeric field are filled with zeros, unless these fields have been initialized otherwise.
  • Assign an edit code (EDTCDE) or edit word (EDTWRD) keyword to a field to specify how the field’s values are to be displayed.
  • Specify subfiles.
A display-device-record format contains three types of fields:
  • Input fields. Input fields are passed from the device to the program when the program reads a record. Input fields can be initialized with a default value. If the default value is not changed, the default value is passed to the program. Input fields that are not initialized are displayed as blanks into which the work-station user can enter data.
  • Output fields. Output fields are passed from the program to the device when the program writes a record to a display. Output fields can be provided by the program or by the record format in the device file.
  • Output/input (both) fields. An output/input field is an output field that can be changed. It becomes an input field if it is changed. Output/input fields are passed from the program when the program writes a record to a display and passed to the program when the program reads a record from the display. Output/input fields are used when the user is to change or update the data that is written to the display from the program.

If you specify the keyword INDARA in the DDS for a WORKSTN file, the RPG program passes indicators to the WORKSTN file in a separate indicator area, and not in the input/output buffer.

For a detailed description of an externally-described display-device file and for a list of valid DDS keywords, refer to the DB2 for i section of the Database and File Systems category in the IBM i Information Center at this Web site - http://www.ibm.com/systems/i/infocenter/.

Figure 1 shows an example of the DDS for a display-device file.

Figure 1. Example of the Data Description Specifications for a Display Device File
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ..*
AAN01N02N03T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++++*
A** ITEM MASTER INQUIRY
A                                      REF(DSTREF)  1 
A          R PROMPT                    TEXT('Item Prompt Format')
A  73N61                               OVERLAY  2 
A                                      CA03(98 'End of Program')  3 
A                                  1  2'Item Inquiry'
A                                  3  2'Item Number'
A            ITEM      R        I  3 15PUTRETAIN  4 
A  61                                  ERRMSG('Invalid Item Number' 61) 5 
A          R RESPONSE                  TEXT('Response Format')
A                                      OVERLAY  2 
A                                      LOCK  6 
A                                  5  2'Description'
A            DESCRP    R           5 15
A                                  5 37'Price'
A            PRICE     R           5 44
A                                  7  2'Warehouse Location'  7 
A            WHSLOC    R           7 22
A                                  9  2'On Hand'
A            ONHAND    R           9 10
A                                  9 19'Allocated'  8 
A            ALLOC     R           9 30
A                                  9 40'Available'
A            AVAIL     R           9 51
A*
This display device file contains two record formats: PROMPT and RESPONSE.
 1 
The attributes for the fields in this file are defined in the DSTREF field reference file.
 2 
The OVERLAY keyword is used so that both record formats can be used on the same display.
 3 
Function key 3 is associated with indicator 98, which is used by the programmer to end the program.
 4 
The PUTRETAIN keyword allows the value that is entered in the ITEM field to be kept in the display. In addition, the ITEM field is defined as an input field by the I in position 38. ITEM is the only input field in these record formats. All of the other fields in the record are output fields since position 38 is blank for each of them.
 5 
The ERRMSG keyword identifies the error message that is displayed if indicator 61 is set on in the program that uses this record format.
 6 
The LOCK keyword prevents the work-station user from using the keyboard when the RESPONSE record format is initially-displayed.
 7 
The constants such as ‘Description’, ‘Price’, and ‘Warehouse Location’ describe the fields that are written out by the program.
 8 
The line and position entries identify where the fields or constants are written on the display.