==== KbdXlate ====

**Bindings**: [[xlat#C bindings|C]], [[xlat#MASM bindings|MASM]]

This call translates scan codes with shift states into ASCII codes. 

KbdXlate (XlateRecord, KbdHandle) 

//XlateRecord// (**PKBDTRANS**) - input 
Address of the translation record structure: 

//chardata// (**KBDKEYINFO**) 
Character data information structure as defined in //[[charin|KbdCharIn]]// call. 

//kbdflag// (**USHORT**) 
See the //[[KbdDDFlagWord]]// call in the "Keyboard Device Driver" section of IBM Operating System/2 Version 1.2 I/O Subsystems And Device Support Volume 1. 

//xlate// (**USHORT**) 
Translation flag: 

^Value ^Definition ^
|0 |Translation incomplete. |
|1 |Translation complete. |

//xlatestate1// (**USHORT**) 
Identifies the state of translation across successive calls; initially the value should be zero. It may take several calls to this function to complete a character. The value should not be changed unless a new translation is required, that is, reset value to zero. 

//xlatestate2// (**USHORT**) 
See description for //xlatestate1//. 

//KbdHandle// (**HKBD**) - input 
Default keyboard or the logical keyboard. 

//rc// (**USHORT**) - return 
Return code descriptions are: 

|0 |NO_ERROR |
|439 |ERROR_KBD_INVALID_HANDLE |
|445 |ERROR_KBD_FOCUS_REQUIRED |
|447 |ERROR_KBD_KEYBOARD_BUSY |
|464 |ERROR_KBD_DETACHED |
|504 |ERROR_KBD_EXTENDED_SG |

**Remarks**

It may take several calls to complete a translation because of accent key combinations, or other complex operations. 

The //Xlatestate1// and //Xlatestate2// are for use by the keyboard translation routines. These fields are reserved and must only be accessed by the caller prior to starting a translation sequence and then they must be set to zero. The //KbdXlate// function is intended to be used for translating a particular scan code for a given shift state. The //KbdXlate// function is not intended to be a replacement for the OS/2 system keystroke translation function. 

=== C bindings ===

<code c>
typedef struct _KBDTRANS {    /* kbxl */
  UCHAR      chChar;          /* ASCII character code */
  UCHAR      chScan;          /* Scan code */
  UCHAR      fbStatus;        /* State of the character */
  UCHAR      bNlsShift;       /* Shift status (reserved set to zero) */
  USHORT     fsState;         /* Shift state */
  ULONG      time;
  USHORT     fsDD;
  USHORT     fsXlate;
  USHORT     fsShift;
  USHORT     sZero;
} KBDTRANS;

#define INCL_KBD

USHORT  rc = KbdXlate(XlateRecord, KbdHandle);

PKBDTRANS        XlateRecord;   /* Translation Record */
HKBD             KbdHandle;     /* Keyboard handle */

USHORT           rc;            /* return code 
</code>

=== MASM bindings ===

<code asm>
KBDTRANS struc
  kbxl_chChar    db  ? ;ASCII character code
  kbxl_chScan    db  ? ;scan code
  kbxl_fbStatus  db  ? ;State of the character
  kbxl_bNlsShift db  ? ;shift status (reserved set to zero)
  kbxl_fsState   dw  ? ;shift state
  kbxl_time      dd  ?
  kbxl_fsDD      dw  ?
  kbxl_fsXlate   dw  ?
  kbxl_fsShift   dw  ?
  kbxl_sZero     dw  ?
KBDTRANS ends

EXTRN  KbdXlate:FAR
INCL_KBD            EQU 1

PUSH@  OTHER   XlateRecord   ;Translation Record
PUSH   WORD    KbdHandle     ;Keyboard handle
CALL   KbdXlate

Returns WORD
</code>