Tuesday, September 7, 2021

Finding which display file field and record format the cursor is in

display field name retrieval

It has been a long time since I last wrote a post about display files, but I thought this was worth sharing. I was asked how you could determine which field the cursor is in when the prompt key is pressed. The prompt key is the SAA standard F4 key.

The person had found a very old program where the position of the cursor was returned as its location on the screen, as the row and column numbers. If this method was use they would have to determine the location of each field in the display file's record format.

I was asked is there an easier way?

Fortunately there has been an easier way for many releases using the RTNCSRLOC keyword in the display file.

I created a very simple display file, the DDS source code for this is:

01 A                                      INDARA
02 A                                      CA03(03 'Exit')
03 A          R SCREEN
04 A                                      CA04(04 'Prompt')
05 A                                      RTNCSRLOC(&ZRCDFMT &ZFIELD)
06 A            ZRCDFMT       10A  H
07 A            ZFIELD        10A  H
08 A                                  2  2'First  .'
09 A            FIRST          1A  B  2 11
10 A                                  3  2'Second .'
11 A            SECOND    R        B  3 11REFFLD(FIRST *SRC)
12 A                                  4  2'Third  .'
13 A            THIRD     R        B  4 11REFFLD(FIRST *SRC)
14 A            ZWHERE        50A  O  6  2

The important lines to notice are:

Line 5: The Return Cursor Location keyword, RTNCSRLOC, contains two fields.

  1. Record format name
  2. Field name

Both field names have to start with the ampersand character ( & ).

Lines 6 and 7: The definitions for these two fields. They both have to be ten long, and are defined as hidden, "H" in the Usage column.

Line 14: The record format and field names will be displayed in this field.

The RPG program is equally simple.

01  **free
02  ctl-opt option(*nodebugio:*srcstmt) ;

03  dcl-f TESTDSPF workstn indds(Dspf) ;

04  dcl-ds Dspf qualified ;
05    Exit ind pos(3) ;
06    Prompt ind pos(4) ;
07  end-ds ;

08  dow (1 = 1) ;
09    exfmt SCREEN ;

10    if (Dspf.Exit) ;
11      leave ;
12    elseif (Dspf.Prompt) ;
13      ZWHERE = 'Rec fmt = ' + ZRCDFMT + ' Field = ' + ZFIELD ;
14    endif ;
15  enddo ;

Line 1: These days I always code my programs in totally free RPG.

Line 2: I add these control options to all of my RPG programs.

Line 3: The display file definition. Notice that I have defined an indicator data structure to use with this file.

Lines 4 – 7: The indicator data structure with indicators 3 and 4 defined. I use this rather than *IN03 or *INKC as it allows me to give the indicator a name related to its function.

Lines 10 and 11: If the F3 key was pressed I leave the Do-loop, which ends the program.

Lines 12 and 13: When the F4 key is pressed the values in ZRCDFMT and ZFIELD will be displayed in the ZWHERE field.

When I call the program the following screen displayed:

First  .  
Second .  
Third  .  

When I press the F4 key with the cursor in the first field I see:

First  .  
Second .  
Third  .  

Rec fmt = SCREEN     Field = FIRST

I move the cursor down to the second field, and press the F4 key:

First  .  
Second .  
Third  .  

Rec fmt = SCREEN     Field = SECOND

Move down to the next field, and press F4.

First  .  
Second .  
Third  .  

Rec fmt = SCREEN     Field = THIRD

This time I move the cursor below the third field, into a place where there is no field, and press F4 again:

First  .  
Second .  
Third  .  
Rec fmt = SCREEN     Field =

No field name is returned as the cursor is not in a field.

It would be easy to use the record format and field names to condition the calls to the prompt programs or procedures.

Another advantage of using this method rather than the location (row and column) is I can move the fields to other parts of the screen, there is no need to change the program as the same field names will be return passed to the program.


This article was written for IBM i 7.4, and should work for some earlier releases too.


  1. This is such a cool function, old but still powerful. I once wrote a help text app using this by pulling in the display file name, rcdfmt name and field name as keys a to a file for entering app help text using SEU and entering special characters to highlight and underline fields. The IBMi is still a great machine and OS.

  2. Maybe you should mention the SFLCSRRRN(&RecNo) return key for subfiles as well.
    That's really cool.

  3. Thank you for sharing. This is cool!

  4. Very powerful and simplified,thanks for sharing


To prevent "comment spam" all comments are moderated.
Learn about this website's comments policy here.

Some people have reported that they cannot post a comment using certain computers and browsers. If this is you feel free to use the Contact Form to send me the comment and I will post it for you, please include the title of the post so I know which one to post the comment to.