Mapping DSPF Data Structures

DDS can be created to map the DSPF I/O feedback DS.

Externally Defined INFDS

A simple way of defining a data structure is to reference an external file description. The DDS below describes the fields of the I/O feedback data structure for display files. Making a map of the I/O feedback simplifies defining the DS subfields to an RPG program. It also provides consistency. Adopting the map as a standard means that all programs using the external map are coded to respond to the same field names. This makes it easy to interpret the code when it is time to maintain a suite of programs.

      ********************************************************************
      * File Name    - SCDSPFPF                                          *
      *                                                                  *
      * Function     - This file was designed to serve as an external    *
      *                data structure to define the file information     *
      *                data structure for display files.                 *
      *                                                                  *
      * Programmer   - Steve Croy        99/99/99                        *
      ********************************************************************
      ********************************************************************
      *                   Modification log                               *
      *                                                                  *
      *   Date    Programmer      Description                            *
      *                                                                  *
      ********************************************************************
      *===============================================================
      * FILE INFORMATION DATA STRUCTURE: FRO DISPLAY FILE
      *===============================================================
     A          R RSCDSPF                   TEXT('DSPF INFDS')
     A            FILNAM         8          COLHDG('FILE' 'NAME')
     A            DSPOPN         1          COLHDG('FILE' 'OPEN')
     A            DSPEND         1          COLHDG('FILE' 'END')
     A            DSPSTS         5S 0       COLHDG('FILE' 'STS')
     A            DSCODE         6          COLHDG('RPG' 'OPCODE')
     A            DSRRTN         8          COLHDG('RPG' 'ROUTINE')
     A            DSRSTM         8          COLHDG('RPG' 'STATMNT')
     A            FMTNAM         8          COLHDG('FORMAT' 'NAME')
     A            DSPMSG         7          COLHDG('CPF' 'MSG')
     A            DSPINS         4          COLHDG('PGM' 'INSTR')
     A            DSUN01        10          COLHDG('UNDEFINED')
     A            DSPSIZ         4S 0       COLHDG('DSP' 'SIZE')
     A            DSPINP         2S 0       COLHDG('INPUT')
     A            DSPOUT         2S 0       COLHDG('OUTPUT')
     A            DSPMOD         2S 0       COLHDG('MODE')
     A            DSUN02         4          COLHDG('UNDEFINED')
     A            DSPODP         2S 0       COLHDG('ODP' 'TYPE')
     A            DSXNAM        10          COLHDG('XT' 'NAME')
     A            DSPLIB        10          COLHDG('FILE' 'LIB')
     A            DSSPLF        10          COLHDG('SPLF' 'NAME')
     A            DSSPLB        10          COLHDG('SPLF' 'LIB')
     A            DSSPL#         4B 0       COLHDG('SPLF' 'NBR')
     A            DSPLEN         4B 0       COLHDG('RECORD' 'LENGTH')
     A            DSUN03         2          COLHDG('UNDEFINED')
     A            DSPMBR        10          COLHDG('FILE' 'MEMBER')
     A            DSUN04         8          COLHDG('UNDEFINED 01')
     A            DSPTYP         4B 0       COLHDG('FILE' 'SUBTYPE')
     A            DSUN05         3          COLHDG('UNDEFINED 01')
     A            DSPLIN         4B 0       COLHDG('NBR OF' 'LINES')
     A            DSPCOL         4B 0       COLHDG('COLUMNS' 'DSP')
     A            DSPRCD         8B 0       COLHDG('RECORD' 'COUNT')
     A            DSPACC         2          COLHDG('ACCESS' 'TYPE')
     A            DSPDUP         1          COLHDG('ALLOW' 'DUPE')
     A            DSPSRC         1          COLHDG('SOURCE' 'FILE')
     A            DSUFCB        10          COLHDG('USER' 'FC' 'BLK')
     A            DSFBOV        10          COLHDG('FC' 'BLK' 'OVR')
     A            DSVLID         4B 0       COLHDG('VOL' 'ID' 'OVR')
     A            DSBKIO         4B 0       COLHDG('BLK' 'IO')
     A            DSPOFL         4B 0       COLHDG('OVERFLOW' 'LINE')
     A            DSBKOO         4B 0       COLHDG('BLK' 'IO' 'OFL')
     A            DSUN06         5          COLHDG('UNDEFINED')
     A            DSPDEV        10          COLHDG('PROGRAM' 'DEVICE')
     A            DSFBST         4B 0       COLHDG('FC' 'BLK' 'STS')
     A            DSUN07         2          COLHDG('UNDEFINED')
     A            DSPOST         4B 0       COLHDG('DB' 'OPN' 'STS')
     A            DSFLAG         1          COLHDG('FILE' 'FLAG')
     A            DSOPID         2          COLHDG('OPEN' 'ID')
     A            DSMAXR         4B 0       COLHDG('MAX' 'RECORDS')
     A            DSUN08       151          COLHDG('UNDEFINED')
     A            KEYPRESSED     1          COLHDG('FUNCTION' 'KEY')
     A            ROW            1          COLHDG('CURSOR' 'ROW')
     A            COL            1          COLHDG('CURSOR' 'COL')
     A            DSUN09         6          COLHDG('UNDEFINED')
     A            SFRRN#         4B 0       COLHDG('SFL' 'RRN')

