4.5.10 jp1Imdd.execCmd

This method executes a command specified in the parameter. The following table shows the details of the jp1Imdd.execCmd method.

Method name

Object jp1Imdd.execCmd(String host, String cmd, Object env, String envFile, String jp1user)

Parameters

If the file specified by envFile also contains the environment variable specified by env, the value specified by env takes precedence.

host

Specifies the name of the command execution host from 1 to 255 bytes.

cmd

Specifies the command to be executed and its arguments from 1 to 4,095 bytes. If the command name contains any space character, it must be enclosed in double quotation marks (").

env

Specifies the environment variable value for the value of the object, using the environment variable when the command is executed on the execution host as a key to the object. Up to 30 env parameters can be specified.

If it is not needed, specify null. Specify both the object key and value together from 1 to 7,107 bytes.

envFile

The name of the environment variable file. Specify the absolute path to the file on the execution host between 1 and 255 bytes. If it is not needed, specify null or an empty string.

jp1user

Specifies a JP1 user name from 1 to 31 bytes. If the value is specified, the command is executed as the primary user of the specified JP1 user. If it is not needed, specify null or an empty string.

Return values

An object that stores the execution result of the command. The object contains the following keys and values:

No	Description		Key	Value
1	If the command is executed remotely and successfully (the executed command is started successfully)^#		"`response`"	response object
		Keys and values that are stored in the response object	"`rc`"	Return value of the executed command
			"`stdOut`"	String of the standard output of the command, converted into UTF-8
			"`stdError`"	String of the standard error output of the command, converted into UTF-8
2	If the remote execution of the command fails (the executed command cannot be started successfully)		"`error`"	error object
2		Keys and values that are stored in the error object	"`rc`"	error code

#:: Even if the execution command specified in cmd does not exist, if the connection to the execution host is successfully established and cmd.exe or /bin/sh starts up, the return value, standard output, and standard error output are returned. Furthermore, the return value, standard output, and standard error output that are returned depend on the cmd.exe or /bin/sh of the execution host.

Exception

IOEXception

When an I/O error occurs

Prerequisite

To use this method, JP1/Base 12-10 or later must be installed in the execution host and added to IM configuration management.

Commands that can be executed

The following shows the types of commands that can be executed by the jp1Imdd.execCmd command.

If a command is executed on a Windows host:

Executable file (.com, .exe)
Batch fil (.bat)

If a command is executed on a UNIX host:

UNIX command
Shell script

Important: If a command is executed, it works assuming that the language setting is the same as the one with which JP1/Base is running. Do not change characters with the LANG environment variable.

The following commands cannot be executed:

Command that needs interactive operations
Command that opens a window
Command that involves escape sequences and control codes
Command that does not exit, such as a daemon
Command that needs interactions with the desktop, such as the Windows messaging mechanism and DDE (In Windows)
Command that shuts down the OS, such as shutdown and halt
Command that exits JP1/Base
jbs_spmd_reload command

How to execute a command

The remote command execution function executes a command with the following operations.

In Windows:

cmd.exe /c specified-command

InUNIX:

The login shell of the OS user is used. If it is not specified, /bin/sh is used.

/bin/sh -c specified-command

Execution user

The command is executed as the primary user of the JP1 user specified in the jp1User argument. If jp1User is set to null or an empty string, the command is executed with the following privilege of the execution host.

In Windows: SYSTEM
In UNIX: root

Important: If UAC is enabled on the execution host, the primary user of the JP1 user specified by the jp1User argument must be the built-in Administrator user.

Limits

The following table describes the limits that apply to jp1Imdd.execCmd method.

Table 4‒35: Limitations to jp1Imdd.execCmd method
No.	item	Value to be specified
1	Time out (second)	3600
2	Size of the standard output and standard error output (MB)	20

Error code

The following table shows the error codes when the execution target command fails to be started.

Table 4‒36: Error codes when the execution target command fails to be started
No.	Error case	Error code	Status
1	The specified parameter is invalid	1	Revise the specified parameter and re-execute the command.
2	A connection to the execution host failed	2	Check to see if the JP1/Base service is running on the execution host.
3	A timeout occurred^#	3	A timeout occurred due to a high load on the execution host or the network. Wait a while and then re-execute the command.
4	The amount of incoming data exceeded its upper limit	4	The size of the standard output or the standard error output for the executed command exceeded its upper limit. Revise the output of the executed command.
5	The environment variable file cannot be read	5	Check to see if the file specified by the `envFile` argument exists on the execution host.
6	The JP1 user is invalid	6	Check the JP1 user specified by the `jp1User` argument to see if: The user is mapped with the OS user on the execution host. The server hosts with user mapping contain the JP1/IM hosts.
7	Internal error	255	Use the data collection tool to collect data and contact the system administrator.

When a timeout occurs, the process of the command currently running is terminated.

Note

If UAC is enabled on the execution host, the primary user of the JP1 user specified for jp1User must be the built-in Administrator user.

To Page Top