Hitachi

JP1 Version 12 JP1/IT Desktop Management 2 Distribution Function Administration Guide

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.

Figure 7‒15: External Program page

[Figure]
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 7.2.10(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 7.2.10(3) Handling of termination notifications from external programs.

When specifying an external program, note the following:

To set the startup of an external program for a package to be distributed to an agent for UNIX, see 7.2.10(5) Notes on starting external programs on agents for UNIX.

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 7.2.10(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.

To Page Top

(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);

To Page Top

(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.

Figure 7‒16: The External Program Options dialog box displayed by clicking the Details button to the right of "Before installation" or "After installation"

[Figure]
Figure 7‒17: The External Program Options dialog box displayed by clicking the Details button to the right of "At installation error"

[Figure]
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 Install Manager.

Continues

Continues processing even if return information from the external program is a value other than 0.

To Page Top

(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 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2

System privileges

To Page Top

(5) Notes on starting external programs on agents for UNIX

When you set the startup of an external program for a package to be distributed to an agent for UNIX, note the following:

To Page Top

Copyright (C) 2019, 2022, Hitachi, Ltd.

Copyright (C) 2019, 2022, Hitachi Solutions, Ltd.

Copyright, patent, trademark, and other intellectual property rights related to the "TMEng.dll" file are owned exclusively by Trend Micro Incorporated.