DDS display file windows

I was asked a question about using DDS Windows with display files, that is when I noticed I did not have any examples of them. IMHO that is an omission on my part, and I am going to correct here. The examples I will be giving will also answer the question I was asked.

We have been able to create "pop-up" Windows using DDS Display files for many releases, and I have used them for scenarios where a user presses F4 in a field on the display file, a window is displays containing a subfile that the user can select a record from. I am going to keep the following examples much simpler than that, enough to be able to demonstrate some of the features of DDS windows. Examples of coding subfiles in RPG can be found elsewhere on this website.

For these examples I am using one display file and one RPG program. I am going to "break" the display's code into parts so I can describe what is going on and what is different from others. The RPG program can just be shown in one place, as it is very simple. Here is that RPG program:

Creating an auto-scrolling subfile

The idea for this post came from a question that was asked on Facebook. Someone wanted to create a subfile that would be projected onto a screen at an event. The subfile would scroll to the next screen of results every so many seconds without the need for someone to press a key on the keyboard.

I was surprised by the replies to the question, some said it was not possible, others gave over complicated examples of how they thought it could be achieved. I knew that to do this was simple, and all the information needed to do this exists in various posts on this website.

I decided to write a program to do what was asked before. I decided to make this a little more interesting:

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

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?

Make second line appear and disappear on a subfile

I was asked how to do this by someone who said that no-one in his department knew how to: have a second record appear in a subfile when a function key is pressed, and disappear when the function key was pressed again.

Fortunately this is a simple thing to do with just three keywords in the display file's DDS:

• SFLDROP
• SFLFOLD
• SFLMODE

And there is not much we have to do in the RPG program that uses the subfile.

I have deliberately stripped down the display file and RPG code to what I consider a minimum to, in my opinion, makes it easier to understand.

Let me jump right in and show you the display file I will be using in this example:

Control progression of cursor in display file

The question was how to control the way the cursor moves from field to field on a display. The display had two columns of fields and the questioner wanted the cursor to progress down the first column's fields before moving to the top of the second column.

My example display file contains two records format. The first I will be using to demonstrate the default cursor progression, and the second how I can move down the first column's fields before moving over to the second column.

The DDS code for the first record format looks like:

A R SCREEN0 A Z001 3 B 2 3 A Z002 3 B 2 10 A Z003 3 B 3 3 A Z004 3 B 3 10 A Z005 3 B 4 3 A Z006 3 B 4 10

Conditioning display file size

In the past couple of week I have been asked by several people how to condition whether a display file is shown in *DS3 (24 rows x 80 columns) or *DS4 (27 x 132) format. Rather than writing the same message to each one, I have decided to write this post so I can direct them to it.

These days I doubt if any of us IBM i developers are still using "dumb" workstations, we are all using PCs. In the settings of our 5250 emulator there is a configuration setting so we can set our emulated session to have a screen size of either 24x80 or 27x132. Personally I always configure my sessions to be 27x132.

You can see, and change, this setting depending on the emulator application you use.

Creating a screen with two side-by-side subfiles

I have written about subfiles, and even a screen with two subfiles on it. When I was asked about a screen with two subfiles, side-by-side, I was intrigued how to do it.

The first problem to overcome is that if I code two subfiles, one to occupy the left side of the screen and the other the right, whichever subfile's control record I write last will overlay the other.

After using Google I could find reference to an example of using DDS windows to contain the subfiles, but the links to the article only returned a "page not found". With that hint I created the following.

Let me start by saying that this display file is a "stripped down" version. I have removed a lot of the things I put in display files so not to clutter this example. Let me start with the file level keywords and a record format I have called HEADER.

Sending your own program created messages to the error subfile

I have previously written about using the error subfile to display error messages, rather than the message subfile. Personally I like using the error subfile as it is another case of allowing the operating system to do the work for me.

Since publishing that article I have received messages asking how can people create their own error message text, in the RPG program, that is displayed in the error subfile.

Fortunately there is a simple way to do this that will work in either RPG in CL.

No matter which language I use the display file can be the same. Here is the display file I will be using in this example.

Displaying more than one subfile at a time

I decided to write the post after being asked if I had an example of having two subfiles on the same screen. I did a quick search using Google and was unable to find what I considered a good example I felt comfortable sharing.