Using the Mapped DS

The code snippetts below illustrate using the mapped INFDS. The DSPDS represents the display file INFDS. The fields are all available to the program with one line of code--the reference to the externally defined data area, SCDSPFPF. Function key representations are also mapped externally.

The code on the SELECT statement, WHEN KEYPRESSED, is easy to interpret. Byte 369 of the INFDS is the AID-byte (Attention ID). Naming the field KEYPRESSED, makes the code in the program read similar to English syntax.

     FSC0200DF  CF   E             WORKSTN                                                          
     F                                     SFILE(SC0200S1:RRNSI)                                    
     F                                     INFDS(DSPDS)                                             
      *================================================================                             
     D FunctionKey   E DS                  EXTNAME(SCKEYSPF) qualified          Function keys       
     D PGMDS         ESDS                  EXTNAME(SCPSTSPF)                    Pgm status map      
     D DSPDS         E DS                  EXTNAME(SCDSPFPF)                    Display INFDS       
     D MACDS         E DS                  EXTNAME(SCFUNCPF) INZ                Key map             
     D OPTDS         E DS                  EXTNAME(SCOPTNPF) INZ                Option map          
     D FUNCT         E DS                  EXTNAME(SCMACRPF) INZ                Macro map           
     D GATEPR        E DS                  extname(SCGATEPF)                                        
     D BEFORE        E DS                  extname(SCGATEPF) prefix(b_)   inz                       
     D AFTER         E DS                  extname(SCGATEPF) prefix(a_)   inz  
.
.
.
           SELECT;                                                                                  
           WHEN KeyPressed = FunctionKey.ENTER;                                                              
              EXSR @ENTER;                                                                          
           WHEN KeyPressed = FunctionKey.ROLLUP;                                                             
              EXSR @LOAD;                                                                           
           WHEN KeyPressed = FunctionKey.ROLLDN;                                                             
              EXSR @DOWN;                                                                           
           WHEN SUBOP = 'CALL';                                                                     
              EXSR @CALLS;                                                                          
           WHEN FUNCT = 'EXIT';                                                                     
              QUIT();                                                                               
           WHEN FUNCT = 'RESET';                                                                    
              EXSR @RESET;                                                                          
           WHEN FUNCT = 'PROMPT';                                                                   
              EXSR @PROMPT;                                                                         
           WHEN FUNCT = 'MORE';                                                                     
              DisplayKeys(cmdkey: z$key1: z$key2: M);                                               
           WHEN FUNCT = 'MOREOPT';                                                                  
              DisplayOptions(option: z$opt1: z$opt2: O);                                            
        ENDSL;                                              

Standards for DS

Making the externally defined map a standard practice can streamline application development and improve readability. It can also aid maintenance. If it happens the same way in each interactive program, it should not be a mystery to whoever inherits the maintenance project, regardless of the program's original author. The program below uses the same externally defined map. The in-line case structure (SELECT WHEN) may perform different operations, but the test for the KEYPRESSED and refernce to the FUNCTIONKEY is identical.

     FSC0320DF  CF   E             WORKSTN                                                          
     F                                     SFILE(SC0320S1:RRNSI)                                    
     F                                     INFDS(DSPDS)                                             
      *================================================================                             
     D FUNCTIONKEY   E DS                  EXTNAME(SCKEYSPF) qualified          Function keys       
     D PGMDS         ESDS                  EXTNAME(SCPSTSPF)                    Pgm status map      
     D DSPDS         E DS                  EXTNAME(SCDSPFPF)                    Display INFDS       
     D MACDS         E DS                  EXTNAME(SCFUNCPF) INZ                Key map             
     D OPTDS         E DS                  EXTNAME(SCOPTNPF) INZ                Option map          
.
.
.
              SELECT;                                                                               
              WHEN KeyPressed = functionKey.ENTER;                                                  
                 EXSR @ENTER;                                                                       
              WHEN KeyPressed = functionKey.ROLLUP;                                                 
                 EXSR @LOAD;                                                                        
              WHEN KeyPressed = functionKey.ROLLDN;                                                 
                 EXSR @DOWN;                                                                        
              WHEN KeyPressed = functionKey.F23;                                                    
                   DisplayOptions(option: z$opt1: z$opt2: O);                                       
              WHEN KeyPressed = functionKey.F24;                                                    
                   DisplayKeys(cmdkey: z$key1: z$key2: M);                                          
              WHEN Function = 'EXIT';                                                               
                 QUIT();                                                                            
              WHEN Function = 'CANCEL';                                                             
                 EXSR @return;                                                                      
              WHEN Function = 'RESET';                                                              
                 EXSR @RESET;                                                                       
              WHEN Function = 'PROMPT';                                                             
                 EXSR @PROMPT;                                                                      
                 IF promptDta <> *blanks;                                                           
                    PromptDta = *blanks;                                                            
                    EXSR @RESET;                                                                    
                 ENDIF;                                                                             
              WHEN Function = 'HELP';                                                               
                 HelpText(ThisPgm:fmt);                                                             
              WHEN SUBOP = 'CALL';                                                                  
                 EXSR @CALLS;                                                                       
              WHEN Function = 'CMDLINE';                                                            
                 CommandLine();                                                                     
           ENDSL;