:gdoc sec='IBM CONFIDENTIAL'.
:frontm.
:titlep.
.pm 5;.ll 66
.sp 15
.sl p8
.fo off
&IBMLOGO0
&IBMLOGO1
&IBMLOGO2
&IBMLOGO3
.fo on
.sl 1
:date.
:title.MULTI-CODEPAGE MESSAGE FILES SUPPORT
:title.I1 Document
:author.Issued by: Vera Dulany
:author.Prepared by: J. Hare and B. Chen
:address.
:aline.Entry Systems Division
:aline.Advanced Systems I/O Services or Advanced Systems Supervisor Services
:aline.Department 4Y1 Bldg. 229-4
:aline.Internal Zip 3811
:aline.Boca Raton, FL
:aline.Tie Line 982-6863
:eaddress.
:etitlep.
.bx 10 61
.ce IBM CONFIDENTIAL
.bx
.in +12
.ir +8
.fo on
This document contains information of a proprietary nature.  ALL INFORMATION
CONTAINED HEREIN SHALL BE KEPT IN CONFIDENCE.  None of this information shall
be divulged to persons other than IBM employees authorized by the nature of
their duties to receive such information, or individuals or organizations
authorized by the Entry Systems Division in accordance with existing policy
regarding release of company information.
.in 0
.ir 0
.bx off
:toc.
:body.

:h3.Multi-Codepage Message Files Support Overview

.* This section describes the component's relationship to the overall
.* system.

.il 5
The known Bi-Language message problem for concurrent DBCS/SBCS sessions can
described by the following case,
In order to run a U.S. version application program in a DBCS session under
OS/2-Japan, the code page has to be switched from DBCS to SBCS, but after
switching the code page, DBCS encoded messages are incorrectly displayed in
the SBCS session code page.
.sp 2;.il 5
Currently OS/2 supports only one code page message file. Therefore,Multi-CodePage
Message Files Support is required to generate multi code page message files
and retrieve message based on the current process's code page. This support must
be provided not only for system message files but also for general application
message files.
.sp 2;.il 5
Three components of OS/2 utilities must be modified to support the Multi-
CodePage Message Files.
.fo off




   . MKMSGF - Make Message File(s)

   . MSGBIND - Bind Message File(s) to Application Program

   . MSG.DLL - Message APIs




.fo on
.sp 2;.il 5

.pa
:h3.Multi-CodePage Message Operational Description

.* This section contains a high-level description of how each component
.* works.  This description should treat the component as a "black box"
.* and discuss, for example: when it is invoked, what it does when
.* invoked, what its parameters mean, and how it relates to other components.
:h4.***** MKMSGF *****
.il 5
MKMSGF - In order to generate message file(s) to support the Multi-CodePage,
we need to extend the current header of message file(s) to support Multi-CodePage
information. There are two kinds of related message files.
.fo off


     . Message root file, with the following structure:

	    .. 31 byte header, compatible with current format
	    .. Message offset table
	    .. Message text
	    .. Extension header root_file type
	    .. List of message file definitions and filenames

     . Message sub file, with the following structure:

	    .. 31 byte header, compatible with current format
	    .. Message offset table
	    .. Message text
	    .. Extension header sub_file type
	    .. Single message file definition

.fo on
.sp 2;.il 5
Each file(either root file or sub file) contains messages. A message is
retrieved(EX: DosGetMessage API is issued) from the root file if the
current process code page is equal to the code page of the root file.
Otherwise the search is performed from the definition record(s) of the extend
header of the root file to the correct code page of the sub file. If there is
no code match in any sub file, then the code page of the root file will be used
where the name of the root file is always the file specified in DosGetMessage.
.pa
:h4.Multi-CodePage Message Operational Description
:h4.***** MKMSGF *****
.im mkmsg01.src
.pa
:h4.Multi-CodePage Message Operational Description
.sp 3
:h4.***** MKMSGF *****
.fo off
.im mkmsg02.src
.fo on
.pa
:h4.Multi-CodePage Message Operational Description
.sp 3
:h4.***** MSGBIND *****
.il 5
MSGBIND - In order to bind the Multi-CodePage message file(s) to a user EXE
file, MSGBIND has to bind the information of Multi-CodePage and Multi-Language
of the root file and sub file(s) to the end of the user EXE file.
.sp 2;.il 5
The MSGBIND should have the capability to recognize the structure of the root
file and the structure of sub file(s).
.sp 3
.fo off
.im msgbind7.src
.fo on
.pa
:h4.Multi-CodePage Message Operational Description
.sp 3
:h4.***** MSG.DLL *****
.il 5
MSG.DLL - There are three exist APIs for message retrieval. All three API
DosGetMessage, DosInsMessage, DosPutMessage need to be enhanced. In order
to allow the user to get all the code pages and language IDs, we need to add
an extra API which the name is called DosQueryMessageCP.
.sp 2
Whenever DosGetMessage is called, it should be able
to distinguish and set up the code page for that specific message.
Whenever DosQueryMessageCP is called, it should allow the user to get code
pages and language IDs from the root and sub files.
.pa
:h4.Multi-CodePage Message Operational Description
.sp 3
:h4.***** MSG.DLL - DosGetMessage *****
.sp 3
.fo off
.im msgdll01.src
.fo on
.pa
:h4.Multi-CodePage Message Operational Description
.sp 3
:h4.***** MSG.DLL - DosQueryMessageCP *****
.sp 3
.fo off
.im msgdll02.src
.fo on
.pa
:h3.Multi-CodePage Message Interfaces

