07
Tue, May
2 New Articles
  1. You are here:  
  2. Home
  3. IT Infrastructure
  4. IT Infrastructure - Other
  5. Unravel the Display File Maze

Unravel the Display File Maze

Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Like opening Russian nesting Matryoshka dolls, studying an AS/400 interactive job reveals many layers. In the outermost layer, a programmer sends DDS source code to the Create Display File (CRTDSPF) command. In the middle layer, display file objects hold intermediate binary structures. In the innermost layer, data management builds 5250 data streams on the fly. Display files in the middle are neither DDS source code nor 5250 data streams. You can look at display file structures with the Retrieve Display File Description (QDFRTVFD) API.

Sometimes, applications need information about display files. QDFRTVFD provides a base for this. With this API, you can build custom tools to do the following tasks:

• Print screen pictures

• Re-create lost DDS source code

• Retrieve subfile size (SFLSIZ) and subfile page size (SFLPAG) numbers to condition subfile processing logic

• Retrieve row and column positions of screen fields to condition program logic

• Document how indicators 01 to 99 are used

• Convert a display file to another form, such as User Interface Manager (UIM) source and Dynamic Screen Manager (DSM) API calls

• Provide a Common Gateway Interface (CGI) program with a source of screen information for dynamic HTML

• Build cross-reference lists of objects used by display files, including the names of message files, printer files, panel groups, documents, folders, search indexes, bookshelves, and other “help” records


QDFRTVFD returns the display file structures directly into a program variable, not into a user space. QDFRTVFD takes five parameters:

• Receiver variable (Output)

• Length of the receiver variable in a Binary(4) variable (Input)

• Receiver format name in a Character(8) variable (the only format available is DSPF0100) (Input)

• Qualified display file name in a Character(20) variable (Input)

• Standard API error data structure (Input/Output)

This parameter list seems simple, but this simplicity is deceiving! Inside the receiver variable lurks a beastly, complex format. I had to reread the System API Reference documentation untold times, hold it up to the light, turn it sideways, and shout, “Eureka!” in the bathtub until I made sense of this thing. Unlike other APIs that return data in fixed offsets, QDFRTVFD returns data in offsets relative to prior offsets. To arrive at data you want, you have to add a series of offsets. Traditional RPG language, with fixed “from” and “through” I-specs and D-specs, isn’t the best choice for this (although recursion and pointer arithmetic help). I rely on recursion and pointer arithmetic in this article’s RPG IV program, DSP001R. You can download this program and associated command, Display a Display File (DSPDSPF), from the MC Web page at www.midrangecomputing.com/mc. Inside the RPG IV program are five subprocedures that you can copy to start building new functions based on QDFRTVFD.

You Ought to Be in Pictures

The DSPDSPF command prints a spool file. It takes five parameters:

• Display file name (FILE). This is the name of a display file object you want to print. You need only the *FILE object, not the DDS source code.

• Print pictures or hexadecimal dumps (TYPE). A value of *PIC (the default) prints all screen pictures from the display file, one screen per page. A value of *HEX prints all structures from the file in hexadecimal dumps.

• Lines per page (LINES). The default is 66. The page overflow line number is equal to this number.

• Lines per inch (LPI). The default is 6.

• Characters per inch (CPI). The default is 10. The combination of LINES, LPI, and CPI lets you fine-tune the spool file size and page breaks for documentation.

Figure 1 shows some sample DDS source code from a window in my users’ application. It consists of input (I), output (O), and both (B) fields; a multiple-choice selection field with mnemonics; constants; and a window title.

Figure 2 shows the DSPDSPF output TYPE(*PIC) over the compiled display file object in Figure 1. You can see the constants, window title, choice mnemonic underlines, choice field slashes, and input field underlines. One picture is in *DS3 dimensions (24x80 mode), and one picture is in *DS4 dimensions (27x132 mode). The area below each


picture lists I/O field names, row/column locations, keyboard shift attributes, field lengths, and I/O buffer positions. *NOLOC appears for hidden (H) and program-to-system (P) field locations. This command makes a handy documentation tool. Try running it over one of your own display files.

Figure 3 shows the first page of DSPDSPF output TYPE(*HEX) over the compiled display file object in Figure 1. This is the raw data from the QDFRTVFD receiver variable. The left column lists offsets denoting the start of each structure. In this example, the offsets begin with 0, 10, 13, 18, 1D, etc. The “dump area” in the middle breaks apart each structure onto separate lines. The angle brackets (< and >) delimit the start and end of each structure. To the right, characters are printed for dump bytes greater than X‘40’. On the far right is the name and description of each structure in the dump, as named in System API Reference: OS/400 File APls. See this book for the detailed layout of each structure.

