NAME
	MapANSI -- Encode an ANSI string into keycodes. (V36)

   SYNOPSIS
	actual = MapANSI( string, count, buffer, length, keyMap )
	D0                A0      D0     A1      D1      A2

	LONG MapANSI( STRPTR, LONG, STRPTR, LONG, struct KeyMap * );

   FUNCTION
	This console function converts an ANSI byte string to the
	code/qualifier pairs of type IECLASS_RAWKEY that would
	generate the string and places those pairs in a buffer.
	A code/qualifier pair is a pair of bytes suitable for
	putting in the ie_Code and low byte of ie_Qualifier,
	and for subsequent events, shifted to the ie_Prev1DownCode/
	ie_Prev1DownQual then ie_Prev2DownCode/ie_Prev2DownQual
	pairs for any dead or double dead key mapping.


   INPUTS
	string - the ANSI string to convert.
	count - the number of characters in the string.
	buffer - a byte buffer large enough to hold all anticipated
	    code/qualifier pairs generated by this conversion.
	length - maximum anticipation, i.e. the buffer size in bytes
	    divided by two (the size of the code/qualifier pair).
	keyMap - a KeyMap structure pointer, or null if the default
	    key map is to be used.

   RESULT
	actual - the number of code/qualifier pairs in the buffer,
	    or negative to describe an error (see below).

   EXAMPLE
	...
	#include <devices/inputevent.h>

	#define	STIMSIZE	3	/* two dead keys, one key */
	unsigned char rBuffer[STIMSIZE*2];
	...
	    KeymapBase = (struct Library *) OpenLibrary("keymap.library", 0);
	    ...
	    event.ie_NextEvent = 0;
	    event.ie_Class = IECLASS_RAWKEY;
	    event.ie_SubClass = 0;

	    /* prove keymap code completeness and MapANSI reversibility */
	    for (code = 0; code < 256; code++) {
		buffer[0] = code;
		actual = MapANSI(buffer, 1, rBuffer, STIMSIZE, 0);
		r = rBuffer;
		event.ie_Prev2DownCode = 0;
		event.ie_Prev2DownQual = 0;
		event.ie_Prev1DownCode = 0;
		event.ie_Prev1DownQual = 0;
		switch (actual) {
		    case -2:
			printf("MapANSI internal error");
			goto reportChar;
		    case -1:
			printf("MapANSI overflow error");
			goto reportChar;
		    case 0:
			printf("MapANSI ungeneratable code");
			goto reportChar;

		    case 3:
			event.ie_Prev2DownCode = *r++;
			event.ie_Prev2DownQual = *r++;
		    case 2:
			event.ie_Prev1DownCode = *r++;
			event.ie_Prev1DownQual = *r++;
		    case 1:
			event.ie_Code = *r++;
			event.ie_Qualifier = *r;

			actual = MapRawKey(&event, buffer, BUFFERLEN, 0);
			if ((actual != 1) || (buffer[0] != code)) {
			    printf("MapANSI not reversible");
			    for (i = 0; i < actual; i++)
				ReportChar(buffer[i]);
			    printf(" from");
	reportChar:
			    ReportChar(code);
			    printf("n");
			}
		}
	    }
	...

   ERRORS
	if actual is 0, a character in the string was not generatable
	    from the keyMap.
	if actual is -1, a buffer overflow condition was detected.
	if actual is -2, an internal error occurred (e.g. no memory)

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