.* This section defines in greater detail what external functions are
.* performed by the component.

.* This section includes a list of OS/2 DOS calls provided by the component
.* and any other interfaces provided to other components.  Information
.* on the interfaces should include:
.*  -- function name
.*  -- names and types of parameters
.*  -- effects of invoking the interface
.*  -- restrictions of the invoker
.*  -- special considerations and cautions
.*  -- return information and status reporting

:h4.***** MKMSGF *****
.il 5
MKMSGF - During the operation, it will invoke DOS APIs listed below,
.im mkmsg03.src
.pa
:h4.Multi-CodePage Message Interfaces
.sp 3
:h4.***** MSGBIND *****
.il 5
MSGBIND - It need some DOS API function call. The extended header
information of message file(s) should be appended at the bottom of the
user EXE file. The appended format should be the same as before.
.fo off
	. DosGetMachineMode - Get the current mode of the process.
.fo on
.fo off
.im msgbind8.src
.fo on
.im msgbind9.src
.pa
:h4.Multi-CodePage Message Interfaces
.sp 3
:h4.***** MSG.DLL - DosGetMessage & DosQueryMessageCP *****
.il 5
MSG.DLL - During the operation, it will invoke DOS APIs where list below,
.fo off


      . DosGetCP - In order to get current process's code page to locate
		   the desired message file(either root file or sub file).

      . DosOpen - Opens file.

      . DosRead - Reads data from the opened file.

      . DosChgFilePtr - Moves the read/write pointer.

      . DosSemRequest - Obtains a semaphore.

      . DosSemClear - Clears a semaphore.

      . DosFreeSeg - Deallocates a memory segment.

      . DosClose - Closes file.

      . DosAllocSeg - Allocates a memory segment.

      . DosReallocSeg - Reallocates a memory segment.

      . DosGetDBCSEv - Obtains a DBCS environment vector.

      . DosCaseMap - Performs case mapping between binary and ASCII.

      . DosSearchPath - Searches file name from the path.

      . DosGetEnv - Gets process environment string.

      . DosInsMessage - Inserts variable text strings in message.

.fo on
.pa
:h3.Multi-CodePage Message Special Considerations

.* This section defines any dependencies, constraints, or limitations of
.* this component.

.il 5
In order for us to verify that the Multi-CodePage Message file(s) works,
DBCS machine and OS/2 Japan Version 2.00 software are needed.
.sp 1
.il 5
MSG.DLL - DosGetMessage & DosQueryMessageCP will be implemented in MASM code,
so that we can 100% compatible with current OS/2 version.
.sp 1
.il 5
MSGBIND should provide the data structure of the expanded EXE file so that
either DosGetMessage or DosQueryMessageCP can locate the message text.

:h4.Constraints - Impacts to the current implementation

.* Examples of constraints:
.*
.*  -- timing considerations/performance
.*  -- data handling limitations
.*  -- memory utilization constraints
.*  -- bimodal operation
.*  -- critical algorithms

.il 5
MKMSGF - Needs more execution time and storage when compares with single
code page.
.sp 1
.il 5
MSGBIND - Needs more execution time when compares with single code page.
.sp 1
.il 5
MSG.DLL - DosGetMessage, Approximately the same.
.sp 1
.il 5
MSG.DLL - DosQueryMessageCP, It's new, nothing to compare with.

:h4.Limitations

.* These are functions that a reader might assume are handled by the
.* component (because of the nature of the component) but are not
.* handled by the component.