If you begin writing a QDFRTVFD-based utility, this TYPE(*HEX) output can help you understand and locate structures in your display files. Use the structure names in the dump to find things in System API Reference. Likewise, use the book as a road map to find things in the dump. DSPDSPF does the hard part for you, resolving the offsets of structures through recursion. Your role is to choose the correct set of offsets to arrive at data you want.

Pointer arithmetic is key here. The RPG IV program DSP001R contains five procedures containing pointer arithmetic to aid navigating through offsets:

• Procedure I2. The input parameter is an absolute offset into the QDFRTVFD receiver variable. The output value is the Binary(2) signed integer value at that location.

• Procedure I4. The input parameter is an absolute offset into the QDFRTVFD receiver variable. The output value is the Binary(4) signed integer value at that location.

• Procedure U1. The input parameter is an absolute offset into the QDFRTVFD receiver variable. The output value is the Binary(1) unsigned integer value at that location.

• Procedure BIT. The input parameters are an absolute offset into the QDFRTVFD receiver variable; they are one byte of “mask” bits.

The output value is an indicator variable and is set to *ON if the byte value at the input location contains any “mask” bits.

• Procedure GET. The input parameters are an absolute of set into the QDFRTVFD receiver variable; they are a length. The output value is the data substring at that location.

Figure 4 contains an example in pseudocode using some of these procedures. Suppose I wanted to get the window title text from the compiled display file object in Figure 1. Using System API Reference as a road map, Figure 4 shows the travel route to that destination.

Comments on the right denote absolute offset results in hexadecimal. Try following this trail of offsets through the dump in Figure 3. Point your finger to offsets 8, 1D, 5D, 7D, and so on. Eventually, you’ll arrive at offset X‘114’. You’ll see it begins the 10-byte value DISABILITY. Once you understand how these offsets add together, you can experiment with a copy of the five RPG IV procedures in DSP001R to locate more things.

The Organization of Structures

QDFRTVFD structures fall into five basic categories.


File-level structures occur at the beginning of the receiver variable. Values that you’ll likely use here include the number of screen sizes, the number of record formats, and a record format table. Entries in the record format table contain offsets to the start of each record section.

A set of record-level structures occurs for each record in the file. Values that you’ll likely use here include the number of fields and field indexing tables. Entries in the field indexing tables contain offsets to the start of each field section.

A set of field-level structures occurs for each field in each record. Values that you’ll likely use here include the field type.

A set of where-used structures occurs at the end of the QDFRTVFD receiver variable. There is a one-to-one correspondence between a where-used structure and a file, record, and field structure. SDA option 3 (Test display file) and the Display File Field Description (DSPFFD) command use these structures for I/O buffer positions. Workstation data management does not use them. Interestingly, display files in OS/400 libraries do not contain the where-used structures, which may explain why you can’t use SDA option 3 and DSPFFD on them.

Nested sets of keyword category structures occur throughout the QDFRTVFD receiver variable for each file, record, and field structure. They contain DDS keyword values that require composite structures. You can study the RPG IV program DSP001R for examples of loops within loops within loops that scan through nests of keyword category structures.

Working Your Way Through

Even if you have no plans to plunge into display file internals, the screen pictures in DSPDSPF output TYPE(*PIC) can still help you quickly document an application. Users will like the pictures.

Programmers will also like the I/O buffer layouts. If, on the other hand, you have the patience to navigate to a new target in display file structures, the DSPDSPF output TYPE(*HEX) can help you visualize and simplify the layout of QDFRTVFD structures as you work your way through its many layers.

References and Related Materials

OS/400 File APIs (SC41-5857, CD-ROM QB3AMI02)

A DSPSIZ(*DS3 *DS4)

A R SCREEN_01

A *DS3 WINDOW(3 11 9 27)

A *DS4 WINDOW(3 11 5 76)

A WDWTITLE((*TEXT 'DISABILITY'))

A CF03

A CF12

A DIS_CUSTOM 9A P

A SHOW_AUTO 1Y 0H

A SHOW_WORK 1Y 0H

A SHOW_TERM 1Y 0H

A SHOW_DIS 1Y 0H

A 2 2'Claimant:'

A *DS4 1 6

A CLAIM_NAME 14A I 2 13

A *DS4 1 17

A 3 2'Employer:'

A *DS4 2 6

A EMPLO_NAME 14A O 3 13

A *DS4 2 17

A 4 2'Provider:'

A *DS4 3 6

A PROVD_NAME 14A B 4 13

A *DS4 3 17

A OPTIONS 2Y 0B 7 2MLTCHCFLD((*NUMROW 2))

A CHOICE(1 '>Auto NF')

A CHCCTL(1 &SHOW_AUTO)

