You are currently on IBM Systems Media’s archival website. Click here to view our new website.


Show Me the Data!

While developing subprocedures or exploring new coding techniques, we’ve always made extensive use of RPG’s DSPLY op-code. It’s a convenient way of gathering simple input data and displaying the results of your calculations. Prior to the advent of /Free, our biggest annoyance was that if we wanted to output a message containing multiple values, we had to string the required text into a variable and display that. This was necessary because the message had to be specified in factor 1 and was therefore limited to being a variable name, or a literal of 12 characters or less. Here’s an example:

   c                 eval      message = 'Found ' + %Char(itemCount)
  c                           + ' items for Customer ' + 
  c     message     dsply

/Free did away with this limitation by effectively making factor 1 an arbitrary size—anything you specify within the first set of parentheses following the op-code. You can see the difference in the following example, which outputs exactly the same message as the first example.

    Dsply ('Found ' + %Char(itemCount) + ' items for Customer
         +  custName ) ;
    Dsply ('Press <Enter> when ready') ' ' wait;

The second DSPLY op-code example above demonstrates the one small “wrinkle” in using the /Free version. When we want to use DSPLY to accept input data, we must remember to artificially include the normally empty factor 2. In fixed form, we just left it blank, but in /Free, we represent it by a single-space literal (' ').

Even with /Free though one limitation remains: RPG’s idiotic restriction of a maximum of 52 characters in the message. Most of the time this is no big deal, but suppose, for example, that we want to retrieve and display a name and address. Then it becomes a problem. So you can imagine how happy we were when we came upon the QUILNGTX API. Turns out this thing has been around since V3R6 as part of the UIM (User Interface Manager) APIs. For those of you unfamiliar with the term, UIM is what IBM uses to create the screens that we interact with daily; IBM doesn’t use DDS, it uses UIM. Some UIM functions are surfaced as APIs and can be used in conjunction with conventional display files. QUILNGTX is one such API. Its official description is “Display Long Text” and it turns out to be very useful for displaying ad-hoc messages. You can even have it effectively simulate a simple subfile—for example, a list of validation errors.


Let’s begin with a simple example of using the API to output a text message. Needless to say, the message text itself can be built any way you like. The important thing is that we can break the 52-character barrier. The API takes five parameters as follows:

  1. The message string, which can be more 15 million characters long
  2. The second is the length of that string as a 4-byte integer (10 i)
  3. Next comes the message ID. The text of this message is used as a heading for the API’s display window. You can specify it as *Blank in which case no heading is used.
  4. This is followed by the 20-character message file and library identifier. The library portion, the last 10 characters, can be specified as *LIBL if you wish. *Blank can be used if parameter 3 specified blanks.
  5. Last but not least is the conventional API error structure.

Here’s the prototype for the API:

D QUILNGTX        PR                  ExtPgm('QUILNGTX')
D   text                      6800a   const options(*Varsize)

D   length                      10i 0 const
D   msgid                        7a   const
D   qualmsgf                    20a   const
D   errorCode                    8a   const

Notice that we resisted the urge to define the text as being 15,728,640 characters long (the true maximum) and instead used a length of 6,800. We’ll explain the reasons in a bit.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters