NAME
	MapRawKey -- Decode single raw key input event to an ANSI
	             string. (V36)

   SYNOPSIS
	actual = MapRawKey(event, buffer, length, keyMap)
	D0                 A0     A1      D1      A2

	WORD MapRawKey( struct InputEvent *, STRPTR, WORD,
	    struct Keymap * );

   FUNCTION
	This console function converts input events of type
	IECLASS_RAWKEY to ANSI bytes, based on the keyMap, and
	places the result into the buffer.

   INPUTS
	event -  an InputEvent structure pointer.  The event list is
	    not traversed.
	buffer - a byte buffer large enough to hold all anticipated
	    characters generated by this conversion.
	length - maximum anticipation, i.e. the buffer size in bytes.
	keyMap - a KeyMap structure pointer, or null if the default
	    key map is to be used.

   RESULT
	actual - the number of characters in the buffer, or -1 if
	    a buffer overflow was about to occur.

   EXAMPLE
	...
	#define	BUFFERLEN	80	/* length of longest expected mapping /*
	char buffer[BUFFERLEN];
	struct InputEvent ie;
	...
	    KeymapBase = OpenLibrary("keymap.library", 0);
	    ...
	    ie.ie_Class = IECLASS_RAWKEY;
	    ie.ie_SubClass = 0;
	    for (;;) {
		WaitPort(window->UserPort);
		while (im = (struct IntuiMessage *) GetMsg(window->UserPort)) {
		    switch (im->Class) {
			case RAWKEY:
			    ie.ie_Code = im->Code;
			    ie.ie_Qualifier = im->Qualifier;
			    /* recover dead key codes & qualifiers */
			    ie.ie_EventAddress = (APTR *) *((ULONG *)im->IAddress);
			    actual = MapRawKey(&ie, buffer, BUFFERLEN, 0);
			    for (i = 0; i < actual; i++)
				ReportChar(buffer[i]);
			    break;
			...
		    }
		    ...
		}
	    }

   ERRORS
	if actual is -1, a buffer overflow condition was detected.
	Not all of the characters in the buffer are valid.

   SEE ALSO
	devices/inputevent.h, devices/keymap.h