VioSavRedrawWait

Bindings:  C, MASM 

This call notifies a graphics mode application when it must save or redraw 
its screen image. 

 VioSavRedrawWait     (SavRedrawIndic, NotifyType, VioHandle) 
 

 SavRedrawIndic (USHORT) - input 
    Indicates which events the application is waiting for: 

    Value     Definition 
    0         The session manager notifies the application for both save 
              and redraw operations. 
    1         The session manager notifies the application for redraw 
              operations only. 

 NotifyType (PUSHORT) - output 
    Address that specifies the operation to be performed by the 
    application upon return from VioSavRedrawWait: 

    Value     Definition 
    0         Save screen image 
    1         Restore screen image. 

 VioHandle (HVIO) - input 
    Reserved word of 0s. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    421       ERROR_VIO_INVALID_PARMS 
    422       ERROR_VIO_FUNCTION_OWNED 
    423       ERROR_VIO_RETURN 
    430       ERROR_VIO_ILLEGAL_DURING_POPUP 
    436       ERROR_VIO_INVALID_HANDLE 
    465       ERROR_VIO_DETACHED 
    494       ERROR_VIO_EXTENDED_SG 
 
 Remarks 

 OS/2 uses VioSavRedrawWait to notify a graphics mode application to save 
 or restore its screen image at screen switch time.  The application in 
 the outgoing foreground session is notified to perform a save.  The 
 application in the incoming foreground session is notified to perform a 
 restore.  The application must perform the action requested and 
 immediately re-issue VioSavRedrawWait.  When an application performs a 
 save, it saves its physical display buffer, video mode, and any other 
 information the application needs to completely redraw its screen at 
 restore time. 

 Only one process per session can issue VioSavRedrawWait.  The process 
 that first issues VioSavRedrawWait becomes the owner of the function. 

 A text mode application must issue VioSavRedrawWait only if the 
 application writes directly to the registers on the display adapter. 
 Assuming VioSavRedrawWait is not issued by a text mode application, OS/2 
 performs the required saves and restores. 

 An application that issues VioSavRedrawWait may also need to issue 
 VioModeWait.  This would allow the application to be notified when it 
 must restore its mode at the completion of an application or hard error 
 pop-up.  Refer to VioModeWait for more information.  Two application 
 threads would be required to perform these operations in this case. 

 At the time a VioSavRedrawWait thread is notified, the session is in 
 transition to/from the background.  Although the session's official 
 status is background, any selector to the physical display buffer 
 previously obtained by the VioSavRedrawWait process (through 
 VioGetPhysBuf) is valid at this time.  The physical display buffer must 
 be accessed without issuing VioScrLock.  Since the session's official 
 status is background, any thread waits if it issues VioScrLock with the 
 "wait if unsuccessful" option. 

 An application containing a VioSavRedrawWait thread should be designed so 
 that the process does not cause any hard errors while the 
 VioSavRedrawWait thread is running, otherwise a system lockout may occur. 
 

 An application's VioSavRedrawWait thread may be notified to perform a 
 restore before it is notified to perform a save.  This happens if the 
 application was running in the background the first time it issued 
 VioSavRedrawWait.  The return from this function call provides the 
 notification.  The thread that issues the call performs the save or 
 redraw and then reissues VioSavRedrawWait to wait until its screen image 
 must be saved or redrawn again.