kbdsvc.doc

MMURTL(tm) Computer Operating System Ver x0.8, source code.

Copyright 1991-1993, R.A. Burgess

KeyBoard Service

INTRODUCTION

The Keyboard is handled with a system service.  As described in the architecture section, system services are accessed with the request primitive.  It is a service because it is a shared resource just like the file system.  Several programs can have outstanding requests to the keyboard service at one time.  Only one program (Job) will be assigned to receive keystrokes at any one time.  The exception to this rule is the Global Keyboard request to receive CTRL-ALT keystrokes.  

The Service Name is 'KEYBOARD' (Upper case as always).  Each of the functions is identifed by its Service Code number.  

An example of a Keyboard Service request:

erc = Request("KEYBOARD",
	    		1,			/* wSvcCode for ReadKbd */
	     	MyExch,		/* dRespExch  */
			&MyRqhandle,	/* pRqHndlRet */
			0,			/* npSend (no Send Ptrs) */
			&KeyCode		/* pData1  */
			4,			/* cbData1 (size of KeyCode)*/
			0			/* pData2 - not used (0) */
			0,			/* Not used (0)   */	
			1,			/* dData0 - fWait for Key */
			0,			/* dData1 - Not used (0) */
			0);			/* dData2 - Not used (0) */

All message based services use the same request interface.  Using the Request interface allows for asynchronous program operation.  You can make a request, then go do something else before you come back to wait or check the function to see if it's completed (yes boys and girls, this is true multitasking). 

If you don't need asynchronous keyboard access, the Public call ReadKbd is provided which is a blocking call with only 2 parameters.  It's easier to use, but not as powerful.  It is described after the servies below.


AVAILABLE SERVICES


The Keyboard service provides the following functions:

Service Code		Description

	1			Read Keyboard
	2			Notify on Global Keys
	3			Cancel Notify on Global Keys
	4			Assign Keyboard

The four functions are described in the following section.

--------------------------------------------------------

Read Keyboard

The Read Keyboard function (1) allows a program to request keyboard input from the service.  The first request pointer points to an unsigned DWord where the keycode will be returned. The keycodes are described in detail in a later section.  dData0 determines if the service will hold the request until a key is available.  A value of 0 means the request will be sent back to you immediatly even if a key is not available.  The error from the service will be ErcNoKeyAvailable (700) if no key was available.  The keycode is undefined if this occurs (so you must check the error).  A value of 1 in dData0 will cause the service to hold your request until a key is available.  In this case, the error should be zero.

Parameters for ReadKeyboard:

	wSvcCode    = 1
	npSend	  = 0
	pData1      = Ptr where the KeyCode will be returned
	dcbData1    = 4 - Count of bytes in the code
	pData2      = 0 - Not used
	dcbData2    = 0 - Not used.
	dData0	  = fWaitForKey (0 or 1)
			    0 = Return with error if no key waiting
			    1 = Wait for Key
	dData1	  = 0 - Not used
	dData2	  = 0 - Not used
-----------------------------------------------------	

Notify On Global Keys

The Notify On Global Keys function (2) allows a program to look for any keystroke that was entered with the CTRL and ALT keys depressed.  This allows for "Hot Key" operation.  

Unlike regular keystrokes, keys that are pressed when the  CTRL-ALT keys are depressed are not buffered.  This means that users of the Read Keyboard function (1) will not see these keys.  It also means that your application must have an outstanding Notify request with the keyboard service to receive these keys.  If you have an outstanding Notify request, and you no longer want to receive Global key notifications, you should send a Cancel Notify request (service code 3).

The Global keycodes are identical to the regular keycodes which are described in detail later.

Parameters for Notify On Global Keys:

	wSvcCode    = 2
	npSend	  = 0
	pData1      = Ptr where the KeyCode will be returned
	dcbData1    = 4 - Count of bytes in the code
	pData2      = 0 - Not used
	dcbData2    = 0 - Not used
	dData0	  = 0 - Not used
	dData1	  = 0 - Not used
	dData2	  = 0 - Not used
-----------------------------------------------------	

Cancel Notify On Global Keys

