cm(3X)																	    cm(3X)

NAME

       cm, cm_open, cm_close, cm_put - Kana-Kanji Conversion Manager Library

SYNOPSIS

       cc [ flags ...]	files ...  -lmle [ libraries ...]

       #include <mle/cm.h>
       #include <mle/env.h>
       #include <mle/cmkeys.h>

       Cm_session cm_open(cm_id, cm_initvalue, se_initvalue)
       Cm_id	 cm_id;
       struct cm_initstruct	*cm_initvalue;
       struct cm_to_env *se_initvalue;

       int cm_close(cm_id, cm_session);
       Cm_id	 cm_id;
       Cm_session cm_session;

       struct cm_to_env *cm_put(cm_id, cmsession, inptr)
       Cm_id	 cm_id;
       Cm_session cmsession;
       struct env_to_cm *inptr;

DESCRIPTION

       This library defines the interface for presenting the input data and receiving the intermediate and final results of language-specific con-
       version process such as Kana-Kanji conversion.  The current release supports such conversion for the Japanese language.

       Use of this library enables the user to construct a universal application system that can handle different languages, simply by	describing
       language-independent input procedures (such as screen control) in the applications.

       When  the user passes input data to the Conversion Manager (CM), two primary responses are returned from the CM.  One is a character string
       resulting from the conversion process, which will be treated as the input data.	The other is logical data describing the  display  request
       for  the  screen  for  any user interactions that have occurred during the conversion process.  The user can expand the logical data into a
       visible screen image (physical data), which achieves the user interface for the conversion.

       The display request sent from the CM is presented as operations for the following four regions:
	      - Intermediate region
	      - Selection region
	      - Mode region
	      - Miscellaneous region

       The intermediate region is mainly used for showing the intermediate results of conversion.  It consists of logical data	in  the  following
       structure.

		 int	ce_cursor    /* cursor position */
		 int	ce_cursor_type/* cursor type */
		 e_char *ce_text     /* text to display */
		 u_char *ce_text_attr/* attribute, color & type of text */
		 int	ce_v_pos     /* display position */
		 int	ce_v_type    /* meaning of ce_v_pos */

       The image being input is indicated by this structure.  The library user determines how to display this data on the screen, and where on the
       screen.

       The selection region enables the candidate selection process.  It consists of logical data in the following structure.

		 int	ce_ncandidate/* number of candidates */
		 e_char **ce_candidate/* array of EUC strings for candidates */
		 int	ce_prevexist /* whether previous candidate exists */
		 int	ce_nextexist /* whether next candidate exists */
		 e_char *ce_sel_prompt/* user prompt for selection operation */

       ce_prevexist being true indicates that one or more candidates follow, and ce_nextexist being true indicates that  one  or  more	candidates
       precede.

       The mode region is used for presenting the modes the CM has.  It consists of logical data in the following structure.
	      ((mode_name mode_value)(mode_name mode_value) ....)

       It is the library user's responsibility to ensure the correspondence between the mode names and the values to be displayed.

       The  miscellaneous  region  is used for achieving other display operations such as displaying help messages and adding to dictionaries.	It
       comprises three subregions:

			- Interactive subregion
			- Label subregion
			- Message subregion

       Logical data for each subregion is represented by the structure shown below.

       Interactive subregion
		 int	ce_cursor    /* cursor position */
		 int	ce_cursor_type/* cursor type */
		 e_char *ce_text     /* text to display */
		 u_char *ce_text_attr/* attribute, color & type of text */
		 int	ce_v_pos     /* display position */
		 int	ce_v_type    /* meaning of ce_v_pos */

       Label subregion
		 e_char *ce_text     /* label text */

       Message subregion
		 e_char *ce_text     /* text to display */
		 int	ce_prevexist /* previous text exists */
		 int	ce_nextexist /* next text exists */

       Refer to cm_put() for details on operations for these regions.

