1.4 Precautions for using commands
(1) Precautions for using Application Server commands in Windows Server 2012, Windows Server 2008, Windows 8, Windows 7, or Windows Vista
The commands provided with the Application Server must be executed with administrator privileges. You open Administrator, and choose Command Prompt to execute commands provided with the Application Server.
To open Administrator, and choose Command Prompt, use the functionality provided with Windows Server 2012, Windows Server 2008, Windows 8, Windows 7, or Windows Vista. An example describing the start method is given below:
- Click Start.
- Choose All Programs, and then Accessories.
- Right-click Command Prompt and then click Execute As Administrator.
If the administrator password or confirmation is requested, enter the password or specify the confirmation information as per the instructions in the window.
(2) Precautions for using server management commands
- If an insufficient memory error occurs during the command execution, and the command cannot be executed normally, specify the JavaVM option -Xmx<size> with the USRCONF_JVM_ARGS key in the option definition file (usrconf.bat) used for the server management command, and extend the maximum size of the memory allocation pool. '64 MB' is the default value when -Xmx<size> is not specified.
- Example:
- In Windows
- set USRCONF_JVM_ARGS=-Xmx512m
- In UNIX
- set USRCONF_JVM_ARGS="-Xmx512m"
- If a large file is to be operated, the java.lang.OutOfMemoryError message might be displayed in the console in which the server management commands are activated. In such cases, change the memory allocation size of JavaVM by using the -Xms and -Xmx options of the USRCONF_JVM_ARGS key used in the option definition file (usrconf.bat in Windows and usrconf in UNIX) for the server management commands.
Coding example:
set USRCONF_JVM_ARGS="-Xms64m -Xmx256m"
- The encoding specified in the XML declaration part of the property file determines the applicable property file and does not affect the encoding of the Deployment Descriptor file on the server-side (the encoding of the server-side Deployment Descriptor file is always UTF-8).
- When using Windows Server 2012, Windows Server 2008, Windows 8, Windows 7, or Windows Vista, if Command Prompt is not started with the administrator privilege, an administrator privilege error occurs, and then the termination code 9 is returned.
- In UNIX, if the Component Container administrator is set up, apart from the superuser even the general users can execute the command.
In Windows Server 2012, Windows Server 2008, Windows 8, Windows 7, or Windows Vista, even if the user has the administrator permission, the command cannot be executed if Command Prompt is not started using the administrator privilege.
- You cannot use the supplementary characters of Unicode in the directory and file names.
If characters that cannot be converted to character encoding at runtime are output in the log file, such characters are converted to ?.
- The execution permission setup in the Bean method is valid only in the create method, business method, and remove method. The execution permission setup using the server management command for other methods is ignored.
- If you establish a remote connection with J2EE servers or batch servers using commands, the KDJE30045-E message might be displayed in the console and in the dialog box. In such cases, you match the versions of server management commands and J2EE servers, or the version of Cosminexus Component Container.
- If the cjresetsv command is remotely executed from a version of Cosminexus Component Container earlier than 06-00, the KDJE37516-I message is displayed; however, the exclusion information of the server management command is not reset.
- If you execute a delete node command and display list node command simultaneously for a same resource, the KDJE39057-E message might be displayed on the console where the J2EE server or batch server is running, however, there will be no impact on the operations of the J2EE server or batch server.
The delete node commands and display list node commands are as follows:
Delete node server management commands
cjdeleteapp
cjdeleteres
cjundeployrar
cjdeletelibjar
Display list node server management commands
cjlistapp
cjlistres
cjlistrar
cjlistlibjar
- If you want to include a space in the command option of server management commands, specify the space as follows:
In Windows
Enclose the command option with a space within double quotation marks ("").
Example: When Display name acquires the resource adapter information of TP1/Message Queue - Access
cjgetresprop -type rar -resname "TP1/Message Queue - Access" -c C:\temp\rar.xml
In AIX
Enclose the command option with a space within double quotation marks ("").
Example: When Display name acquires the resource adapter information of TP1/Message Queue - Access
cjgetresprop -type rar -resname "TP1/Message Queue - Access" -c /home/rar.xml
Other UNIX
Enclose the entire command option within double quotation marks ("") and also enclose the command option containing the space within single quotation mark ('').
Example: When Display name acquires the resource adapter information of TP1/Message Queue - Access
cjgetresprop "-type rar -resname 'TP1/Message Queue - Access' -c /home/rar.xml"
However, the command might not function properly in the following cases:
- There are two or more consecutive spaces in the option enclosed within single quotation mark.
- There is a space immediately after the first single quotation mark or there is a space just before the last single quotation mark.
- In UNIX, when a command option of the server management commands includes an exclamation mark (!), enclose the command option that includes an exclamation mark (!) within single quotation marks (').
Example: When displaying a list of Connection Pools for Connector 1.5
cjlistpool server-name -nameserver provider-URL resource-adapter-display-name!connection-definition-identifier
- Do not specify a string beginning with an underscore "_" or a string with consecutive underscores "__" in display-name-of-queue specified in the tag (linked-to tag in the resource-env-ref tag) for the resource environment variable in the attribute file to be used with the server management commands.
- In the application, do not include the CLASSPATH environment variable or the classes referenced from the classes included in the class path that are specified in the option definition file for server management commands.
- When you are executing the server management commands in Windows, do not use strings containing ^ or & in the path to be setup in the PATH environment variable or CLASSPATH environment variable.
- If vbroker.se.iiop_tp.scm.iiop_tp.listener.port is specified in the usrconf.properties (system property file for server management commands), you cannot use Server Plug-in or HCSC commands and the server management commands together.
- When you are operating a J2EE server of another host or using multiple NICs, you must define the webserver.connector.http.permitted.hosts key beforehand, in usrconf.properties (user property file for J2EE servers). For details on the webserver.connector.http.permitted.hosts key, see 2.4 usrconf.properties (user property file for the J2EE server) in the uCosminuexus Application Server Definition Reference Guide.
(3) Precautions for using commands with the Smart Composer functionality
For using the following commands, you enable the monitoring of J2EE server operations (specify true in the ejbserver.instrumentation.enabled parameter) in the configuration settings of the J2EE server with the physical tier:
- cmx_start_application
- cmx_stop_application
- cmx_start_resource
- cmx_stop_resource
You use the Easy Setup definition file to specify the settings for physical tier. For details on the Easy Setup definition file, see 4.6 Easy Setup definition file in the uCosminexus Application Server Definition Reference Guide.
(4) Precautions for enabling the functionality for omitting the admin user account
Among the commands used with the Manager Server and Smart Composer, there are some commands that operate differently when the functionality for omitting the admin user account is enabled. The following table lists and describes the commands:
Table 1-8 Commands that operate differently when the functionality for omitting the admin user account is enabled
Function | Command name | Operation when the functionality for omitting the admin user account is enabled |
---|
Commands used with Manager Server | mngsvrctl command | The following setup of the argument setup is disabled:
- -u admin-user-ID
- -p admin-password
- -nu admin-user-ID
- -np admin-password
Even the message is output, the setup process is executed as usual. The setup of the arguments start and stop is disabled. You cannot set up or change the admin user account and the password. |
| mngsvrutil command | The setup of the following arguments is disabled:
- -u admin-user-ID
- -p admin-password
|
Commands used with Smart Composer | Other than the cmx_admin_passwd command | |
| cmx_admin_passwd command | The setup value is disabled and the message is output. You cannot set up or change the admin user account and the password. |
You can set up the default value for the options of the command as common definition files. These files operate differently when the functionality for omitting the admin user account is enabled. The following table lists and describes the files in which the operations are different:
Table 1-9 Files in which the operations are different when enabling the functionality for omitting the admin user account
File name | Command definition file type | Operation when the functionality for omitting the admin user account is enabled |
---|
.mngsvrutilrc | mngsvrutil command definition file | The settings of the following properties are disabled:
- mngsvrutil.connect.userid
- mngsvrutil.connect.password
|
mngsvrutilcl.properties |
.cmxrc | Command definition file used with Smart Composer | The settings of the following properties are disabled:
- cmx.connect.userid
- cmx.connect.passwd
|
cmxclient.properties |
.mngsvrmonitorrc | mngsvrmonitor command definition file | The settings of the following properties are disabled:
- mngsvrmonitor.connect.userid
- mngsvrmonitor.connect.password
|
(5) Precautions for using the virtual server manager commands
- You can execute the virtual server manager commands when the virtual server manager is running. If a command is executed when the virtual server manager is not running, a message is output and the operation terminates with an error.
- The start and stop messages of the virtual server manager commands and the command execution results are output to the standard output.
- Before you execute a command, make sure that the log output directory and the log file are writable. A log is not output if the log output directory and the log file are not writable.
- The virtual server manager commands do not have executing user restrictions. However, in Windows, you must note the following items depending on the type and the executing user of the OS in which the command is executed:
- For an OS with disabled UAC (user account control)
If a user who does not have Administrator permissions executes the virtual server manager commands, make sure that the log output directory and the log file are writable before the command is executed. A log is not output if the log output directory and the log file are not writable.
If a user with Administrator permissions executes the virtual server manager commands, no specific precautions need be taken.
- For an OS with enabled UAC (user account control)
If a user who does not have Administrator permissions executes the virtual server manager commands, the log might be output to a directory different from the log output directory specified in manager.cfg (Manager configuration file), depending on the virtualization of the files for UAC (user account control), which is an OS functionality.
If a user with Administrator permissions executes the virtual server manager commands, no specific precautions need be taken.
(6) Display name containing characters other than single-byte alphanumeric characters
The J2EE servers use the display names set up for J2EE applications or resources (value of the <display-name> tag of DD) as identifiers. If the display name contains a character other than universal characters and single-byte alphanumeric characters (0 to 9, A to Z, and a to z), the character is converted to an underscore (_), and an identifier is generated. Depending on the set value, the identifier generated during the conversion might be repeated and the operation might fail. Do not use the characters other than single byte alphanumeric characters or underscores, in the display name.
If the display name contains characters other than single byte alphanumeric characters, the J2EE server outputs a warning message (KDJE42374-W).
(7) File and directory name to be specified in command arguments
Do not use a hash mark (#), percent mark (%), or question mark (?), in the file name and the name of the directory that stores that file that is to be specified in the arguments of the command used with the Smart Composer functionality or Management Server.
If you use a hash mark, percent mark, or question mark, the following message is output and the command processing is aborted:
KEOS24007-E The definition file is invalid. file name = file-name line number = 1 column number = 1 details = KECX01024-E Content is not allowed in prolog.
(8) Precautions related to the commands used with JavaVM (In Windows)
The following commands provided with Application Server create temporary files in a directory acquired by the GetTempPath() functionality of Windows API:
- javagc command
- jheapprof command
- eheapprof command
You must have write permission for the directory acquired using the GetTempPath() functionality to operate the commands properly. Also, do not delete this directory when the JavaVM process is being executed.
In Windows Server 2012, Windows Server 2008, Windows 8, Windows 7, and Windows Vista, do not specify the system directory of Windows, in this directory.
(9) Precautions related to the commands used with CTM (In Windows)
A user, belonging to the Administrators group, must execute the commands used with CTM.
(10) Precautions related to the commands used with the performance analysis trace (In Windows)
A user who executes the cprfstart command must execute the commands used with the performance analysis trace.