The Cancel Notify On Global Keys function (3) cancels an outstanding Notify On Global keys request.  If you have an outstanding Notify request, this cancels it.  The Notify request will be sent back to the exchange with an error stating it was cancelled.  The Canel Notify request will be returned also.  This cancels ALL outstanding Notify requests for your application (all from the same job number).

Parameters for Notify On Global Keys:

	wSvcCode    = 3
	npSend	  = 0
	pData1      = 0 - Not used
	dcbData1    = 0 - Not used
	pData2      = 0 - Not used
	dcbData2    = 0 - Not used
	dData0	  = 0 - Not used
	dData1	  = 0 - Not used
	dData2	  = 0 - Not used

-----------------------------------------------------	

Assign Keyboard

The Assign Keyboard Request assigns a new Job to receive keys from the service.  This request should only used by services such as the Monitor or a program that manages multiple jobs running under the MMURTL OS. 

Parameters for Assign Keyboard:

	wSvcCode    = 3
	npSend	  = 0
	pData1      = 0 - Not used
	dcbData1    = 0 - Not used
	pData2      = 0 - Not used
	dcbData2    = 0 - Not used
	dData0	  = x - New Job Number (1 to nJobs)
	dData1	  = 0 - Not used
	dData2	  = 0 - Not used

-----------------------------------------------------	

KEYCODES

MMURTL supports the standard AT 101 key advanced keyboard. All ASCII text and punctuation is supported directly, while providing complete keyboard status to allow further translation for all ASCII control codes.

The KeyCode returned by the keyboard service is a 32 bit (4 byte) value.  The low order byte is the actual key code, while the upper 3 bytes provides status of special keys (Shifts, Locks, etc.).

Low Byte		Key Value from table below
2nd Byte		Shift State (6 bits for SHIFT, ALT & CTRL)
3rd Byte		Lock States (3 bits for CAPS, NUM, SCROLL)
High Byte		Num Pad indicator

To eliminate all the key status from the 4 byte keycode so you can get the keystroke value itself, simply AND the keycode by 0FFh (0xff in C).  This will leave you with the 8 bit code for the key itself. The key will be properly shifted according to the state of the SHIFT and LOCK keys.

Shift State Byte (2nd byte)

If you need to know the shift state of any of the shift keys (CRTL, ALT or SHIFT), you can use the 2nd byte in the 32 bit word returned.  The following is a table showing how the bits are defined:

	Bit		Meaning when SET (a 1 in this bit)

	0		Left CTRL key down		
	1		Right CTRL key down
	2		Left Shift key down
	3		Right Shift key down
	4		Left Alt key down
	5		Right Alt key down
	6		Not used (0)
	7		Not used (0)

The following masks in assembly language can be used to determine if Control, Shift or Alt keys were depressed for the key code being read.

	CtrlDownMask	EQU 00000011b
	ShftDownMask	EQU 00001100b
	AltDownMask	EQU 00110000b


Lock State Byte (3rd byte)

If you need to know the LOCK state of any of the lock capable keys (CAPS, NUM or SCROLL), you can use the 3nd byte in the 32 bit word returned.  The following is a table showing how the bits are defined:

	Bit		Meaning when SET (a 1 in this bit)
	0		Scroll Lock ON		
	1		Num Lock ON
	2		Caps Lock ON
	3		Not used (0)
	4		Not used (0)
	5		Not used (0)
	6		Not used (0)
	7		Not used (0)

The following masks in assembly language can be used to determine if one of the lock keys was active for the key code being read.

	CpLockMask     EQU 00000100b
	NmLockMask     EQU 00000010b
	ScLockMask     EQU 00000001b


NUM Pad Indicator

Only one bit is used in the high order byte of the KeyCode.  This bit (Bit 0, LSB) will be set if the keystroke came from the numeric key pad.  This is needed if you use certain keys from the numeric pad differently than their equivilent keys on the main keyboard.  For example, the Enter key on the numeric keypad might do something differently in your program than the typewriter Enter key.

 

Key Value Tables