A CHOICE(2 '>Workers')

A CHCCTL(2 &SHOW_WORK)


A CHOICE(3 'Long >Term')

A CHCCTL(3 &SHOW_TERM)

A CHOICE(4 &DIS_CUSTOM)

A CHCCTL(4 &SHOW_DIS)

A *DS4 3 46 Display file . . . . . . : QGPL/FIGURE1 Page: 1
Record . . . . . . . . . : SCREEN_01
Size identifier . . . . : *DS3
Printed on . . . . . . . : 10/13/1999 6:16:39

.........DISABILITY..........
: :

: Claimant: IIIIIIIIIIIIII :
: Employer: OOOOOOOOOOOOOO :
: Provider: BBBBBBBBBBBBBB :
: :

: :

: / Auto NF / Long Term :
: / Workers / OOOOOOOOO :
: :

:...........................:

Field Location Length Input Output
DIS_CUSTOM (*NOLOC) A(9) 1-9
SHOW_AUTO (*NOLOC) Y(1,0) 1-1 10-10
SHOW_WORK (*NOLOC) Y(1,0) 2-2 11-11
SHOW_TERM (*NOLOC) Y(1,0) 3-3 12-12
SHOW_DIS (*NOLOC) Y(1,0) 4-4 13-13
CLAIM_NAME (2,13) A(14) 5-18
EMPLO_NAME (3,13) A(14) 14-27
PROVD_NAME (4,13) A(14) 19-32 28-41
OPTIONS (7,2) Y(2,0) 33-34 42-43

Display file . . . . . . : QGPL/FIGURE1 Page: 2
Record . . . . . . . . . : SCREEN_01
Size identifier . . . . : *DS4
Printed on . . . . . . . : 10/13/1999 6:16:39

..................................DISABILITY..................................
: Claimant: IIIIIIIIIIIIII :
: Employer: OOOOOOOOOOOOOO :
: Provider: BBBBBBBBBBBBBB / Auto NF / Long Term :
: / Workers / OOOOOOOOO :
: :

:............................................................................:

Field Location Length Input Output
DIS_CUSTOM (*NOLOC) A(9) 1-9
SHOW_AUTO (*NOLOC) Y(1,0) 1-1 10-10
SHOW_WORK (*NOLOC) Y(1,0) 2-2 11-11
SHOW_TERM (*NOLOC) Y(1,0) 3-3 12-12
SHOW_DIS (*NOLOC) Y(1,0) 4-4 13-13
CLAIM_NAME (1,17) A(14) 5-18
EMPLO_NAME (2,17) A(14) 14-27
PROVD_NAME (3,17) A(14) 19-32 28-41
OPTIONS (3,46) Y(2,0) 33-34 42-43 Display file: QGPL/FIGURE1 Date: 10/13/1999 6:28:58
Page: 1

_______________________________________________ ________________

0 1 2 3 4 5 6 7 8 9 A B C D E F 0123456789ABCDEF

0: <00 00 0B 2D 00 00 0B 2D 00 1D 00 01 00 00 02 00 | | QDFFBASE: Base File Section

10: 00 00 25> | |

13: <03 00 00 00 98 04 00 00 00 98> | q q | QDFFSCRA: Screen Size Table

1D: <00 00 00 | | QDFFINFO: File Header
Section

20: 40 00 00 06 50 00 00 07 96 00 00 00 50 00 01 00 | & o & |

30: 01 00 00 00 01 00 01 00 01 00 00 00 00 00 01 00 | |

40: 24> | |


Figure 1: This is sample DDS source code for a window with two border sizes.

Figure 2: This is DSPDSPF output TYPE(*PIC) over Figure 1’s display file.

41: <00 00 04 40 00 00 02 0D 00 01 01 07 00 00 00 | | QDFFDPDD: Display-File-
Level Device-Dependent Secti 50: 18 00 00 00 00 00 00 00 00 00 00 00 00> | |

5D: Table

60: C5 C5 D5 6D F0 F1 40 00 00 00 00 00 60> |EEN_01 - |

6D: Table

70: F7 F5 F8 C1 F5 F1 F8 F7 C1 F6 00 00 00> |758A5187A6 |

7D: <00 00 01 | | QDFFRINF: Record Header
Section

80: 40 00 00 00 E0 00 00 00 00 00 01 02 00 00 0C 00 | |

90: 22 00 2B 00 00 00 00 00 00 00 1E> | |

9B: <00 00 00 A2 00 | s | QDFFRDPD: Display-Record-
Level Device-Dependent Sec A0: 07 00 03 00 00 00 00 20 10 00 00 00 00 00 60 00 | - |

B0: 00 00 28 FF FF 00 00 00 40 00 00 00 58> | |

