May-21-96:DE    Copyright (C) 1995, 1996 by Starbase Corporation

1/21/2002 - Tested in Version 7.0.
2/28/2001 - Tested in Version 6.6.
6/26/2000 - Updated dll loading instruction for CodeWright 6.5.


    OEM2ANSI - Convert DOS files for Windows editing

    The purpose of this package is to let you edit files created under
    DOS that contain language-specific characters.  It contains DLLs
    for use with the 16- and 32-bit versions of Codewright 4.0.
    
    The package contains functions to convert characters between the
    native OEM character set (determined by your codepage) and the
    Windows ANSI character set for editing.  The conversion will be
    done either automatically or on demand.
    
    To load this dll select Customize|Libraries and the Load CodeWright
    Dll dialog will display.  Select the Add button and Browse for 02A32.dll.
    Earlier versions of CodeWright load the Dll through CodeWright's 
    Tools|Libraries dialog. In the dialog, click on Add and browse for
    the DLL. The preceding process adds the following line to the 
    [LibPreload] section of CWRIGHT.INI:

        LibPreload="O2A32.DLL"
        
    To automatically convert all the files that you edit, and assign
    the ANSI keymap to all file buffers, add this line to the [Editor] 
    section of cwright.ini:
    
        O2AInstallHandler=TRUE
        
    If you want automatic conversion, but do not want to use the ANSI
    keymap on converted files, use this line instead:
    
        O2AInstallHandler=FALSE
        
    If you choose to let the handlers select OEM vs. ANSI keymaps
    for you, then you will need a file in your CodeWright directory
    called OEM2ANSI.KMA.  The German version of this file is provided
    in the current package.  It has the same format as an INI file,
    and consists of two sections: one contains a set of keybindings
    for use with the OEM character set, and one is for ANSI. Additional 
    keymap files can be located in another add-on named O2AKMAPS. 
    
    Normally, a message box will displayed when you open a file,
    asking if you want to convert it.  To disable this dialog and
    cause all files to be converted without prompting, add this line
    to the [Editor] section:
    
        O2ASetPrompting=FALSE
        
    If you want more control over how files are processed, you can
    call this package's functions from an API command line, or bind
    them to keystrokes.  Specifically, the functions of greatest
    interest will be O2AConvertOemToAnsi, O2AConvertAnsiToOem, 
    O2AFileOpen, and O2AFileClose.
    
    NOTE: The conversions are not reversible.  Converting a file from
    OEM to ANSI, then back to OEM can result in a file which is different
    from the original.  This is because not all characters in the OEM
    character set can be shown in the ANSI character set, and vice versa.
    If you load a file containing the ANSI characters, and mistakenly
    convert it to ANSI, do not save it.  You will not be able to convert
    it back to its original form.  For this reason, it is best to keep
    backups of files that you edit with this package.
    

    The DLL provides several API functions:

        void O2AConvertAnsiToOem (HBUFFER bufHandle)
        
        
            Called by the event handler when a file is closed.  This
            function may also be called directly.  It may be assigned
            to a key, a button, or a menu item.  It converts every
            character in the given buffer to its OEM equivalent.
            
            If a selection exists when this function is called, then
            only the selected text will be converted.
            
            If you only occasionaly edit files created under DOS that
            contain international characters, you may find it more
            convenient to use this function directly just before closing
            the file.
            
            This function may be used in conjunction with O2ASetCharSet
            to ensure that the appropriate keymap is used.
            
            Default parameter values:
            
                bufHandle: current buffer
        

        void O2AConvertOemToAnsi (HBUFFER bufHandle)
        
            Called by the event handler when a file is opened.  This
            function may also be called directly.  It may be assigned
            to a key, a button, or a menu item.  It converts every
            character in the given buffer to its ANSI equivalent.
            
            If a selection exists when this function is called, then
            only the selected text will be converted.
            
            If you only occasionaly edit files created under DOS that
            contain international characters, you may find it more
            convenient to use this function directly just after opening
            the file.
            
            If you have the event handlers installed, you can use this
            function to do the conversion, then call O2ASetCharSet.
            That way, the handler will convert the file back when it
            is saved.
            
            Default parameter values:
            
                bufHandle: current buffer
        
        
        ERRCODE O2AFileClose (HBUFFER bufHandle, BOOL save)
        
            This function is meant to be called directly by the user.
            Use it when the event handler is not active, optionally
            to convert the file to OEM and close it.
            
            It may be assigned to a key, a button, or a menu item.
            If save is TRUE, it converts every character in the given
            buffer to its OEM equivalent.  Then the buffer is deleted
            and the file is closed.  If bufHandle is NIL or is not
            given, the current buffer is closed after optional
            conversion.
            
            If the file opened by O2AFileOpen is closed by O2AFileClose,
            its contents can be converted back to the OEM character
            set, even if the event handler is not active.
            
            If bufHandle is NIL, the current buffer is closed.
            
            Default parameter values:
            
                bufHandle: current buffer
                save:      TRUE
                
            Return value is the value returned from BufDelBuffer.  If
            the deletion was successful, this value is 0.


        HBUFFER O2AFileOpen (LPSTR fileName, BOOL setKeymap)
        
            This function is meant to be called directly by the user.
            Use it when the event handler is not active, to open
            a file and do the conversion.
            
            It may be assigned to a key, a button, or a menu item.  It
            opens the named file and converts every character in it
            to its ANSI equivalent.  If setKeymap is TRUE, then the
            ANSI keymap is assigned to this buffer; otherwise, the
            current default keymap is used.
            
            If the file opened by O2AFileOpen is closed by O2AFileClose,
            its contents will be converted back to the OEM character
            set, even if the event handler is not active.
            
            Default parameter values:
            
                fileName:  <no default>
                setKeymap: TRUE
                
            Return value is a handle to the file's buffer.

        
        BOOL O2AInstallHandler (BOOL setKeyMap, BOOL promptMe)
        
            Installs the event handlers.  All files opened after this
            function is called will be converted from the OEM character
            set to the Windows character set, and they will be converted
            back when they are written.  A dialog will prompt for
            confirmation before the conversion.
            
            If setKeyMap is TRUE, then files opened after this function
            is called will be assigned a keymap for OEM or ANSI characters,
            depending on the font assigned to the file's window.
            
            If promptMe is TRUE, then you will be asked to confirm
            the conversion when you open files.
                        
            Default parameter values:
            
                setKeymap: TRUE
                promptMe:  FALSE
                
            Return value is TRUE if all handlers were installed successfully,
            or FALSE otherwise.
            
        
        int O2AQCharSet (HBUFFER bufHandle)
        
            Provides a way for the user to check which character
            set is being used for the current buffer.

            Default parameter values:
            
                bufHandle: current buffer

            Return values:

            A value of 0 indicates that the default character set is active.
            A value of 1 indicates that the ANSI character set is active.
            A value of 2 indicates that the OEM character set is active.


            Buffers with the ANSI character set will be converted to
            the OEM character set when they are closed using O2AFileClose
            or if the event handlers are active.



        BOOL O2ARemoveHandler (void)
        
            Removes the event handlers.  No conversion will take place
            after this function is called.
            
            Return value is TRUE if all handlers were removed successfully,
            or FALSE otherwise.
            
        
        int O2ASetCharSet BOOL ansi, BOOL setKeymap, HBUFFER bufHandle)

            This function marks the named buffer as ANSI or OEM text,
            so that it will be converted, if necessary, when it is written.
            If setKeymap is TRUE, it will also activate the ANSI or OEM
            keymap for this buffer.  If bufHandle is NIL, the current
            buffer is assumed.
            
            Default parameter values:
            
                ansi:      TRUE
                setKeymap: TRUE
                bufHandle: current buffer
                
            Return value indicates the character set before the call.

            A value of 0 indicates that the default character set was active.
            A value of 1 indicates that the ANSI character set was active.
            A value of 2 indicates that the OEM character set was active.
            A value of -1 indicates that the keymap could not be set


        BOOL O2ASetPrompting (BOOL promptMe)
        
            Enables or disables prompting before converting files.
            If promptMe is TRUE, then you get to confirm or cancel
            conversions.  This is the default behavior.  If promptMe
            is FALSE, the conversions are done automatically, without
            user intervention.
            
            Default parameter values:
            
                promptMe:  TRUE
                
            Return value is TRUE if prompting was active before the call,
            or FALSE otherwise.


    The following are the actual event handlers.  They should not
    be called directly.
        
        long O2AHandlerCreate (long event, long data)
        long O2AHandlerDelete (long event, long data)
        long O2AHandlerSave   (long event, long data)
        long O2ASavedHandler  (long event, long data)
        