.il 5
Due to the short development time, MKMSGF might be short of time to implement
the third kind of format(see next page at top level design).

:h4.Dependencies

.* Examples of dependencies:
.*
.* Interfaces needed by your component that are provided by other
.* components.
.* Required or expected callers
.* System initialization requirements

.il 5
DosCalls Thunk should be ready when the Multi-CodePage Message finishes its
build up.

.pa
:h3.Multi-CodePage Message Top Level Design

.* This section provides a text description of the processing performed
.* by your component.  It describes all inputs and outputs -- where the
.* inputs come from, what the component does with them, what output the
.* component creates and where it goes.  Hardware interfaces, if any,
.* should be discussed.
:h4.***** MKMSGF *****
.il 5
.im mkmsg04.src
.pa
:h4.Multi-CodePage Message Top Level Design
.sp 3
:h4.***** MKMSGF *****
.il 5
.im mkmsg05.src
.pa
:h4.Multi-CodePage Message Top Level Design
.sp 3
:h4.***** MSGBIND *****
.il 5
MSGBIND - Multi-CodePage message files are bound to the user EXE file. It
still use the original command line format,
.fo off


   . MSGBIND infile

     Where the parameter 'infile' has format below,



     .. EX:

	>prog1.exe
	<\messages\prg.msg
	prg0001
	prg0002
	prg0003
	<\messages\app.msg
	app0001
	app0002
	app0003


	... "prog1.exe" - is the executable file to be modified.

	... "<" - defines the first message of a series to be bound.
	    where "<" and ">" function also work as a delimiter of a
	    series.

	... "\messages\prg.msg" - specifies the path\filename.

	... "prg0001" - where prg is the message component ID, 0001 is
	    the message number.

.fo on
.pa
:h4.Multi-CodePage Message Top Level Design
.sp 3
:h4.***** MSG.DLL *****
.il 5
MSG.DLL - Whenever the Multi-CodePage Message file(s) is/are set up by the
MKMSGF or by the MSGBIND utility, application user can extract messages from
the message file(s) by giving the message number(s). The exist DosGetMessage
API does not handle multiple code pages and multiple languages, therefore
enhancement is required. The fundamental change requires that the code should
recognize the incoming message's code page, so that the correct message file
can be located correctly. All the parameters of DosGetMessage API are still
the same without any change.
.sp 2
.il 5
Because we involve Multi-CodePage Message file(s), we should provide the
application user another API to quest for all the code pages and all the
language IDs. This API we called DosQueryMessageCP.
.fo off


     The 4 parameters of DosQueryMessageCP in sequence,

	 . PUSH@   OTHER      BufferArea   ; Buffer for return list
	 . PUSH    WORD       BufferLength ; Length of buffer
	 . PUSH@   ASCIIZ     FileName	   ; Message path and file name
	 . PUSH@   WORD       DataLength   ; Length of return data

     CALL DosQueryMessageCP(BufferArea,BufferLength,FileName,DataLength);

.fo on
.pa
:h4.Multi-CodePage Message Top Level Design
.sp 3
:h4.***** MSG.DLL *****
MSG.DLL - The data structure for each queried code page and language ID is,
.fo off


	 DataArea  DW	?	    ; CP count
		   DW	16 dup(?)   ; CP IDs  (maximum 16 code pages)
		   DW	?	    ; Language family ID
		   DW	?	    ; Language ID
		    :
		   repeat for each subfile
		    :
		   DW	?	    ; CP count
		   DW	16 dup(?)   ; CP IDs  (maximum 16 code pages)
		   DW	?	    ; Language family ID
		   DW	?	    ; Language ID

  Use same errors/warnings/Return_code for FileName as used by DosGetMessage.


.fo on
.pa
:h3.Multi-CodePage Message Hierarchy

.* This section may optionally contain a paragraph describing the
.* software interfaces.  It must contain a diagram that shows the
.* routines of the component.  The diagram is constructed top-down,
.* left to right, in the same order that structured pseudo code is
.* generated.  The hierarchy diagram will show the structure of the
.* component, all routines used within the component, and all
.* interfaces to external components.

