NAME

dtimsstart — launches an input method server

SYNOPSIS

dtimsstart [-env] [-ims name] [-shell name] [-host hostname] [-imsopt options] [-list]

DESCRIPTION

The dtimsstart command launches an IMS (Input Method Server). dtimsstart is normally invoked automatically at Xsession startup (user login) by the script /usr/local/dt/config/Xsession.d/0020.dtims.

Depending on the currently selected locale, environment variables, configuration files, and command-line options, dtimsstart displays a selection window from which you can select the IMS you want to use. Once you select the IMS, dtimsstart starts it and waits until the IMS completes its startup. This is to ensure that applications wishing to connect to the IMS can do so. dtimsstart then sets the XMODIFIERS environment variable to ensure that clients can connect to the selected IMS. Finally, dtimsstart exits.

Once you select an IMS from the selection window, dtimsstart saves the selection in the IMS Selection File. To have dtimsstart automatically start the previously selected IMS, set the IMS Selection Mode to resume-current-input-method. You access the IMS Selection Mode by executing the DtImsMode action located in Desktop_Tools in the Application Manager.

For IMS Selection Mode, you can choose:

ask-at-login: Instructs dtimsstart to display the selection window and prompt you for an IMS each time it is invoked.
resume-current-input-method: Instructs dtimsstart to automatically start the last selected IMS by using the saved IMS Selection File and without displaying the selection window.

Remote Execution of IMS

If you use the -host option to have dtimsstart start an IMS on a remote host, dtimsstart does the following:

•: Executes the DtImsGetRemoteConf action to retrieve IMS configuration data from the specified remote system
•: Lists the IMSs registered on the remote system in the selection window
•: Executes the DtImsRunRemoteIms action to start the selected IMS on the remote system.

For more information on configuring remote execution, refer to the Common Desktop Environment: Advanced User's and System Administrator's Guide.

OPTIONS

The following options are available:

-env: Outputs the contents of the XMODIFIERS environment variable to stdout. dtimsstart automatically updates this variable to reflect the currently selected IMS. Use this option to verify that the intended IMS is the one that is being started. If you omit this option, no output occurs.
-ims name: The name of the IMS to be started. If you specify this option, dtimsstart starts the IMS without displaying the selection window. If you omit this option, dtimsstart displays the selection window.
-shell name: The output format to use, of output, if -env is specified. If you omit this option, dtimsstart uses the value of $SHELL as the default.
-host hostname: The name of the host on which the IMS is to run. If you omit this option, dtimsstart uses the local host as the default.
-imsopt options: The command line options for the selected IMS.
-list: Instructs dtimsstart to output the names of input methods registered on the system and then exit immediately.

EXIT STATUS

0: The IMS was started successfully.
1: Execution failed for one of the following reasons:

•: The started IMS did not complete its initialization within the timeout period.
•: The started IMS process aborted.
•: The IMS specified by the -ims option is not registered.

2: A syntax error was found.

ENVIRONMENT VARIABLES

dtimsstart references the following environment variables:

HOME: The home directory.
LANG: The locale.
DISPLAY: The type of display on which IMS is to be run.

It sets the XMODIFIERS variable to the name of the selected IMS to support application and client connections.

ACTIONS/MESSAGES

The following actions relevant to dtimsstart are defined in the dtims.dt file.

DtImsMode: Change the IM Selection Mode. This action is located at Desktop_Tools in the Application Manager.
DtImsGetRemoteConf: Retrieve IMS configuration data on a remote system (used internally by dtimsstart).
DtImsRunRemoteIms: Run an IMS on a remote system (used internally by dtimsstart ).

ERRORS/WARNINGS

dtimsstart can output the following error messages to stderr:

invalid option `string': Correct the indicated option string.
environment variable `HOME' not defined: Make sure that HOME is set properly.
environment variable `LANG' not defined: Make sure that LANG is set properly.
environment variable `DISPLAY' not defined: Make sure that DISPLAY is set properly.
cannot open display ‘display_name’" 10: Make sure that DISPLAY is set to the correct value.

dtimsstart can display the following error messages in an error dialog box:

cannot open file [/usr/local/dt/config/ims/start.conf ]: This is an installation error. Re-install the package.
cannot create file [file_path]: Make sure the file and its parent directory have write permission.
cannot create directory [$HOME/.dt/ims]: Make sure the parent directory has write permission.
missing `entry_name' entry in configuration: file [file_path]" 10 Correct the indicated entry in the indicated file.
another `dtimsstart' is already running: Terminate the already running dtimsstart and then restart.
cannot create selection file [file_path]: Make sure the indicated file has write permission.
no ims configuration file for `ims_name': The indicated IMS is registered in the locale configuration file, but its IMS configuration file does not exist.
ims `ims_name' not registered: The indicated IMS name is not registered in the locale configuration file.
no executable file for `ims_name': [file_path]" 10 The indicated IMS executable does not exist.
ims `ims_name' is already running: The indicated IMS is already running on the display.
cannot execute ims `ims_name': The fork call failed. The errno is shown in the log file, $HOME/.dt/ims/imslog.
ims `ims_name' aborted: The IMS process aborted. Refer to the log file, $HOME/.dt/ims/imslog, for details.
ims `ims_name' is not available yet: The indicated IMS was not available within the 3-minute timeout period.
unknown host `host_name': The network address of the indicated host cannot be found.
no ims registered on `host_name': No IMS is registered on the indicated host for the current locale.
ims `ims_name' not registered on: `host_name'" 10 The indicated IMS is not registered on the indicated host.

Note that other error messages can be generated by DtActionInvoke or various Xt functions. These messages are self-explanatory.

FILES

/usr/local/dt/bin/dtimsstart: dtimsstart executable
/usr/local/dt/app-defaults/&<locale_name>/Dtimsstart: dtimsstart resource file
/usr/local/dt/appconfig/types/&<locale_name>/dtims.dt: action definition file
/usr/local/dt/appconfig/appmanager/&<locale_name>/Desktop_Tools/DtImsMode: action files for DtImsMode
/usr/local/dt/lib/nls/msg/&<locale_name>/dtimsstart.cat: message catalog file
/usr/local/dt/config/Xsession.d/:0020.dtims: Xsession.d script file
/usr/local/dt/config/ims/start.conf: dtimsstart configuration file
/usr/local/dt/config/ims/&<locale_name>: locale entry files
/usr/local/dt/config/ims/&<ims_name>: IMS entry files
$HOME/.dt/ims/&<locale_name>: IMS selection file
$HOME/.dt/ims/&<display_name>/&<locale_name>: display-specific IMS selection file
$HOME/.dt/ims/imslog: dtimsstart log file

Resource Files

dtimsstart searches a proper resource file in the following order and loads the first file successfully opened.

1.: $HOME/.dt/&<display-name>/current/dt.resources
2.: $HOME/.dt/&<display-name>/home/dt.resources
3.: $HOME/.dt/sessions/current/dt.resources
4.: $HOME/.dt/sessions/home/dt.resources
5.: /usr/local/dt/config/&<locale-name>/sys.resources
6.: /usr/local/dt/config/C/sys.resources

Configuration Files

dtimsstart refers to the following configuration files:

•: Locale Entry file
•: IMS configuration file
•: IMS Selection file

The location and format for each configuration file is listed below.

Locale Entry File

This file lists the IMSs that support the locale. Its location is /usr/local/dt/config/ims/&<locale_name>. The format is:

@Default: ims_name

ims_name: label_string

For example:

/usr/local/dt/config/ims/ja_JP.SJIS
@Default:  xjim
xjim:      HP XJIM
atok8:     ATOK8
vje:       VJE-gamma
egbridge:  EGBridge
none:      No Input Method

IMS Entry File

This file describes the attributes of an IMS. Its location is /usr/local/dt/config/ims/&<ims_name>. The format is:

attribute_name: attribute_value

The IMS attributes are:

protocols: A required String that lists the supported protocols. The supported XIM protocols are XIM, Ximp, and Xsi.
server_name: A required String that identifies the IMS name (used to update the XMODIFIERS environment variable).
cmd_path: A required Path type that specifies the absolute path of the executable file for the identified IMS server. A built-in keyword is used for the local IM built-in Xlib, which does not need a separate process.
cmd_param: A String that specifies the command line option(s) for the IMS server.
env_set: A String that identifies the environment variables to be set, excluding XMODIFIERS.
env_unset: A String that identifies environment variables to be unset, excluding XMODIFIERS.
env_pass: A String that identifies the environment variables to be passed to a remotely executing IMS, excluding LANG, DISPLAY, and XMODIFIERS.
has_window: A Bool indicating whether the IMS has its own main window appearance or not. The default is False.
no_server: A Bool indicating whether dtimsstart should start the IMS or not. It should be True for the local IM, since it doesn't require any server process started by dtimsstart. The default is False.
no_remote: A Bool indicating whether the IMS allows remote execution or not. The default is False.
no_option: A Bool indicating whether the IMS allows the command-line option or not. If True, any options specified by -imsopt are ignored, though the value of the cmd_param entry is always applied regardless of this value. It should be True for the local IMS. The default is False.

Note:

For entries that accept multiple values, the values are separated by white space(s). If multiple entries of the same name appear in the file, only the last entry is used.

For example:

/usr/local/dt/config/ims/xjim
protocols:    XIM Ximp
server_name:  xjim
cmd_path:     /usr/bin/X11/xjim
cmd_param:    -iconic
env_set:
env_unset:
env_pass:
has_window:   true

IMS Selection File

This file saves the most recently selected IMS for each locale. Its location is $HOME/.dt/ims/[&<display_name>/]&<locale_name>. The format is:

entry_name: entry_value

The selection file entries are:Caret

@SelectMode: The most recently set IMS Selection Mode. Valid values are 0 (zero) (for ask-at-login) and 1 (for resume-current-input-method ).
@ImsName: The name of the most recently selected IMS.
@HostName: The name of the host on which the IMS runs.

For example:

$HOME/.dt/ims/ja_JP.SJIS
@SelectMode:  1
@ImsName:     atok8
@HostName:    host-A

EXAMPLE

The command to execute dtimsstart in the /usr/local/dt/config/Xsession.d/0020.dtims script is as follows:

eval  ` /usr/local/dt/bin/dtimsstart  -env -shell ksh `