W_RESTORE

Restore a window that was previously compressed

xcall W_RESTORE(func_status, id, buffer[, options[, name]])

Arguments

func_status

Passed as the value CTL_BEGIN on the initial call to W_SAVE, and returned with the one of the following status values: (n)

CTL_BEGIN (1) = Start the restore operation.

CTL_MORE (2) = Another call to W_RESTORE is required.

CTL_DONE (0) = Restore operation is complete.

Returned with the ID of the restored window. (n)

buffer

Contains the information to use for the restore function. (a)

options

(optional) One or more of the following options, combined using .BOR. or a vertical bar (|): (n)

OPT_NODATA = Don’t restore saved window’s text and attributes.

OPT_NOTITLE = restore saved window’s title.

OPT_NOWFLDS = Don’t restore any saved window field sets.

OPT_NOUSET = Don’t restore any saved user data sets.

OPT_NEWNAME = use the saved window’s name.

name

(optional) A new name to be used for the restored window. (a)

Discussion

W_RESTORE creates a window from one that was previously compressed with W_SAVE.

The windowing system assumes that the window being restored was previously saved using W_SAVE, and that the information buffers returned by W_SAVE are passed to W_RESTORE in the exact order in which they were obtained.

On the initial call to W_RESTORE, func_status must be the value CTL_BEGIN. If func_status is returned with the value CTL_DONE, buffer contains all of the information required to restore the window, and the restore operation is complete. However, if func_status is returned with the value CTL_MORE, multiple calls to W_SAVE are required to save the window, and you must repeatedly call W_RESTORE to get the additional buffer information until CTL_DONE is returned. If func_status returns the value -1, an error occurred in the restore operation.

On the final call to W_RESTORE (CTL_DONE is returned), the options specified by options determine which components of the window are not to be restored. If the OPT_NEWNAME option is specified, name must be specified. If name is a null string, a unique name based on the returned window ID is created.

The “CTL_” and “OPT_” codes are defined in wmisc.def.

Here’s how you might code a window restore operation:

initialize for window restore input
set options to any restore options, or zero if none
set name if OPT_NEWNAME is set in options

fnc_sts = CTL_BEGIN
while (fnc_sts)
  begin
    .
    .  input buffer data from prior W_SAVE
    .
    if (fnc_sts.lt.0)
      .
      .  generate error
      .
    xcall w_restore(fnc_sts, wndid, buffer, opts, wname)
  end
  .
  .  terminate window restore input
  .