:h4.***** MKMSGF *****
.il 5
MKMSGF - The list below is all the procedures inside the MKMSGF.
.im mkmsg06.src
.pa
:h4.Multi-CodePage Message Hierarchy
.sp 3
:h4.***** MSGBIND *****
.il 5
MSGBIND - The list below is all the procedures inside the MSGBIND.
.im msgbind1.src
.pa
:h4.Multi-CodePage Message Hierarchy
.sp 3
:h4.***** MSG.DLL - DosGetMessage *****
.il 5
MSG.DLL - The list below is all the procedures inside the DosGetMessage.
.fo off


	MAIN

	  . Init setup

	  . CHECK_DBCS

	  . FIND_FILE
	      .. fold_up
	      .. filename_strip
	      .. ramfind
	      .. do_open
	      .. test_open_err
	      .. open_dpath
	      .. getbootroot
	      .. xfer_filename

	  . VAL_FORMAT
	      .. fold_up

	  . VAL_MID_NUM

	  . GET_MESSAGE

	  . Call DosInsMessage
.fo on
.pa
:h4.Multi-CodePage Message Hierarchy
.sp 3
:h4.***** MSG.DLL - DosQueryMessageCP *****
.il 5
MSG.DLL - The list below is all the procedures inside the DosQueryMessageCP.
.fo off


	MAIN

          . DosAllocSeg

	  . CHECK_DBCS

          . TRY_RAM
              .. CC_FILENAME_STRIP
                   ... C_FILENAME_STRIP
                         .... FILENAME_STRIP
              .. DosCaseMap

              .. FNSRCH

              .. LOOK_FOR_SUB
                   ...  CC_FIND_FILE
                          .... C_FIND_FILE
                              ..... FIND_FILE


          . TRY_DISK
              ..  CC_FIND_FILE
                    ... C_FIND_FILE
                          .... FIND_FILE

              ..  DOSREAD

              ..  SEEK_READ

              ..  COPY_CP_DATA

              ..  LOOK_FOR_SUB


          . DosFreeSeg




.fo on
.pa
:h3.Multi-CodePage Message Inter-Component Interfaces

.* This section defines all inter-component interfaces to the coding
.* level.  This includes the definition of data structures that are
.* used or passed between components.  Also included in this section
.* are the sublogues for all externally accessed routines.  This is
.* the detailed data that at i0 time identifies external dependencies
.* on other components.

:h4.***** MKMSGF, MSGBIND, MSG.DLL *****
.il 5
The Multi-CodePage Message files(root & subs) will be generated by MKMSGF
as a standard interface for MSGBIND and MSG.DLL.
.sp 2
.il 5
MSGBIND will generate the standard user expanded EXE file to be recognized
by the new MSG.DLL.
.pa
:h3.Multi-CodePage Message Intra-Component Interfaces

.* This section describes the intra-component interfaces at a high level.
.* This is a text description of how your component does its processing.
.* Sublogs are not required, but the text description should be sufficient
.* to indicate that the overall design of your component has been well
.* thought out.

:h4.***** MKMSGF *****
.im mkmsg07.src
.pa
:h4.Multi-CodePage Message Intra-Component Interfaces
:h4.***** MSGBIND *****
.im msgbind4.src
.pa
:h4.Multi-CodePage Message Intra-Component Interfaces
:h4.***** MSGBIND *****
.im.msgbind5.src
.pa
:h4.Multi-CodePage Message Intra-Component Interfaces
:h4.***** MSGBIND *****
.im msgbind2.src
.im msgbind6.src
.pa
:h4.Multi-CodePage Message Intra-Component Interfaces
:h4.***** MSG.DLL - DosGetMessage *****
.im i1.pic
.im msgdll03.src
.im msgdll04.src
.im msgdll05.src
.pa
:h3.Multi-CodePage Message Control/Data Flow

.* This section contains a diagram, accompanied by text, explaining the
.* data flow.  The data flow diagram should show the paths of all data
.* processed by this component.  It is a means for visually describing
.* major data interfaces.  Control flow should be shown, indicating where
.* control enters each major routine and how it gets transferred to
.* subroutines.  It is recommended that you use numbers on the diagram
.* that correspond to numbered notes below the diagram to help the
.* reader follow the flow of the diagram.

:h4.***** MKMSGF *****
.im mkmsg08.src
.pa
:h4.Multi-CodePage Message Control/Data Flow
:h4.***** MSGBIND *****
.im msgbind3.src
.pa
:h4.Multi-CodePage Message Control/Data Flow
:h4.***** MSG.DLL - DosGetMessage *****
.fo off
.im msgdll06.src
.fo on
.pa
:h4.Multi-CodePage Message Control/Data Flow
:h4.***** MSG.DLL - DosQueryMessageCP *****
.fo off
.im msgdll07.src
.fo on
:egdoc
