CBL_SCR_RESTORE

Restores an area of the character-mode screen previously saved with a call to the CBL_SCR_SAVE call-by-name routine.

Syntax:
call NoReturnCode "CBL_SCR_RESTORE" using by value     flags
                                                       handle
Parameters:
Using call prototype (see Library Routines - Key) Picture (32-bit systems)
flags cblt-x4-comp5. pic x(4) comp-5.
handle cblt-pointer. usage pointer.
On Entry:
flags Currently, this must always be zero.
handle A "save-handle" previously returned by a call to the CBL_SCR_SAVE call-by-name routine. This handle can be NULL, in which case the call does nothing.
On Exit:
handle Is untouched, but invalid. It must not be passed again to CBL_SCR_RESTORE unless it has subsequently been re-assigned a valid "save-handle" by a further call to the CBL_SCR_SAVE routine. We recommend that you set this pointer to NULL immediately on return from CBL_SCR_RESTORE. The area of the screen saved when the call to CBL_SCR_SAVE which returned handle was made is written, in the same position, to the screen.
Comments:

Because the flags parameter is passed BY VALUE, it may be specified as a numeric literal. For example, "BY VALUE 0 SIZE 4".

This call returns no status value. Therefore, it must be called using a suitable call-convention (as suggested in the syntax description) that you have defined in the special-names section. A suitable convention for this purpose is 4.

CBL_SCR_RESTORE has advantages over writing areas of the screen directly:

It is valid to change the mode of the screen (for example, switch the screen to 132-column mode) after saving an area of the screen with CBL_SCR_SAVE providing that the mode is restored to the previous setting before calling CBL_SCR_RESTORE. Failure to do so will result in undefined results.

See Also: