Specify the complete path names of the external programs you wish to have start at the indicated times (before installation, after installation, and in the event of an installation error). You can select the applicable program based on the specified complete path from the dialog box that is displayed by clicking the Browse buttons to the right of Before installation, After installation, and At installation error. If Take system conditions from file is specified on the System Conditions page, you cannot specify path names.

If you are remotely installing JP1/Software Distribution Client, external programs can be started only immediately before installation. Even if you specify that the external programs be started immediately following installation or when an installation error occurs, such a specification is ignored.

A specified external program must report whether or not it terminates processing normally. For details about how to report external program termination reporting, see (2) External program termination report. The handling of the termination message received from an external program is specified in the External Program Options dialog box, which appears when a Details button is clicked. For details, see (3) Handling of external program termination message.

You should note the following points about specifying an external program:

• You must specify as an external program a file whose extension is .exe, .bat, or .cmd.
• You can specify an external program path as up to 256 characters.
• If the path name of the external program contains a space, you must enclose the entire path name in quotation marks (").
• The path name of an external program cannot contain the character string %HITACHI_REG\xxx% (xxx: any characters). This character string indicates the specific path of a Hitachi program product and is a JP1/Software Distribution reserved word that general users may not use.
• If remote installation executes in the background installation mode (Windows NT), an external program to be started must not require any interactive responses. Such requests for a response are not displayed, even if the program provides them.
  However, if you execute a program that uses a Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 or Windows Vista GUI, dialog boxes that request an interactive response may continue to be displayed for the executed program. To prevent this, specify the following settings:
  
  • Specify 1 or any greater value in the Time-out field of the External Program page.
  • In the External Program Options dialog box that is displayed by clicking the Details button on the External Program page, select the Monitor the time of the external program check box.
  • In the External Program Options dialog box that is displayed by clicking the Details button on the External Program page, select Finishes unsuccessfully for the When an external program error occurs, the job setting.
• Do not specify a 16-bit application as an external program. If you attempt to install a 16-bit application on a Windows NT client in the background installation mode, the client will freeze up.

If you need to specify startup of an external program in a package to be distributed to a UNIX client, see (5) Notes on starting an external program on a UNIX client.

Time-out

Specify the maximum amount of time to be allowed for monitoring for a response from an external program specified in Start external program. You can select the units and specify a time limit of between 0 and 21,600 seconds (360 minutes or 6 hours) for wait for termination of an external program to protect against the possibility of the external program going into an endless loop. Specify 0 to not monitor for a response. The default is 1 (in seconds). This specification is valid only when the Monitor the time of the external program check box is selected in the External Program Options dialog box. For details about the External Program Options dialog box, see (3) Handling of external program termination message.

The specified value is valid for all external programs that will be started Before installation, After installation, and At installation error. You cannot specify different timeout periods for individual external programs. You can view but you cannot modify a package's external program monitoring time if it was packaged (its resource was registered) with the UNIX version of Packager.

When you install a user program at a remote destination, you can start an external program before or after installation or in the event of an installation error.

The external program must send a termination code or Windows Message to the server to report whether or not its processing was completed successfully. This section explains how to set the values for reporting the result using a termination code or Windows Message.

When an external program starts immediately after installation, completion of distribution is reported when the external program terminates.

Termination code specified

For the program termination code to report to the script, you must set 0 for normal termination and a value in the range of 1-255 for a result other than normal termination. The shell function returns control when the program started by the script terminates.

Windows Message specified

When you use Windows Message to report the processing result, you must use the RegisterWindowMessage() Windows API function to define the character string DMP_UAP_QUIT, then use the returned message ID to report the program's processing result to all top-level windows. The third argument of the PostMessage() Windows API function is the processing result code.

The procedure for defining the DMP_UAP_QUIT character string is shown in the example below. In this example, the variable DMRtn is the processing code.

Example

UINT MsgId;
WORD DMRtn;
 
MsgId = RegisterWindowMessage("DMP_UAP_QUIT");
DMRtn = 0;    /* Set termination code: normal */
(VOID)PostMessage(HWND_BROADCAST,
MsgId,
DMRtn,
NULL);

You specify the handling of the external program termination message in the External Program Options dialog box, which is displayed when a Details button is clicked. The contents of this dialog box are different when the Details buttons for Before installation and After installation are clicked from when the Details button for At installation error is clicked. In the latter case, the At time-out, the end status is assumed to be and When an external program error occurs, the job sections are not displayed. The following figures show the External Program Options dialog box, which opens in these cases.

Figure 2-22 External Program Options dialog box displayed by clicking the Details buttons for Before installation and After installation

Figure 2-23 External Program Options dialog box displayed by clicking the Details button for At installation error

Monitor the time of the external program

You use this option to specify whether or not the setting of Monitor the time of the external program specified on the External Program page in the Software Distribution Packaging dialog box is to be effective. The default is that this option is not selected.

When this check box is selected, the external program is monitored for the amount of time specified in Time-out.

When this check box is not selected, the external program is monitored indefinitely. The check box should be selected unless the external program needs to be monitored for longer than the amount of time specified in Time-out. This option is useful for an external program that will require a long time for database updating, etc.

Note

If the external program is not monitored, the job will hang up and the distribution results may not be available if, for example, the external program goes into an endless loop. To prevent such an occurrence, specifying a Time-out value is recommended.

At time-out, the end status is assumed to be

Specifies whether or not you wish to cancel the remote installation job and return an error message if the external program results in a timeout. The default is that Abnormal is selected. Normally, you should select Abnormal.

• Abnormal
  When the specified timeout value is reached, assumes that an error has occurred in the remote installation job and reports this assumption to the managing server or relay system. The external program is terminated.
  
• Normal
  When the specified timeout value is reached, assumes that the remote installation job was successful and reports this assumption to the managing server or relay system. You should select this option only if you want to make the external program resident for later use, in which case you should set a low value in Time-out.
  

End status is notified by

The external program must notify the server of the termination status of its processing. For this option, you specify the method for obtaining the external program's processing result. It is important to set this option correctly, because setting it wrong will cause the client to hang up. The default is that Exit code is selected.

• Windows message
  If the external program started from the client initiates another program, you can use this option to obtain that program's processing result. For example, you can start an external program on the client to process the remotely installed data and then register the processed data in the database using a program that sends a Windows message to report the result to the client.
  Note that this option applies only to the GUI installation mode. If you select Windows message in the background installation mode (Windows), the selection is changed automatically on the client to Exit code.
  
• Exit code
  Use this option for a program that returns a typical termination code.
  

When an external program error occurs, the job

Specifies whether or not an error is to be assumed when the external program's return information (termination code or processing result code) is not 0. The default is that Finishes unsuccessfully is selected.

• Finishes unsuccessfully
  Assume an error whenever the external program's return value is not 0. Use this option for a program that can be relied on to produce accurate return information, such as an EXE file. The obtained return information is set in the user status in the maintenance code. You can check the maintenance code in the Detailed Information dialog box, which is displayed from the Remote Installation Manager's Job Status window.
  
• Continues
  Continue processing even when the external program's return value is not 0. Use this option for a program that cannot be relied on to produce accurate return information, such as a BAT file.
  

If an external program is to be started on the client during remote installation, the external program execution permission depends on the client's OS. To run external programs, you need system permissions or logon user permissions. The following table shows the external program execution permission for each client OS.

Client's OS	External program execution permission
Windows 98 and Windows Me	Logon user permission
Windows Server 2003, Windows XP, Windows 2000, and Windows NT 4.0	System permission or logon user permission
Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, and Windows Vista	System permission

If the client's OS is Windows Server 2003, Windows XP, Windows 2000, or Windows NT 4.0, the external program execution permission depends on the package installation method, the logon user's access permission, and the client setup settings. The following describes the conditions for running external programs by system permission for each package installation method; if the following conditions are not applicable, external programs are run by logon user permission. The execution permissions of some external programs do not allow them permission to access files, directories, network drives, and the registry. Also, it depends on the execution permissions of the external program as to whether the environment variable can be set.

• When installing by starting the Execute Job Backlog icon or from Package Setup Manager
  External programs are run using system permissions if the client's logon user does not have Administrator-level access permissions to the program and the settings on the Default Running Status/Polling and Security pages at the client setup satisfy the combination 1 or 2 shown in the following table.
  

  Settings at client setup	Combination of settings
  	1	2
  Client starts automatically at system boot check box on the Default Running Status/Polling page	Selected	Cleared
  Run the client with non-Administrator user permissions check box on the Security page	Selected	Selected
  Use the Package Setup Manager or Execute Job Backlog command when a client is not resident check box on the Security page	--	Selected

  Legend: --: Not applicable

  
  
• When installing a package for which the GUI installation mode has been set
  External programs are run by system permission if the access permission of the client's logon user is not Administrator permissions and the Run the client with non-Administrator user permissions check box is selected on the Security page at the client setup.
  If none of these conditions apply, external programs are run by the logon user permission.
  

For details about the setup items during client setup, see 6.2 Setting up Client in the manual Setup Guide.

You should note the following points about specifying startup of an external program in a package to be distributed to a UNIX client:

• Do not use >, <, |, &, or $, which have special meanings in shell programs.
• If an installation error occurs, the external program will not start.
• The path specification for an external program to be started before installation will differ from the specification for an external program to be started after installation depending on whether or not an installation date/time is specified on the Schedule page. Even if the path specification method is wrong, both packaging and the job can be executed. However, no external program will start on the UNIX client at the distribution destination. In such a case, the job will not result in an error and will terminate normally.
  The following table shows the differences in the specification:
  

  Installation date/time specified?	Path specification for an external program to be executed
  	Execute before installation	Execute after installation
  Yes	Cannot be specified.	Specify a path of up to 40 characters. A path containing a space cannot be specified. If there are any arguments for the post-processing program, enclose the path and the entire set of arguments in double quotation marks ("). If an argument contains a space, enclose the argument in single quotation marks (').
  No	To specify only an external program to be started before installation, specify its path as up to 60 characters. To specify only an external program to be started after installation, specify its path as up to 64 characters. To specify external programs to be started before and after installation, specify their paths as up to 60 characters combined. Up to 18 character strings (arguments) can be specified. Consecutive spaces are treated as a single delimiter. The single quotation mark (') is not treated as part of the argument. Shell variables are invalid, because they are treated as character strings. Do not specify a process that may go into wait status.