Jump to content

VioRegister: Difference between revisions

From EDM2
Ak120 (talk | contribs)
Ak120 (talk | contribs)
mNo edit summary
Line 1: Line 1:
==Description==
This call registers an alternate video subsystem within a session.
This call registers an alternate video subsystem within a session.


==Syntax==
==Syntax==
<PRE>
  VioRegister (ModuleName, EntryPoint, FunctionMask1, FunctionMask2)
  VioRegister


    (ModuleName, EntryPoint, FunctionMask1, FunctionMask2)
</PRE>
==Parameters==
==Parameters==
; ModuleName (PSZ) - input : Address of the ASCIIZ string containing the 1-8 character file name of the subsystem. The maximum length of the ASCIIZ string is 9 bytes including the terminating byte of zero. The module must be a dynamic link library but the name supplied must not include the .DLL extension.  
; ModuleName (PSZ) - input : Address of the ASCIIZ string containing the 1-8 character file name of the subsystem. The maximum length of the ASCIIZ string is 9 bytes including the terminating byte of zero. The module must be a dynamic link library but the name supplied must not include the .DLL extension.
 
; EntryPoint (PSZ) - input : Address of the ASCIIZ name string containing the dynamic link entry point name of the routine in the subsystem to receive control when any of the registered functions is called. The maximum length of the ASCIIZ string is 33 bytes including the terminating byte of zero.
; EntryPoint (PSZ) - input : Address of the ASCIIZ name string containing the dynamic link entry point name of the routine in the subsystem to receive control when any of the registered functions is called. The maximum length of the ASCIIZ string is 33 bytes including the terminating byte of zero.  
 
; FunctionMask1 (ULONG) - input : A bit mask where each bit identifies a video function being registered. The bit definitions are shown below. The first word pushed onto the stack contains the high-order 16 bits of the function mask, and the second word contains the low-order 16 bits.
; FunctionMask1 (ULONG) - input : A bit mask where each bit identifies a video function being registered. The bit definitions are shown below. The first word pushed onto the stack contains the high-order 16 bits of the function mask, and the second word contains the low-order 16 bits.
       BIT  REGISTERED FUNCTION        BIT  REGISTERED FUNCTION
       BIT  REGISTERED FUNCTION        BIT  REGISTERED FUNCTION
    ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ-
       31    VioPrtScToggle              15    VioWrtCharStr
       31    VioPrtScToggle              15    VioWrtCharStr
       30    VioEndPopUp                14    VioWrtTTY
       30    VioEndPopUp                14    VioWrtTTY
Line 33: Line 26:
       17    VioWrtCellStr              1    VioGetCurType
       17    VioWrtCellStr              1    VioGetCurType
       16    VioWrtCharStrAtt            0    VioGetCurPos
       16    VioWrtCharStrAtt            0    VioGetCurPos
 
;FunctionMask2 (ULONG) - input : A bit mask where each bit identifies a video function being registered. The bit mask has the format shown below. The first word pushed onto the stack contains the high order 16 bits of the function mask, and the second word contains the low order 16 bits. Unused bits are reserved and must be set to zero.
; FunctionMask2 (ULONG) - input : A bit mask where each bit identifies a video function being registered. The bit mask has the format shown below. The first word pushed onto the stack contains the high order 16 bits of the function mask, and the second word contains the low order 16 bits. Unused bits are reserved and must be set to zero.
 
   '''Bit        Description'''  
   '''Bit        Description'''  
  31-9    Reserved, set to zero  
  31-9    Reserved, set to zero
  8        VioSetState  
  8        VioSetState
  7        VioGetState  
  7        VioGetState
  6        VioSetFont  
  6        VioSetFont
  5        VioGetCp  
  5        VioGetCp
  4        VioSetCp  
  4        VioSetCp
  3        VioGetConfig  
  3        VioGetConfig  
  2        VioGetFont  
  2        VioGetFont
  1        VioModeUndo  
  1        VioModeUndo  
  0        VioModeWait
  0        VioModeWait


