Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

How to save, restore the screen -- the quick and easy way

This time we turn our attention to a couple of DSM APIs that can be used to take a "snapshot" of the screen, save it and restore it later using the saved data.

Ron Turull

In the last installment, I introduced you to Dynamic Screen Manager (DSM). This time we turn our attention to a couple of DSM APIs. These two APIs can be used to take a "snapshot" of the screen, save it and restore it later using the saved data. One of the ways this can be used is in the following situation, drawn from personal experience.

An RPG program calls a CL program, which in turn executes the STRPCCMD command. The STRPCCMD runs a command on the PC and leaves the screen completely blank. After returning, the RPG program does considerable processing before doing another write to the screen (e.g., EXFMT). During this time the screen remains blank, and the user may get the impression that the PC is hung.

Objective: Have the RPG program restore its screen after receiving control back from the CL program.

We do not want to use RSTDSP(*YES) on the CRTDSPF command because it can cause performance problems. Nor do we want to execute an RPG WRITE operation to the screen because it requires the use DFRWRT(*NO) on the CRTDSPF command, which can greatly complicate matters.

Solution: Use the Save Screen API (QsnSavScr) to take the snapshot and save the screen before calling the program that alters the screen. After the program returns, use the Put Buffer API (QsnPutBuf) to restore the screen. The following partial RPG code listing shows the ease of using this technique.

      *   Save screen.
     c                   CALLb     'QsnSavScr'
     c                   parm                    Buffer            4
     c                   parm      x'00000000'   Dummy             4
      *  ----------------------------------------------
      *   Call to screen-altering program here.
      *   Test with call to Clear Screen DSM API.
     c                   CALLb     'QsnClrScr'
     c                   parm                    *omit
      *  ----------------------------------------------
      *   Restore screen.
     c                   CALLb     'QsnPutBuf'
     c                   parm                    Buffer
      *  -----------------------
      *   Long processing here.
      *  -----------------------
      *  -------------
      *   EXFMT here.
      *  -------------
     c                   return

The Save Screen API stores a buffer handle (i.e., buffer identifier) in the Buffer parameter. The buffer it identifies (which is managed internally by DSM) will contain the data necessary to restore the screen -- the snapshot. The Put Buffer API writes the data saved in the buffer to the screen. Note: If you compile and run this program, you will see the screen flash.

Here are six points to remember:

  1. Both the Save Screen API and the Put Buffer API are called using the direct mode of DSM (see last installment).
  2. Both the Save Screen API and the Put Buffer API have other parameters. They are optional depending on the intended use. In the example, they are not needed.
  3. Contrary to logical thinking, you cannot replace the Put Buffer API in the example code with the Restore Screen API (QsnRstScr).
  4. Complete documentation is found in the OS/400 System API Reference and the OS/400 System API Programming manuals.
  5. The documentation lists the omissible parameters of each API (if applicable). Sometimes, you can leave off omissible parameters altogether, as in the QsnSavScr and QsnPutBuf calls. Other times you must explicit pass a null pointer. This is done using the *Omit RPG keyword, as in the call to the QsnClrScr (Clear Screen) API, which clears the display. When in doubt, code an explicit *Omit parameter. Note: Omissible parameters are different from optional parameters, which can always be left off (i.e., no need to pass a null pointer).
  6. The program shown can be easily translated to ILE COBOL or even ILE CL. To get you started, here is a COBOL listing:
     *  Declare buffer.
      01  BUFFER  PIC A(4).
     *  Save screen.
     *  Test with clear screen API.
     *  Restore screen.
          STOP RUN.

About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.

This was last published in November 2004

Dig Deeper on iSeries system performance and monitoring

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.



  • How do I size a UPS unit?

    Your data center UPS sizing needs are dependent on a variety of factors. Develop configurations and determine the estimated UPS ...

  • How to enhance FTP server security

    If you still use FTP servers in your organization, use IP address whitelists, login restrictions and data encryption -- and just ...

  • 3 ways to approach cloud bursting

    With different cloud bursting techniques and tools from Amazon, Zerto, VMware and Oracle, admins can bolster cloud connections ...