13.19.20 USER_PROGRAM_INSTALLATION_CONDITIONS (specifying external programs)
In the USER_PROGRAM_INSTALLATION_CONDITIONS tag, specify the external programs to be started on managed computers before and after package installation and when an installation error occurs. This tag is used for the dcmcoll, dcmpack, and dcmstsw commands.
The following table shows the parameters that can be specified, and their corresponding command arguments:
Parameter |
Content |
Command argument |
---|---|---|
External program to be started before installation |
/b external-program-to-be-started-before-installation |
|
External program to be started after installation |
/a external-program-to-be-started-after-installation |
|
External program to be started at installation error |
/e external-program-to-be-started-at-installation-error |
|
External program to be started |
/ep external-program-to-be-started |
|
How to report the processing result of external program |
/rbR, /rbM, /raR, /raM, /reR, /reM |
|
Action to take when processing result is error |
/ybC, /ybS, /yaC, /yaS |
|
Monitoring method |
/wbU, /wbT, /wbG, /waU, /waT, /waG, /weU, /weY |
|
|
|
|
Monitoring code |
/wc monitoring-code |
Specify the programs that do not have a GUI as the external programs to be started. Even when a program having a GUI is started, the program will not display any window or dialog box.
Also, do not specify a 16-bit application program as an external program to be started. If an attempt is made to remotely install a package (for which a 16-bit application program is specified as an external program to be started) in background installation mode on a Windows computer, the Windows computer will hang up.
- Organization of this subsection
(1) Format
USER_PROGRAM_INSTALLATION_CONDITIONS{ { external_program_executed_before_installation= external-program-to-be-started-before-installation exit=how-to-report-the-processing-result-of-external-program action=action-to-take-when-processing-result-is-error wait=monitoring-method (U, T, or G) } { external_program_executed_after_installation= external-program-to-be-started-after-installation exit=how-to-report-the-processing-result-of-external-program action=action-to-take-when-processing-result-is-error wait=monitoring-method (U, T, or G) } { external_program_error_handler= external-program-to-be-started-at-installation-error exit=how-to-report-the-processing-result-of-external-program wait=monitoring-method (U or Y) timeout=monitoring-time } { external_program_handler= external-program-to-be-started timeout=maximum-execution-period wait_code=monitoring-code } }
(2) Description
-
external_program_executed_before_installation=external-program-to-be-started-before-installation
Specify the full path name of the external program to be started immediately before package installation (or file collection). When specifying a path name that includes a space, enclose the path name in double quotation marks ("").
The path name of the external program can consist of a maximum of 256 single-byte characters (for package installation) or a maximum of 128 single-byte characters (for file collection). If the path name specified exceeds the maximum number of characters, an error occurs (indicated by the return code 2).
-
external_program_executed_after_installation=external-program-to-be-started-after-installation
Specify the full path name of the external program to be started immediately after package installation (or file collection). When specifying a path name that includes a space, enclose the path name in double quotation marks ("").
The path name of the external program can consist of a maximum of 256 single-byte characters (for package installation) or a maximum of 128 single-byte characters (for file collection). If the path name specified exceeds the maximum number of characters, an error occurs (indicated by the return code 2).
-
external_program_error_handler=external-program-to-be-started-at-installation-error
Specify the full path name of the external program to be started when an error occurs at package installation (or file collection). When specifying a path name that includes a space, enclose the path name in double quotation marks ("").
The path name of the external program can consist of a maximum of 256 single-byte characters (for package installation), or a maximum of 128 single-byte characters (for file collection). If the path name specified exceeds the maximum number of characters, an error occurs (indicated by the return code 2).
-
external_program_handler=external-program-to-be-started
Specify the full path name of the external program to be started when specified execution status occurs. When specifying a path name that includes a space, enclose the path name in double quotation marks ("").
The path name of the external program can consist of a maximum of 256 single-byte characters. If the path name specified exceeds the maximum number of characters, an error occurs (indicated by the return code 4).
-
exit=how-to-report-the-processing-result-of-external-program
Write R (return code) or M (message) to specify the method to report the processing result of the external program. When using command arguments, write R or M immediately after /rb (for the program to be started before installation), /ra (for the program to be started after installation), or /re (for the program to be started at installation error).
The default of this parameter varies depending on the installation mode specified in the installation_mode parameter of the INSTALLATION_METHOD tag (or in the command argument /m). When the installation mode is the GUI installation mode, the default is M. When the installation mode is the background installation mode, the default is R.
-
R
Reports the processing result by the return code output by an external program.
-
M
Reports the processing result by a defined message output by an external program.
-
-
action=action-to-take-when-processing-result-is-error
Write C (continue) or S (stop) to specify whether to continue package installation when the processing result of an external program is an error. When using command arguments for specification, write C or S immediately after /yb (for the program to be started before installation), or /ya (for the program to be started after installation). The default is S.
-
C
Continues package installation while assuming normal status even when an error occurs.
-
S
Stops package installation while assuming an installation error.
-
-
wait=monitoring-method
Write U, T, G, or Y to specify how to handle installation processing until the processing result is reported by an external program. When using command arguments for specification, write U, T, G, or Y immediately after /wb (for the program to be started before installation), /wa (for the program to be started after installation), or /we (for the program to be started at installation error). The default is U.
When you specify T, G, or Y, also specify the maximum time of monitoring the response from the external program in the timeout parameter.
-
U
Suspends installation processing until the processing result is reported.
-
T
Cancels installation processing when suspension has continued over the monitoring time while assuming an installation error.
-
G
Continues installation processing when suspension has continued over the monitoring time while assuming normal status.
-
Y
Continues processing of the program to be started at an installation error when suspension has continued over the monitoring time.
-
-
timeout=monitoring-time (maximum-execution-period for the dcmstsw command)
- For the dcmpack command
-
Specify the maximum time (from 0 to 21,600 (5 hours)) for monitoring the response from an external program. If you do not monitor the response, specify 0. The default is 1.
The specified value of monitoring time applies to all external programs that are started immediately before package installation, immediately after package installation, or when an installation error occurs. Note that specified monitoring time becomes invalid when U is specified for the monitoring method.
- For the dcmstsw command
-
Specify the maximum execution period (from 1 to 10,000,000 seconds) for monitoring job execution status. The default is 86,400 (1 day).
-
wait_code=monitoring-code
Specify the job execution status or maintenance code as a trigger for starting an external program. When specifying multiple statuses or codes, separate them by a comma (,). When multiple statuses or codes are specified, they are connected by logical OR.
- When specifying job execution status:
-
Specify one or more values among those listed below. The default is ERROR.
- NORMAL
The job ended normally.
- TRANS_WAIT
The job is waiting for transmission at the managing server.
- TRANSMITTED
The job is being transmitted to managed computers or being executed.
- REGISTERED
The ID group job is being transmitted to the ID-management relay computer.
- CLT_NOTREADY
Startup of the job failed.
- CLT_SERVICE_OFF#
Startup of the job failed because JP1/IT Desktop Management 2 stopped.
- CLT_POWER_OFF#
Startup of the job failed because the PC power was off.
- CLT_NETWORK_ERR#
Startup of the job failed because of a network error.
- SUSPENDED
A suspension instruction was issued by the relay system.
- INST_WAIT
The job is waiting for installation or collection.
- HOLD_EXEC
The job was held.
- ID_NOPKG
In an ID group job, the package stored at the relay system was deleted.
- CONNECT_ERROR
A communication error occurred.
- ERROR
A job execution error occurred.
- DELETING
The job is being deleted on the relay system, management relay server, or managed computers.
- #
-
You can specify this value if you selected the Break down the reason for a starting failure check box for setup of JP1/IT Desktop Management 2 - Manager. (This checkbox is on the Server Customization panel in the Setup for Distribution by Using Remote Install Manager window.) Note, however, that this value is ignored when it is specified together with CLT_NOTREADY.
If the above check box has been cleared, no external program can be started even when you specify this value.
- When specifying a maintenance code
-
Specify a 12-digit maintenance code. You can use wildcard characters.
(Example)
In the maintenance code, the 9th digit from the left is 8, and the 10th digit is 2: "????????82??"
(3) Notes
-
You can specify one of each of the following: an external program to be started before installation, an external program to be started after installation, an external program to be started at installation error, and an external program to be started.
-
When external programs to be started before and after installation are specified, specifying a system condition (SYSTEM_CONDITIONS) or package condition (SOFTWARE_CONDITIONS) invalidates the values specified in the exit, action, and wait parameters.
-
When this tag is used for the dcmcoll command, the values specified in the external_program_handler, exit, action, wait, and timeout parameters are invalid.
-
When this tag is used for the dcmstsw command, the values specified in parameters other than external_program_handler, timeout, and wait_code are invalid.
(a) Notes on starting external programs on UNIX computers
Note the following when using the dcmpack command to set the startup of external programs for packages to be distributed to UNIX computers:
-
Unlike packages for Windows, you cannot specify the external_program_error_handler, exit, action, or wait parameter.
-
For the external_program_executed_before_installation and external_program_executed_after_installation parameters, the path specification method for external programs differs depending on whether the installation_date_and_time parameter is specified for the SCHEDULE tag.
-
Do not use characters that have special meanings in shell programs, such as <, >, |, &, and $.
The following table describes differences in the path specification method when installation date/time is specified and not specified:
"installation date/time" specification
Path specification method for external programs to be started
external_program_executed_before_installation
external_program_executed_after_installation
Specified
You cannot specify external programs.
-
Specify no more than 40 single-byte characters for a path.
-
You cannot specify a path containing spaces.
-
If the path to the post-processing program contains arguments, enclose the entire part of the path and arguments in double quotation marks (").
-
If the argument contains spaces, enclose the argument including spaces in single quotation marks (').
Not specified
-
If you specify only external_program_executed_before_installation, specify no more than 60 single-byte characters.
-
If you specify only external_program_executed_after_installation, specify no more than 64 single-byte characters.
-
If you specify both external_program_executed_before_installation and external_program_executed_after_installation, specify no more than 60 single-byte characters for the paths to both external programs.
-
You can specify up to 18 strings (arguments).
-
Successive spaces are treated as a single delimiter.
-
Single quotation marks (') are not treated as arguments.
-
Shell variables are invalid because they are treated as strings.
-
Do not specify a process that waits for a response.
-
Note the following when using the dcmcoll command to set the startup of external programs on UNIX computers:
-
Unlike Windows computers, you cannot specify the external_program_error_handler parameter.
-
For the path to the external program to be started, specify no more than 64 single-byte characters. If you specify more than 64 characters, only the first 64 characters are valid.
-
The path to the external program to be started cannot contain spaces.
-
You cannot specify arguments in the external program to be started.
If the path specification method is incorrect, packaging and jobs can be executed, but external programs will not be started on the destination UNIX computers. In this case, note that jobs do not produce an error but terminate normally.