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