7.2.10 External Program page
On this page, specify the external programs to be started on the managed computer before and after installation, and when an installation error occurs.
- Organization of this subsection
(1) Start external program
In this area, specify the path names of the respective external programs to be started immediately before and after installation, and when an installation error occurs. Click the Browse button to the right of Before installation, After installation, or At installation error, and then you can specify the full path to the selected program in the dialog box that appears.
Note that if you perform a remote installation of JP1/IT Desktop Management 2 - Agent, you can only start an external program immediately before installation. Even if you specify an external program to be started immediately after installation or when an installation error occurs, the specification is ignored.
The specified external program needs to notify the server whether processing has terminated normally. For details about the termination notification method, see (2) Termination notifications from external programs. You can also use the External Program Options dialog box (displayed by clicking the Details button) to specify the handling of termination notifications obtained from an external program. For details, see (3) Handling of termination notifications from external programs.
When specifying an external program, note the following:
-
For external programs, you can only specify files with extensions *.exe, *.bat, and *.cmd.
-
Specify a maximum of 256 single-byte characters for the path to an external program.
-
If the path to an external program includes spaces, enclose the entire path with double quotation marks (").
-
The path to an external program cannot include the string %HITACHI_REG\xxx% (xxx is any string). This string is a path specific to each Hitachi program product, and is reserved for JP1/IT Desktop Management 2.
-
If you perform a remote installation in background installation mode (Windows), specify a program without GUI. Even if you specify a program with GUI, GUI is not displayed.
However, if you execute a program with GUI in Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, or Windows Vista, a dialog box that requests the program to display GUI might remain displayed. To prevent this problem, note the following:
-
Set Time-out in the External Program page to 1 or more.
-
Select the Monitor the time of the external program check box in the External Program Options dialog box, which is displayed by clicking the Details button on the External Program page.
-
Select Finishes unsuccessfully for When an external program error occurs, the job of the External Program Options dialog box, which is displayed by clicking the Details button on the External Program page.
-
-
Do not specify a 16-bit application as an external program. If you perform a remote installation of a package on a Windows computer in background installation mode by specifying a 16-bit application as an external program, the computer hangs.
-
If you specify a console program or batch file for Start external program when executing the Install package job or Collect files from client job, the Windows Interactive Services Detection dialog box appears on the task bar.
- Time-out
-
Specify the upper limit and unit of the time period to monitor responses from the external program specified for Start external program. In case the external program enters an infinite loop, specify the time to wait for the external program to terminate, in the range from 0 to 21,600 seconds (360 minutes or 6 hours). If you do not monitor responses from the external program, specify 0. The default value is 1 (second). Note that this specification is valid only when you select the Monitor the time of the external program check box in the External Program Options dialog box. For details about the External Program Options dialog box, see (3) Handling of termination notifications from external programs.
This specification is valid for all external programs to be started immediately before and after installation, and when an installation error occurs. You cannot specify different monitoring times for each external program.
(2) Termination notifications from external programs
When you perform a remote installation of user programs, you can start external programs immediately before and after installation, and when an installation error occurs.
External programs need to issue an exit code or Windows message to notify the server whether processing has terminated normally. The setting methods for notification using an exit code and for notification using a Windows message are explained separately, as below.
If you start an external program immediately after installation, the completion of software distribution is notified when the external program finishes its execution.
- If you specified Exit code
-
For the exit code of the program that is posted to the script, specify 0 for normal termination, and specify any value from 1 to 255 for abnormal termination. When the program executed from the script terminates, the shell function returns control.
- If you specified Windows message
-
If external programs use Windows messages to notify their processing results, define string ITM_UAP_QUIT with the Windows API RegisterWindowMessage() function. Then, use the message identifier (that is returned) to notify the processing results of the programs to all top-level windows. A processing result code is set in the third argument of the Windows API PostMessage() function.
The following example shows how to define string ITM_UAP_QUIT. In this example, a processing result code is set for variable DMRtn.
- Example:
UINT MsgId; WORD DMRtn; MsgId = RegisterWindowMessage("ITM_UAP_QUIT"); DMRtn = 0; /* Exit code setting: Normal*/ (VOID)PostMessage(HWND_BROADCAST, MsgId, DMRtn, NULL);
(3) Handling of termination notifications from external programs
You can specify how to handle termination notifications from an external program by using the External Program Options dialog box, which is displayed by clicking the Details button. The contents of the window displayed by clicking the Details button to the right of Before installation or After installation differ from those displayed by clicking the Details button to the right of At installation error. The window displayed by clicking the Details button to the right of At installation error does not display At time-out, the end status is assumed to be or When an external program error occurs, the job. The two types of External Program Options dialog box that are displayed in these different scenarios are shown below.
- Monitor the time of the external program
-
Specify whether to enable the settings for Time-out on the External Program page of the JP1/ITDM2 Packaging dialog box. By default, this check box is not selected.
If you select this check box, the external program is monitored during the time period specified for Time-out.
If you do not select this check box, the external program is continuously monitored. Do not select this check box only if you need to monitor the external program for longer than the maximum time period that can be specified for Time-out. This is useful when an external program that is started performs time-consuming processing, such as database updating.
- Note
-
Unless external programs are monitored, jobs might hang in such cases as when the external programs enter an infinite loop, thereby preventing distribution results from being obtained. To prevent jobs from hanging, we recommend that you select the Monitor the time of the external program check box.
- At time-out, the end status is assumed to be
-
Specify whether to suspend a remote installation job and generate an error when the external program monitoring time is exceeded. By default, Abnormal is selected. Normally, leave the default setting unchanged.
- Abnormal
-
If the monitoring time is exceeded, this option regards the remote installation job as abnormal, and notifies the managing server or relay system, and then terminates the external program.
- Normal
-
Even if the monitoring time is exceeded, this option regards the remote installation job as normal, and notifies the managing server or relay system. Select this option only in such cases as when you want to make the external program resident after starting it. In this case, specify a shorter time value for Time-out.
- End status is notified by
-
External programs need to notify the server whether processing has terminated normally. In this area, select the method for obtaining the processing results of external programs. For the following packages, Windows message is selected by default:
-
Packages created by using the Packager
-
Packages for which GUI installation mode has been set
-
Packages for which the path to an external program is specified when a job is created
For all other packages, Exit code is selected by default.
If you specify incorrect settings, the agent might hang, and so when creating a job, you must check whether it is OK to leave the default settings unchanged.
- Windows message
-
Enables you to obtain the processing results of a program that is executed from an external program started from a managed computer. You can select this option only when GUI installation mode is selected as the installation mode. If you select Windows message while in background installation mode (Windows), this option is automatically changed to Exit code on the managed computer.
- Exit code
-
Select this option for programs that return a general exit code.
-
- When an external program error occurs, the job
-
In this area, specify whether to generate an error when return information (an exit code or processing result code) from the external program is a value other than 0. By default, Finishes unsuccessfully is selected.
- Finishes unsuccessfully
-
Generates an error when return information from the external program is a value other than 0. Select this option for programs from which you can correctly obtain return information, such as executable files. The obtained return information is set in the user status segment of the maintenance code. You can view the maintenance code in the Detailed Information dialog box, which is displayed from the Job Status window of the Remote Installation Manager.
- Continues
-
Continues processing even if return information from the external program is a value other than 0.
(4) External program execution privileges
When external programs are executed on a managed computer during remote installation, external program execution privileges differ according to the OS on the managed computer. External programs operate based on system privileges or logged-on user permissions. The following table describes the external program execution privileges according to the OS on the managed computer:
OS on the managed computer |
External program execution privileges |
---|---|
Windows Server 2003, Windows XP |
System privileges or logged on user privileges |
Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, Windows Vista |
System privileges |
When the OS on the managed computer is Windows Server 2003 or Windows XP, external program execution privileges differ according to the package installation method or logged on user access permissions. The conditions under which external programs operate based on system privileges are described according to the package installation method, as below. If the following conditions are not met, external programs operate based on logged on user privileges.
There might be no access permissions to files, directories, network drives, or registries, depending on the external program execution privileges.
-
When installing a package from the Package Setup Manager
If the logged-on user access permissions on the managed computer are not Administrator permissions, external programs operate based on system privileges.
-
When installing a package for which GUI installation mode has been set
If the logged-on user access permissions on the managed computer are not Administrator permissions, external programs operate based on system privileges.
If these conditions are not met, external programs operate based on logged-on user permissions.