This call requests ownership of (locks) the physical display buffer.

Syntax

VioScrLock (WaitFlag, Status, VioHandle)

Parameters

;WaitFlag (USHORT) - input : Indicates whether the process should block until the screen I/O can take place. 'Value Definition' 0 Return if screen I/O not available 1 Wait until screen I/O is available. ; Status (PUCHAR) - output : Address of the Indicator of whether the lock is successful, described below. 'Value Definition' 0 Lock successful 1 Lock unsuccessful (in the case of no wait). Status is returned only when AX = 0.

Status = 1 may be returned only when WaitFlag = 0. ; VioHandle (HVIO) - input : Reserved word of 0s.

Return Code

rc (USHORT) - return Return code descriptions are: * 0 NO_ERROR * 366 ERROR_VIO_WAIT_FLAG * 430 ERROR_VIO_ILLEGAL_DURING_POPUP * 434 ERROR_VIO_LOCK * 436 ERROR_VIO_INVALID_HANDLE * 465 ERROR_VIO_DETACHED * 494 ERROR_VIO_EXTENDED_SG

Remarks

This function call permits a process to determine if I/O to the physical screen buffer can take place. This prevents the process from writing to the physical buffer when the process is in the background. Processes must cooperate with the system in coordinating screen accesses.

Screen switching is disabled while the screen lock is in place. If a screen switch is suspended by a screen lock, and if the application holding the lock does not issue VioScrUnLock within a system-defined time limit, the screen switch occurs, and the process holding the lock is frozen in the background. A process should yield the screen lock as soon as possible to avoid being frozen when running in the background. The timeout on the lock does not begin until a screen switch is requested.

When the screen lock is in effect and another thread in the same or different process (in the same session) issues VioScrLock, the second thread receives an error code. VioScrUnLock must be issued by a thread within the same process that issued VioScrLock.

Family API Considerations

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restriction applies to VioScrLock when coding in the DOS mode:

The status always indicates the lock is successful (Return code = 0).

Example Code

C Binding

<PRE> #define INCL_VIO

USHORT rc = VioScrLock(WaitFlag, Status, VioHandle);

USHORT WaitFlag; /* Block or not */ PUCHAR Status; /* Lock status (returned) */ HVIO VioHandle; /* Video handle */

USHORT rc; /* return code */ </PRE>

MASM Binding

<PRE> EXTRN VioScrLock:FAR INCL_VIO EQU 1

PUSH WORD WaitFlag ;Block or not PUSH@ BYTE Status ;Lock status (returned) PUSH WORD VioHandle ;Video handle CALL VioScrLock

Returns WORD

Note

Text based on http://www.edm2.com/index.php/VioScrLock_(FAPI)

Family API
DOS	Process Manager	DosBeep DosExit DosSleep DosExecPgm
File Manager	DosChDir DosChgFilePtr DosClose DosDelete DosDupHandle DosMkDir DosMove DosQCurDir DosQCurDisk DosSetFileMode DosOpen DosQFileInfo DosRead DosQFileMode DosQFSInfo DosQVerify DosRmDir DosSelectDisk DosFindClose DosFindFirst DosFindNext DosSetFileInfo DosSetVerify DosWrite DosFileLocks DosSetFHandState DosNewSize DosBufReset DosQFHandState DosSetFSinfo DosShutdown
Memory Manager	DosFreeSeg DosSubAlloc DosSubFree DosSubSet DosAllocHuge DosAllocSeg DosReallocHuge DosReallocSeg DosGetHugeShift DosCreateCSAlias
NLS	DosCaseMap DosGetCtryInfo DosGetDBCSEv DosSetCtryCode DosGetCollate DosGetMessage DosInsMessage DosPutMessage
Date and Time	DosSetDateTime DosGetDateTime
Devices	DosDevConfig DosDevIOCtl DosDevIOCtl2
Signals	DosHoldSignal DosSetSigHandler
Misc	BadDynLink DosGetEnv DosGetMachineMode DosGetVersion DosError DosErrClass DosSetVec
KBD	KbdCharIn KbdFlushBuffer KbdGetStatus KbdSetStatus KbdStringIn KbdPeek
VIO	VioGetBuf VioGetConfig VioGetCurPos VioGetCurType VioGetPhysBuf VioReadCellStr VioReadCharStr VioScrollUp VioScrollDn VioScrollLf VioScrollRt VioScrUnLock VioSetCurPos VioSetCurType VioSetMode VioGetMode VioShowBuf VioWrtCellStr VioWrtCharStr VioWrtCharStrAtt VioWrtNAttr VioWrtNCell VioWrtNChar VioWrtTTY VioScrLock VioPopUp
Tools	BIND
Modules	DOSCALLS.DLL VIOCALLS.DLL KBDCALLS.DLL MSG.DLL
Libraries	API.LIB OS2386.LIB FAPI.LIB DOSCALLS.LIB SUBCALLS.LIB