==Return Code==
==Return Code==
rc (USHORT) - return
rc (USHORT) - return
 
Return code descriptions are:
Return code descriptions are:
* 0          NO_ERROR  
* 0          NO_ERROR  
* 349        ERROR_VIO_INVALID_MASK  
* 349        ERROR_VIO_INVALID_MASK  
Line 60: Line 49:
* 465        ERROR_VIO_DETACHED  
* 465        ERROR_VIO_DETACHED  
* 494        ERROR_VIO_EXTENDED_SG
* 494        ERROR_VIO_EXTENDED_SG
==Remarks==
==Remarks==
An alternate video subsystem must register which video calls it handles. The default OS/2 video subsystem is the Base Video Subsystem.
An alternate video subsystem must register which video calls it handles. The default OS/2 video subsystem is the Base Video Subsystem.
Line 68: Line 58:


For example, if VioSetCurPos were a registered function, the stack would appear as if the following instruction sequence were executed if VioSetCurPos were called and control routed to EntryPoint:
For example, if VioSetCurPos were a registered function, the stack would appear as if the following instruction sequence were executed if VioSetCurPos were called and control routed to EntryPoint:
 
  ³ PUSH    WORD    Row
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  ³ PUSH    WORD    Column
  ³ PUSH    WORD    Row                                 ³
  ³ PUSH    WORD    VioHandle
  ³ PUSH    WORD    Column                             ³
  ³ CALL    FAR      VioSetCurPos
  ³ PUSH    WORD    VioHandle                           ³
  ³ PUSH    WORD    Index
  ³ CALL    FAR      VioSetCurPos                       ³
  ³ CALL    NEAR    Entry point in Vio router
  ³ PUSH    WORD    Index                               ³
  ³ PUSH    WORD    Caller's DS
  ³ CALL    NEAR    Entry point in Vio router           ³
  ³ CALL    FAR      Dynamic link entry point
  ³ PUSH    WORD    Caller's DS                         ³
  ³ CALL    FAR      Dynamic link entry point           ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
 
The index numbers that correspond to the registered functions are listed below:
The index numbers that correspond to the registered functions are listed below:
<PRE>
<PRE>
VioGetPhysBuf
VioGetPhysBuf   22 VioSetAnsi 1
 
VioGetBuf       23 VioGetAnsi 2
    22 VioSetAnsi  
VioShowBuf       24 VioPrtSc   3
 
VioGetCurPos    25 VioScrLock 4
1 VioGetBuf
VioGetCurType   26 VioScrUnLock 5
 
VioGetMode       27 VioSavRedrawWait 6
    23 VioGetAnsi  
VioSetCurPos    28 VioSavRedrawUndo 7
 
VioSetCurType   29 VioPopUp 8
2 VioShowBuf
VioSetMode       30 VioEndPopUp 9
 
VioReadCharStr   31 VioPrtScToggle 10
    24 VioPrtSc  
VioReadCellStr   32 VioModeWait 11
 
VioWrtNChar     33 VioModeUndo 12
3 VioGetCurPos
VioWrtNAttr     34 VioGetFont 13
 
VioWrtNCell     35 VioGetConfig 14
     25 VioScrLock  
VioWrtCharStr   36 VioSetCp 15
 
VioWrtCharStrAtt 37 VioGetCp 16
4 VioGetCurType
VioWrtCellStr   38 VioSetFont 17
 
VioWrtTTY       39 VioGetState 18
    26 VioScrUnLock  
VioScrollUp     40 VioSetState 19
 
VioScrollDn     20 VioScrollLf 21 VioScrollRt
5 VioGetMode
 
    27 VioSavRedrawWait  
 
6 VioSetCurPos
 
     28 VioSavRedrawUndo  
 
7 VioSetCurType
 
    29 VioPopUp  
 
8 VioSetMode
 
    30 VioEndPopUp  
 
9 VioReadCharStr
 
    31 VioPrtScToggle  
 
10 VioReadCellStr
 
    32 VioModeWait  
 
11 VioWrtNChar
 
    33 VioModeUndo  
 
