Suspend or Restore Display File (QWSSPRST) API

The Suspend or Restore Display File (QWSSPRST) API gives the caller the ability to either suspend the active display file on the requester device or restore a suspended file to the requester device. The suspend function returns a handle to the suspended file. The restore function accepts a handle of a suspended file to be restored.

The QWSSPRST API also allows the caller to have the screen image saved before the file is suspended. When the file is restored, this screen image also can be restored.

Authorities and Locks

None.

Required Parameter Group

Function requested

INPUT; CHAR(1)

The function requested for the start of QWSSPRST. The following functions can be specified:

0	Suspend the active file on the requester device and return a corresponding handle to that file.
1	Restore a suspended file to the requester device. The handle indicates which file will be restored.

Handle to suspended file

I/O; BINARY(4)

When suspending the active file (function 0), a handle to the suspended file will be returned in this parameter. When restoring a suspended file (function 1), this parameter accepts the handle of the file to be restored.

Screen image option

INPUT; CHAR(1)

When suspending the active file (function 0), this parameter gives the caller the option to save the current screen image. When restoring a suspended file (function 1), this parameter gives the caller the option to restore the saved screen image associated with the suspended file. If there is no saved screen image associated with the suspended file, this parameter is ignored when doing a restore.

If the screen image is not saved and restored when the file is restored, it is assumed that the application that is using the file will redraw the screen image. The following options can be specified:

0	If suspending the active file (function 0), do not save the screen image. If restoring an active file (function 1), do not restore the screen image associated with the suspended file.
1	If suspending the active file (function 0), save the current screen image. If restoring an active file (function 1), restore the screen image associated with the suspended file.

This parameter provides a function similar to that of the RSTDSP parameter of the CRTDSPF and CHGDSPF commands. Be aware that the command parameter causes the system to save and restore the screen image if RSTDSP(*YES) is used. The user of this API must request save the screen image at suspend time and restore the screen image at restore time to have the same function.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Messages