BD: <00 00 00 | | QDFFXRDP: Display-Record-
Level Device-Dependent Ext C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | |

D0: 00 00 00 00 00> | |

D5: <00 01> | | QDFFCOSA: Keyword Category
Displacement String D7: <17 00 5E 00> | ; | QDFFCCOA: Keyword Category
Displacement String Entr DB: <00 02> | | QDFKMRPR: Miscellaneous
Record-Level Structure DD: <08 00 01 | | QDFKMRWP: Miscellaneous
Record-Level Keywords E0: 00 18> | |

E2: | H | QDFKWDTA: Window Data Array
Structure

EE: Structure

F0: 00 03 00 0B 00 05 00 4C 00 00> | < |

FA: <09 00 01 00 1F 00 | | QDFKWDWTTL: Window Title
Structure

100: 00 00 00 00 00 00 00 1A 00 0A 00 00 00 00 00 00 | |

110: 00 00 00 00 C4 C9 E2 C1 C2 C9 D3 C9 E3 E8 00> | DISABILITY |

11F: <02 | | QDFFRCTB: Row-Column Table

120: 01 08 1B 40 00> | |

125: Entry

130: 01 02 0C 03 01 03 0C 04 01 04 0C 07 01> | |

13D: <01 05 04 | | QDFFRCTB: Row-Column Table

140: 47 00 00> |Ü |

143: Entry

150: 10 02 05 02 10 03 05 03 10 03 2D 00 00> | |

15D: <00 00 01 | | QDFFFITB: Field Indexing
Table

160: 40 00 01 00 09 00 00 01 60 00 01 00 01 00 00 01 | - |

170: 80 00 01 00 01 00 00 01 A0 00 01 00 01 00 00 01 |[.radical] Ê |

180: C0 00 01 00 01 00 00 01 E0 00 01 00 09 00 00 02 |{ |

190: 10 00 01 00 0E 00 00 02 34 00 01 00 09 00 00 02 | |

1A0: 64 00 01 00 0E 00 00 02 84 00 01 00 09 00 00 02 |¥ d |

1B0: B4 00 01 00 0E 00 00 02 D8 00 01 00 02> |ü Q |

1BD: <00 20 07 | | QDFFFINF: Field Header
Section

1C0: 00 00 00> | |

1C3: | | QDFFFNAM: Named Field
Header Table

1CF: <00 | | QDFFFDPD: Display-Field-
Level Device-Dependent Sect 1D0: 20 00 18 00 00> | |

1D5: <00 00 00 01 00 00 00 00> | | QDFFXFDP: Field-Dependent
Extension Structure 1DD: <00 20 06 | | QDFFFINF: Field Header
Section

1E0: 00 00 00> | |

1E3: <00 00 00 09 00 01 00 03 00 00 00 12> | | QDFFFNAM: Named Field
Header Table

1EF: <00 | | QDFFFDPD: Display-Field-
Level Device-Dependent Sect 1F0: 20 00 18 00 00> | |

1F5: <00 00 00 02 00 00 00 00> | | QDFFXFDP: Field-Dependent
Extension Structure 1FD: <00 20 06 | | QDFFFINF: Field Header
Section

200: 00 00 00> | |

203: <00 01 00 0A 00 01 00 03 00 00 00 12> | | QDFFFNAM: Named Field
Header Table

20F: <00 | | QDFFFDPD: Display-Field-
Level Device-Dependent Sect 210: 20 00 18 00 00> | |

215: <00 00 00 03 00 00 00 00> | | QDFFXFDP: Field-Dependent
Extension Structure

Figure 3: This is the first page of DSPDSPF output TYPE(*HEX) over Figure 1’s display file.


Calculation Resulting Variable Resulting Value

I2(8) FileHeader X’001D’ FileHeader + I4(FileHeader) RecFormatTab X’005D’ FileHeader + I4(RecFormatTab + 12) RecordHeader X’007D’ RecordHeader + I2(RecordHeader + 28) RecDeviceDep X’009B’ RecordHeader + I2(RecDeviceDep + 32) CategoryDisp X’00D5’ RecordHeader + I2(CategoryDisp + 3) MiscStruct X’00DB’ MiscStruct + 2 MiscKeyword X’00DD’ MiscKeyword + I2(MiscKeyword + 3) + 5 TitleStruct X’00FA’ I2(TitleStruct + 14) TitleLength X’000A’ TitleStruct + 26 TitleOffset X’0114’ Get(TitleOffset : TitleLength) WindowTitle DISABILITY

Figure 4: This pseudocode illustrates how the programmer must navigate the offsets returned by QDFRTVFD.


BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$0.00 Raised:
$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: