Display Files WORKSTN

Display Files (WORKSTN)

A WORKSTN file is an interactive 5250-style screen. The screen itself is described in a separate .dspf source file and compiled by dspfc (the OpenDSPF compiler); OpenRPG then reads the compiled descriptor and gives the RPG program a variable for every field on the screen.

The Two-Step Compile

dspfc CUSTMENU.dspf     # produces CUSTMENU.dspfd and CUSTMENU_dspf.h
rpgc  myprogram.rpgle   # reads CUSTMENU.dspfd, links the screen runtime

rpgc looks for NAME.dspfd in the same directory as the RPG source, trying the uppercase name first and then the lowercase one. If it finds no descriptor the program still compiles, but the screen opcodes become comments — check the generated C++ if a screen silently does nothing.

Screen rendering uses curses, and rpgc adds the right linker flag for the platform automatically (-lncurses, or -lpdcurses on Windows). You do not pass anything extra on the command line.

Declaring the File

DCL-F CUSTMENU WORKSTN;

Every field in every record format of the display file becomes a program-scope variable with the field's own name. Character, date, time and timestamp fields become strings; binary fields become integers; the rest become numeric.

Two things worth knowing about those variables:

• HIDDEN fields get a variable too. Hidden means "not rendered", not "no data" — SFLRCDNBR is the common case.
• DFTVAL('text') seeds the initial value, so the field displays that text before the program ever assigns to it.

EXFMT — Write and Read in One Step

EXFMT displays a record format and waits for the user:

DCL-F CUSTMENU WORKSTN;
DCL-S choice CHAR(1);

EXFMT MAINMENU;

IF *IN03;
  DSPLY 'F3 pressed — exiting';
ELSE;
  choice = OPTION;
  DSPLY ('You selected option: ' + choice);
ENDIF;

Function keys defined in the display file set their indicators, so the program tests *IN03, *IN12 and so on after the EXFMT returns. Only input, both and hidden fields are copied back — the program already knows what it sent out.

WRITE and READ

WRITE renders a record format without waiting, and READ sends the current field values to the screen and reads the user's input back. EXFMT is the combination of the two and is what most programs use.

Subfiles

A subfile is a scrollable list. It needs two record formats in the display file — an SFL record holding one row's fields, and an SFLCTL record that controls the display. The RPG side is three steps:

DCL-F CUSTLIST WORKSTN;
DCL-S i INT(10);

WRITE CUSTCTL;            // 1. clears the subfile

FOR i = 1 TO 5;           // 2. one WRITE per row
  CUSTNO   = ('C' + %CHAR(i));
  CUSTNAME = ('Customer ' + %CHAR(i));
  CUSTBAL  = (i * 1000.00);
  WRITE CUSTSFL;
ENDFOR;

EXFMT CUSTCTL;            // 3. displays it as a scrollable table

IF NOT *IN03 AND NOT *IN12;
  DSPLY ('You selected row: ' + %CHAR(SFLRCDNBR));
ENDIF;

Step	Opcode	Effect
1	WRITE on the SFLCTL record	Clears the subfile's row store
2	WRITE on the SFL record	Appends one row
3	EXFMT on the SFLCTL record	Displays the scrollable list

At runtime the user scrolls with the arrow keys and Page Up/Page Down, and exits with Enter or any defined function key. If the SFLCTL record has a field named SFLRCDNBR, the 1-based relative record number of the selected row is written into it.

READC — Read Changed Records

READC walks the rows the user actually modified:

READC CUSTSFL;
DOW NOT %EOF(CUSTSFL);
  IF OPTION = '4';
    DSPLY ('Deleting ' + %TRIM(CUSTNO));
  ENDIF;
  READC CUSTSFL;
ENDDO;

%EOF(recordformat) becomes true when there are no more changed rows. Unlike EXFMT, READC copies back every field of the row including output-only ones — that is how the program knows which row's option was typed into.

UPDATE — Rewrite the Current Row

After a READC, UPDATE writes the field variables back into that same row:

READC CUSTSFL;
DOW NOT %EOF(CUSTSFL);
  OPTION = ' ';           // clear the option field
  UPDATE CUSTSFL;
  READC CUSTSFL;
ENDDO;

Unlike a DISK UPDATE, no key is involved — it targets whichever row READC last returned.

For the display-file side of all this — record formats, field keywords, literals, function keys, SFLPAG/SFLSIZ, conditioning indicators, EDTCDE and EDTWRD — see the OpenDSPF User's Guide in OpenDSPF/docs/GUIDE.md.