In this example I am going to show two subfiles horizontally (i.e. one on top of the other). I could have shown them vertically (next to one another), or even had more than two. The principals I show here can easily be adapted to fit either of those other scenarios. The most important thing to remember is that each set of subfile and subfile control record format cannot overlap another.

To reduce the size of the display file source code, shown here, I have removed all unnecessary color and display attributes codes that I use in the screens I build. I am going to show my display source in multiple parts to make it easier to understand what each record format is for. Let me start with the file level keywords.

Position cursor into field on screens

The germ for this post's subject came from a two part question I was asked:

1. How can I know which field the cursor is in when Enter is pressed?
2. How can I position a cursor on some field without using indicators? No indicators are available in that very old screen.

Fortunately there are ways to do this by adding a few keywords and fields to the display file's DDS. In these examples I am going to use one display file with three screens, each showing a way to do what has been asked, and the RPG code needed too (and I am going to cheat on the second part).

Determining the screen size

Most of us are aware that TN5250 sessions (displays) on the IBM i can be configured in two sizes:

• 24 x 80 commonly known as *DS3
• 27 x 132 commonly known as *DS4

Most of the time IBM i operating system handles this for us, only displaying "wide" screens when my session is *DS4 and the information to be displayed is wider than 80 columns.

Using API to test Help Panels

After publishing the post about how to create help text for display files using UIM several people messaged me that there is an IBM i API that can be used to test the help, without needing to add code to a display file. I have to admit I was unaware of the API, and am grateful to those who messaged me.

I decided to create a program to call the Display Help, QUHDSPH, API that way I can have a simple user interface to use, I only need to enter the variables I want and leave the rest with there defaults. I am going to show a very simple example here to illustrate how QUHDSPH can be used. As this is a simple example program a lot of the code I would add for myself, for validation etc. is not present.

For simplicity I am using a display file to enter the variables for the help module I want to see. There are other ways I could have done this, perhaps using a command instead, but I want this to be K.I.S.S compliant.

Adding UIM help to the Display file

Having created a UIM help panel group I need to add the code to my Display file's DDS so that the help will be displayed. This post is going to use the UIM panel group that was created in my previous post to demonstrate, in simple terms, how to do this. I have designed a very simple display file to only include what I think is the minimum needed for it to work.

Most people have no idea where to find the Help key in their 5250 emulation client, therefore, as per SAA CUA standards I always define F1 as an alternate help key. I define the alternate help key in the file level keywords, top before the first record format definition, of the display file.

Rather than use SDA I find it easier to enter this source code using a source code editor, for example SEU. Therefore, I will be describing how to add this code as if I am using a source code editor.

Creating help text using UIM

Thanks to UIM, User Interface Manager, designing help for your DDS display files is very simple. UIM has been used by IBM for their screens, menus, and help panels since the launch of the AS400, it was not until V2R1, 1991, that it was made available to programmers to create their own help panels. The "language" itself is easy to become familiar with and its compile listings are some of the easiest to decipher on IBM i.

In this post I am going to show how to create UIM help panels that can be used in DDS display files, and in a second post how to add the various DDS keywords to your Display file source code to use the UIM help panels.

Display screens of results without having to press Enter

I received a message asking me if there was an easy way in RPG to have a screen constantly update without the user needing to press a key. The idea is that as the program progresses it would write a message to the screen to inform the user of what is happening. Fortunately there is, otherwise I would not have be written this post.

First we need to understand what RPG's operation code Execute Format, EXFMT, does. Simply put it is a combination of a Write operation of the record format to the workstation, followed by a Read operation to retrieve the input from the record format. I can easily replace the EXFMT in any program with a WRITE followed by a READ. If I want to just write a display file's record format to the screen I could just perform a write, but how can I stop the user for using the keyboard while the record format is displayed?

Using the Error Subfile for messages in display files

I recently received a communication asking me if there was an easier way to display messages on a display file than using a message subfile. In my opinion there is a much simpler way using the Error Subfile, ERRSFL, keyword in the display file.

I have been using the Error Subfile for many years, so long that I cannot remember when I first encountered it. By using it I do not have to add all the code for the message subfile to my programs. I can just enter ERRSFL into my display and let the operating system do the hard work.