12 VioWrtNAttr
 
    34 VioGetFont  
 
13 VioWrtNCell
 
    35 VioGetConfig  
 
14 VioWrtCharStr
 
    36 VioSetCp  
 
15 VioWrtCharStrAtt
 
    37 VioGetCp  
 
16 VioWrtCellStr
 
    38 VioSetFont  
 
17 VioWrtTTY
 
    39 VioGetState  
 
18 VioScrollUp
 
    40 VioSetState  
 
19 VioScrollDn
 
20 VioScrollLf
 
21 VioScrollRt
</PRE>
</PRE>
When a registered function returns to the video router, the return code is interpreted as follows:
When a registered function returns to the video router, the return code is interpreted as follows:
; Return code = 0 : No error. Do not invoke the corresponding Base Video Subsystem routine. Return to caller with Return code = 0.  
; Return code = 0 : No error. Do not invoke the corresponding Base Video Subsystem routine. Return to caller with Return code = 0.  


Line 177: Line 100:
An alternate video subsystem should be designed so the routines registered do not cause any hard errors when they are invoked. Otherwise, a system lockout occurs. Code and data segments of registered routines, that might be loaded from diskette, must be preloaded.
An alternate video subsystem should be designed so the routines registered do not cause any hard errors when they are invoked. Otherwise, a system lockout occurs. Code and data segments of registered routines, that might be loaded from diskette, must be preloaded.


All VIO functions within a session are serialized on a thread basis. That is, when an alternate video subsystem receives control, it can safely assume that it is not called again from the same session until the current call has completed.  
All VIO functions within a session are serialized on a thread basis. That is, when an alternate video subsystem receives control, it can safely assume that it is not called again from the same session until the current call has completed.
 
==Example Code==
<PRE>
 
</PRE>
==Related Functions==
*
 


[[Category:The OS/2 API Project]]
[[Category:Vio]]

Revision as of 05:26, 13 February 2017

This call registers an alternate video subsystem within a session.

Syntax

VioRegister (ModuleName, EntryPoint, FunctionMask1, FunctionMask2)

Parameters

ModuleName (PSZ) - input
Address of the ASCIIZ string containing the 1-8 character file name of the subsystem. The maximum length of the ASCIIZ string is 9 bytes including the terminating byte of zero. The module must be a dynamic link library but the name supplied must not include the .DLL extension.
EntryPoint (PSZ) - input
Address of the ASCIIZ name string containing the dynamic link entry point name of the routine in the subsystem to receive control when any of the registered functions is called. The maximum length of the ASCIIZ string is 33 bytes including the terminating byte of zero.
FunctionMask1 (ULONG) - input
A bit mask where each bit identifies a video function being registered. The bit definitions are shown below. The first word pushed onto the stack contains the high-order 16 bits of the function mask, and the second word contains the low-order 16 bits.
     BIT   REGISTERED FUNCTION         BIT   REGISTERED FUNCTION

     31    VioPrtScToggle              15    VioWrtCharStr
     30    VioEndPopUp                 14    VioWrtTTY
     29    VioPopUp                    13    VioWrtNCell
     28    VioSavRedrawUndo            12    VioWrtNAttr
     27    VioSavRedrawWait            11    VioWrtNChar
     26    VioScrUnLock                10    VioReadCellStr
     25    VioScrLock                  9     VioReadCharStr
     24    VioPrtSc                    8     VioShowBuf
     23    VioGetAnsi                  7     VioSetMode
     22    VioSetAnsi                  6     VioSetCurType
     21    VioScrollRt                 5     VioSetCurPos
     20    VioScrollLf                 4     VioGetPhysBuf
     19    VioScrollDn                 3     VioGetBuf
     18    VioScrollUp                 2     VioGetMode
     17    VioWrtCellStr               1     VioGetCurType
     16    VioWrtCharStrAtt            0     VioGetCurPos