The Following tables show the hexidecimal value provided in the low order byte of the keycode (least significant) by the keyboard service for each key on a 101 keyboard.  The Shift Code column shows the value returned if the SHIFT key is active.  The CAPS Lock key does not affect the keys shown with an asterisk (*) in the Shift Code column.

If a shift code is not shown, the same value is provided in all shifted states (Shift, Ctrl, Alt, or Locks).  All codes are 7 bit values (1 to 127 - 1h to 7Fh).  Zero and values above 127 are not returned.

	Base Key			KeyCode  	Shift Code

	Esc				1Bh
	1	 			31h		21h  ! Exclamation  *
	2				32h		40h  @ At sign      *
	3		 		33h		23h  # Pound sign   *
	4	 			34h		24h  $ Dollar sign  *
	5	 			35h		25h  % Percent      *
	6	 			36h		5Eh  ^ Carat        *
	7	 			37h		26h  & Ampersand    *
	8	 			38h		2Ah  * Asterisk     *
	9	 			39h		28h  ( Open paren   *
	0	 			30h		29h	 ) Close paren *
	-	 			2Dh		5Fh  _ Underline    *
	=	 			3Dh		2Bh	 + Plus        *
	BkSpc			08h
	TAB				09h
	a				61h		41h
	b				62h		42h
	c				63h		43h
	d				64h		44h
	e				65h		45h
	f				66h		46h
	g				67h		47h
	h				68h		48h
	i				69h		49h
	j				6Ah		4Ah
	k				6Bh		4Bh
	l				6Ch		4Ch
	m				6Dh		4Dh
	n				6Eh		4Eh
	o				6Fh		4Fh
	p				70h		50h
	q				71h		51h
	r				72h		52h
	s				73h		53h
	t				74h		54h
	u				75h		55h
	v				76h		56h
	w				77h		57h
	x				78h		58h
	y				79h		59h
	z				7Ah		5Ah

	[	 			5Bh		7Bh  {  Open brace   *
	\ 	 			5Ch		7Ch  |  Vertical bar * 
	]	 			5Dh		7Dh  }  Close Brace  *
	`	 			60h		7Eh  ~  Tilde        *

	CR	Enter		0Dh
	; 	Semi colon	3Bh		3Ah  :  Colon        *
	'	Apostrophe	27h		22h  "  Double quote *
	,	Comma		2Ch		3Ch  <  Less than    *
	.	Period		2Eh		3Eh  >  Greater than *
	/	Slash		2Fh		3Fh  ?  Question     *
	Space			20h


Function Strip Key Codes 

Shift and Lock states do not affect the function key values.  Shift and Lock state bytes must be used to determine program functionality.

	Base Key			KeyCode

	F1				0Fh
	F2				10h
	F3				11h
	F4				12h
	F5				13h
	F6				14h
	F7				15h
	F8				16h
	F9				17h
	F10				18h
	F11				19h
	F12				1Ah


Numeric Pad Key Codes. 

The Shift values shown are returned when the Shift keys or Num Lock are active. Caps lock does not affect these keys.

	Base Key			KeyCode  	Shift Code

	End 				0Bh		31h   1
	Down 			02h  	32h	 2
	Pg Dn			0Ch  	33h   3
	Left				03h  	34h   4
	Blank Key			1Fh		35h   5   (Extra Code)
	Right			04h  	36h   6
	Home				06h		37h   7
	Up				01h 		38h   8
	Pg Up			05h		39h   9
	Insert			0Eh  	30h   0
	Delete			7Fh		2Eh   . (Period)
	-	Dash			2Dh		
	*	Asterisk		2Ah
	/	Slash		2Fh
	+	Plus			2Bh
	CR   Enter		0Dh


Cursor, Edit, and Special pad Key Codes.

None of these keys are affected by Shift or Lock states.

	Base Key			KeyCode  	Shift Code

	Print Screen		1Ch
	Pause			1Dh

	Insert			0Eh
	Delete			7Fh
	Home				06h
	End				0Bh
	Pg Up			05h
	Pg Dn			0Ch

	Up				01h
	Down				02h
	Left				03h
	Right			04h


----  End of Keyboard Service Documentation --------