FUNCTIONS

       cm_open() declares the beginning of the use of the CM specified by cm_id.  The current release only supports (int)1 as cm_id.

       cm_initstruct contains the members shown below.
		 e_char *env_value;  /* unused */
		 struct usr_auth_info {
			int	     uid; /* user ID */
			char	     *user_name;/* user name */
			int	     gid; /* group ID */
			char	     *grp_name;/* group name */
			int	     hid; /* host ID */
			char	     *host_name;/* host name */
		 }

       cm_close() terminates the session initiated by cm_open().

       cm_put() passes operations for regions to the CM, and receives instructions from the CM.  The env_to_cm structure contains the request  and
       information  to	be  passed to CM.  The cm_to_env structure contains the operation request generated as a result of processing the request,
       and the pointer to that structure is given as the return value of the cm_put() function.

   OPERATIONS SENT TO CM
       The env_to_cm structure consists of the following elements.

		 struct env_to_cm    *ec_next; /* pointer to next structure */
		 Operation_type      ec_operation; /* operation sent to CM */
		 union {
			/* parameters required for the operation */
		 }

       A single call can send multiple requests by chaining the sets of an operation and associated parameters.  ec_next being NULL represents the
       last structure in the chain.

       The following lists the operations defined in <mle/cm.h>.

	   CM_RESET		  Reset request for CM
	   CM_SIMPLE_EVENT	  Data input to CM
	   CM_CMON		  Reporting that CM became ON
	   CM_NOP		  No operation

       The following operations are used in the selection region.
	   CM_NEXT_CANDIDATE	  Direct CM to send next candidates
	   CM_PREV_CANDIDATE	  Direct CM to send previous candidates
	   CM_SELECT		  Notify CM of selected candidate's id
	   CM_ABORT_SELECTION	  Direct CM to stop selection
	   CM_SELECT_INVALID	  Notify CM of invalid selection

   OPERATIONS SENT FROM CM
       The cm_to_env structure consists of the following elements.

		 struct cm_to_env    *ce_next; /* pointer to next structure */
		 Operation_type      ce_operation; /* operation sent to CM */
		 union {
			/* parameters required for the operation */
		 }
       Since  multiple sets of an operation and associated parameters may be chained, the user should process the request from CM until encounter-
       ing a structure where ce_next is NULL.

       The following operations are defined in <mle/env.h>.
	   ENV_COMMIT		  Pass the committed string
	   ENV_SET_CURRENT_REGION Specify active region
	   ENV_NOP		  No operation
	   ENV_CM_OFF		  Switch to CM OFF state
	   ENV_SETKEY_CM_ON	  Define key for making CM active

       The following operations are used in the intermediate region.
	   ENV_INTERM_RESET	  Reset intermediate region
	   ENV_INTERM		  Identify intermediate region

       The following operations are used in the selection region.
	   ENV_SELECT_RESET	  Reset selection region
	   ENV_SELECT		  Start selection and identify selection region
	   ENV_SELECT_END	  End selection
	   ENV_SELECT_NEXT	  Get next candidates
	   ENV_SELECT_PREV	  Get previous candidates
	   ENV_SELECT_COMMIT	  Request selected candidate to be committed
	   ENV_SELECT_NEXT_CAN	  Make next candidate active
	   ENV_SELECT_PREV_CAN	  Make previous candidate to be active
	   ENV_SELECT_TEST	  Test whether selected candidate can be comitted

       The following operation is used in the mode region.
	   ENV_SET_MODE 	  Display mode

       The following operations are used in the miscellaneous region.
	   ENV_MISC_RESET	  Reset miscellaneous region
	   ENV_M_INTERACTIVE	  Display interactive subregion
	   ENV_M_LABEL		  Display label subregion
	   ENV_M_MESS		  Display message subregion
	   ENV_M_MESS_NEXT_P	  Display next page of message subregion
	   ENV_M_MESS_PREV_P	  Display prev. page of message subregion

       Refer to mle/cm.h,mle/env.h and mle/cmkeys.h for a complete list of parameters.

BUGS

       Addresses returned from cm_put() and all parameter addresses should be treated as read-only data.  The  results	may  be  unpredictable	if
       these addresses are modified.

       In  JFP,  this  library	is  provided for a compatibility with a certain application which has ENV/CM type interface for its japanese input
       mothod.	Therefore, Misc Region is not supported.

								   27 March 1992							    cm(3X)