FunctionMask2 (ULONG) - input
A bit mask where each bit identifies a video function being registered. The bit mask has the format shown below. The first word pushed onto the stack contains the high order 16 bits of the function mask, and the second word contains the low order 16 bits. Unused bits are reserved and must be set to zero.
 Bit         Description 
31-9     Reserved, set to zero
8        VioSetState
7        VioGetState
6        VioSetFont
5        VioGetCp
4        VioSetCp
3        VioGetConfig 
2        VioGetFont
1        VioModeUndo 
0        VioModeWait

Return Code

rc (USHORT) - return

Return code descriptions are:

  • 0 NO_ERROR
  • 349 ERROR_VIO_INVALID_MASK
  • 403 ERROR_VIO_INVALID_ASCIIZ
  • 426 ERROR_VIO_REGISTER
  • 430 ERROR_VIO_ILLEGAL_DURING_POPUP
  • 465 ERROR_VIO_DETACHED
  • 494 ERROR_VIO_EXTENDED_SG

Remarks

An alternate video subsystem must register which video calls it handles. The default OS/2 video subsystem is the Base Video Subsystem.

When any of the registered functions are called, control is routed to EntryPoint. When this routine is entered, four additional values (5 words) are pushed onto the stack.

The first value is the index number (Word) of the routine being called. The second value is a near pointer (Word). The third value is the caller'sDSregister( Word ) . Thefourthvalueisthereturnaddress( DWord )totheVIOrouter .

For example, if VioSetCurPos were a registered function, the stack would appear as if the following instruction sequence were executed if VioSetCurPos were called and control routed to EntryPoint:

³ PUSH     WORD     Row
³ PUSH     WORD     Column
³ PUSH     WORD     VioHandle
³ CALL     FAR      VioSetCurPos
³ PUSH     WORD     Index
³ CALL     NEAR     Entry point in Vio router
³ PUSH     WORD     Caller's DS
³ CALL     FAR      Dynamic link entry point

The index numbers that correspond to the registered functions are listed below:

 VioGetPhysBuf    22 VioSetAnsi 1
 VioGetBuf        23 VioGetAnsi 2
 VioShowBuf       24 VioPrtSc   3
 VioGetCurPos     25 VioScrLock 4
 VioGetCurType    26 VioScrUnLock 5
 VioGetMode       27 VioSavRedrawWait 6
 VioSetCurPos     28 VioSavRedrawUndo 7
 VioSetCurType    29 VioPopUp 8
 VioSetMode       30 VioEndPopUp 9
 VioReadCharStr   31 VioPrtScToggle 10
 VioReadCellStr   32 VioModeWait 11
 VioWrtNChar      33 VioModeUndo 12
 VioWrtNAttr      34 VioGetFont 13
 VioWrtNCell      35 VioGetConfig 14
 VioWrtCharStr    36 VioSetCp 15
 VioWrtCharStrAtt 37 VioGetCp 16
 VioWrtCellStr    38 VioSetFont 17
 VioWrtTTY        39 VioGetState 18
 VioScrollUp      40 VioSetState 19
 VioScrollDn      20 VioScrollLf 21 VioScrollRt

When a registered function returns to the video router, the return code is interpreted as follows:

Return code = 0
No error. Do not invoke the corresponding Base Video Subsystem routine. Return to caller with Return code = 0.
Return code = -1
No error. Invoke the corresponding Base Video Subsystem routine. Return to caller with Return code = return code from Base Video Subsystem.
Return code = error (not 0 or -1)
Do not invoke the corresponding Base Video Subsystem routine. Return to caller with Return code = error.

When an application registers a replacement for VioPopUp within a session, the registered routine is only invoked when that session is in the foreground. If VioPopUp is issued when that session is in the background, the OS/2 default routine is invoked.

An alternate video subsystem should be designed so the routines registered do not cause any hard errors when they are invoked. Otherwise, a system lockout occurs. Code and data segments of registered routines, that might be loaded from diskette, must be preloaded.

All VIO functions within a session are serialized on a thread basis. That is, when an alternate video subsystem receives control, it can safely assume that it is not called again from the same session until the current call has completed.