HISTORY

        Apr-11-95:	Initial release

        Aug-30-95:	
                Keymap was being overridden by extension-specific
                handlers, so EVENT_BUFFER_CURRENT is now used instead of 
                EVENT_BUFFER_CREATED.  One bit in each buffer's user flags
                is used to let the BUFFER_CURRENT handler ignore buffers
                that have already been looked at.
        			
                The prompting argument to O2AInstallHandler() was
                being ignored.
				
        Sep-14-95:  
                Switched to an internal buffer table, instead of using
                the API's hash storage/lookup facilities, because I
                have doubts about whether they can handle binary keys.
                Hence, BufList* functions added.  This allows some
                simplification of the code.  Buffers' user flags are
                no longer used.
				
        May-21-96:  
                Using the keymap flag to indicate each buffer's character
                set introduced a logic flaw, so that a buffer that had
                been opened and converted using O2AFileOpen() was not
                getting converted back by O2AFileClose().  So a new flag
                was introduced to the BufferTable to indicate whether
                the buffer had been converted to ansi.  To this end,
                the CharSet enum was introduced, isomorphic to the
                set of *IDX constants, and the type returned by O2AQCharSet
                was changed to int.
                
                A bug was fixed that could cause a program crash if a
                modified converted buffer were closed without saving it.
                
				
            
Please send comments and suggestions to the Starbase technical
support staff:

email: codesupport@starbase.com
tele:  +1 503 641 6000
