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

3021-3-L75-10(E)

Notices

Relevant program products

For details about the supported operating systems and the service packs or patches that are required by JP1/IT Desktop Management 2, see the Release Notes.

JP1/IT Desktop Management 2 - Manager

P-2A42-78DL JP1/IT Desktop Management 2 - Manager version 13-01

The above product includes the following:

P-CC2A42-7ADL JP1/IT Desktop Management 2 - Manager version 13-01 (for Windows Server 2022, Windows Server 2019, Windows Server 2016)

P-CC2A42-7BDL JP1/IT Desktop Management 2 - Agent version 13-01 (for Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008 R2)

P-CC2A42-7CDL JP1/IT Desktop Management 2 - Network Monitor version 13-00 (for Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1 Enterprise, Windows 8.1 Pro, Windows 8 Enterprise, Windows 8 Pro, Windows Server 2012, Windows 7 Enterprise, Windows 7 Professional, and Windows 7 Ultimate)

P-CC2A42-7DDL JP1/IT Desktop Management 2 - Asset Console version 13-01 (for Windows Server 2022, Windows Server 2019, Windows Server 2016)

P-CC2A42-7PDL JP1/IT Desktop Management 2 - Internet Gateway version 13-00 (for Windows Server 2022, Windows Server 2019, Windows Server 2016)

Trademarks

HITACHI, JP1 are either trademarks or registered trademarks of Hitachi, Ltd. in Japan and other countries.

Acrobat is a registered trademark or a trademark of Adobe Systems Incorporated in the United States and/or other countries.

Acrobat Reader is a registered trademark or a trademark of Adobe Systems Incorporated in the United States and/or other countries.

Adobe is a registered trademark or a trademark of Adobe Systems Incorporated in the United States and/or other countries.

AIX is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.

All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc., in the United States and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

BSAFE is a trademark or registered trademark of Dell Inc. in the United States and other countries.

Citrix(R), the Citrix logo, and other marks appearing herein are trademarks of Citrix Systems, Inc., and/or one or more of its subsidiaries, and may be registered in the United States Patent and Trademark Office and in other countries.

IBM is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.

Intel is a trademark of Intel Corporation or its subsidiaries.

Intel Core is a trademark of Intel Corporation or its subsidiaries.

Microsoft is a trademark of the Microsoft group of companies.

Microsoft, ActiveX are trademarks of the Microsoft group of companies.

Microsoft, Hyper-V are trademarks of the Microsoft group of companies.

Microsoft, Internet Explorer are trademarks of the Microsoft group of companies.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Pentium is a trademark of Intel Corporation or its subsidiaries.

Red Hat is a registered trademark of Red Hat, Inc. in the United States and other countries.

UNIX is a trademark of The Open Group.

Microsoft, Windows are trademarks of the Microsoft group of companies.

Microsoft, Windows Server are trademarks of the Microsoft group of companies.

Microsoft, Windows Vista are trademarks of the Microsoft group of companies.

Other company and product names mentioned in this document may be the trademarks of their respective owners.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

This product includes software developed by Ben Laurie for use in the Apache-SSL HTTP server project.

Portions of this software were developed at the National Center for Supercomputing Applications (NCSA) at the University of Illinois at Urbana-Champaign.

This product includes software developed by the University of California, Berkeley and its contributors.

This software contains code derived from the RSA Data Security Inc. MD5 Message-Digest Algorithm, including various modifications by Spyglass Inc., Carnegie Mellon University, and Bell Communications Research, Inc (Bellcore).

Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyright by the University of Cambridge, England. The original software is available from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/

This product includes software developed by Ralf S. Engelschall <rse@engelschall.com> for use in the mod_ssl project (http://www.modssl.org/).

This product includes software developed by IAIK of Graz University of Technology.

This product includes software developed by Daisuke Okajima and Kohsuke Kawaguchi (http://relaxngcc.sf.net/).

This product includes software developed by the Java Apache Project for use in the Apache JServ servlet engine project (http://java.apache.org/).

This product includes software developed by Andy Clark.

This product bundles Dell BSAFE? software developed by Dell Inc. in the United States.

Java is a registered trademark of Oracle and/or its affiliates.

Java is a registered trademark of Oracle and/or its affiliates.

1. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)

2. This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

3. This product includes software written by Tim Hudson (tjh@cryptsoft.com)

4. This product includes the OpenSSL Toolkit software used under OpenSSL License and Original SSLeay License. OpenSSL License and Original SSLeay License are as follow:

LICENSE ISSUES

==============

The OpenSSL toolkit stays under a dual license, i.e. both the conditions of

the OpenSSL License and the original SSLeay license apply to the toolkit.

See below for the actual license texts. Actually both licenses are BSD-style

Open Source licenses. In case of any license issues related to OpenSSL

please contact openssl-core@openssl.org.

OpenSSL License

---------------

/* ====================================================================

* Copyright (c) 1998-2016 The OpenSSL Project. All rights reserved.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions

* are met:

*

* 1. Redistributions of source code must retain the above copyright

* notice, this list of conditions and the following disclaimer.

*

* 2. Redistributions in binary form must reproduce the above copyright

* notice, this list of conditions and the following disclaimer in

* the documentation and/or other materials provided with the

* distribution.

*

* 3. All advertising materials mentioning features or use of this

* software must display the following acknowledgment:

* "This product includes software developed by the OpenSSL Project

* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

*

* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to

* endorse or promote products derived from this software without

* prior written permission. For written permission, please contact

* openssl-core@openssl.org.

*

* 5. Products derived from this software may not be called "OpenSSL"

* nor may "OpenSSL" appear in their names without prior written

* permission of the OpenSSL Project.

*

* 6. Redistributions of any form whatsoever must retain the following

* acknowledgment:

* "This product includes software developed by the OpenSSL Project

* for use in the OpenSSL Toolkit (http://www.openssl.org/)"

*

* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY

* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR

* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT

* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,

* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED

* OF THE POSSIBILITY OF SUCH DAMAGE.

* ====================================================================

*

* This product includes cryptographic software written by Eric Young

* (eay@cryptsoft.com). This product includes software written by Tim

* Hudson (tjh@cryptsoft.com).

*

*/

Original SSLeay License

-----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)

* All rights reserved.

*

* This package is an SSL implementation written

* by Eric Young (eay@cryptsoft.com).

* The implementation was written so as to conform with Netscapes SSL.

*

* This library is free for commercial and non-commercial use as long as

* the following conditions are aheared to. The following conditions

* apply to all code found in this distribution, be it the RC4, RSA,

* lhash, DES, etc., code; not just the SSL code. The SSL documentation

* included with this distribution is covered by the same copyright terms

* except that the holder is Tim Hudson (tjh@cryptsoft.com).

*

* Copyright remains Eric Young's, and as such any Copyright notices in

* the code are not to be removed.

* If this package is used in a product, Eric Young should be given attribution

* as the author of the parts of the library used.

* This can be in the form of a textual message at program startup or

* in documentation (online or textual) provided with the package.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions

* are met:

* 1. Redistributions of source code must retain the copyright

* notice, this list of conditions and the following disclaimer.

* 2. Redistributions in binary form must reproduce the above copyright

* notice, this list of conditions and the following disclaimer in the

* documentation and/or other materials provided with the distribution.

* 3. All advertising materials mentioning features or use of this software

* must display the following acknowledgement:

* "This product includes cryptographic software written by

* Eric Young (eay@cryptsoft.com)"

* The word 'cryptographic' can be left out if the rouines from the library

* being used are not cryptographic related :-).

* 4. If you include any Windows specific code (or a derivative thereof) from

* the apps directory (application code) you must include an acknowledgement:

* "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"

*

* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND

* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

* SUCH DAMAGE.

*

* The licence and distribution terms for any publically available version or

* derivative of this code cannot be changed. i.e. this code cannot simply be

* copied and put under another distribution licence

* [including the GNU Public Licence.]

*/

Microsoft product screen shots

Microsoft product screen shots reprinted with permission from Microsoft Corporation.

Restrictions

Information in this document is subject to change without notice and does not represent a commitment on the part of Hitachi. The software described in this manual is furnished according to a license agreement with Hitachi. The license agreement contains all of the terms and conditions governing your use of the software and documentation, including all warranty rights, limitations of liability, and disclaimers of warranty.

Material contained in this document may describe Hitachi products not available or features not available in your country.

No part of this material may be reproduced in any form or by any means without permission in writing from the publisher.

Issued

Dec. 2023: 3021-3-L75-10(E)

Copyright

Copyright (C) 2023, Hitachi, Ltd.

Copyright (C) 2023, Hitachi Solutions, Ltd.

Colophon

Publisher

Hitachi, Ltd.

6-6, Marunouchi 1-chome, Chiyoda-ku, Tokyo, 100‒8280 Japan

Summary of amendments

The following table lists changes in this manual (3021-3-L75-10(E)) and product changes related to this manual.

Changes

Location

None.

--

Legend:

--: Not applicable

In addition to the above changes, minor editorial corrections were made.

Preface

This manual provides details about the distribution function that uses Remote Install Manager of JP1/IT Desktop Management 2 - Manager (hereinafter abbreviated to JP1/IT Desktop Management 2) and describes how to use this function.

This manual also provides typical examples of using the distribution function that uses Remote Install Manager and explains the issues you need to consider before using this function.

This manual also provides details about how to use the Automatic Installation Tool (AIT), which is a component of JP1/IT Desktop Management 2. Read this manual when creating AIT files that are to be used to install software automatically.

For details about how to configure a system, see the JP1/IT Desktop Management 2 Configuration Guide.

For details about the latest notes, see the Release Notes.

Intended readers

This manual is intended for the following persons:

Administrators who use JP1/IT Desktop Management 2 to distribute software

System administrators who set up JP1/IT Desktop Management 2

Organization of this manual

This manual consists of the following chapters and appendixes:

1. Overview of the Distribution Function That Uses Remote Install Manager

Chapter 1 describes the distribution function that uses Remote Install Manager.

2. Examples of Typical System Operation

Chapter 2 provides operation examples that relate to package distribution using Remote Install Manager.

3. System Design

Chapter 3 describes the issues you need to consider when designing a system in which Remote Install Manager is used to distribute software.

4. Performing Operations on the Managing Server

Chapter 4 describes the basic operations of the managing server.

5. Creating System Configuration Information and Host Groups

Chapter 5 describes how to create system configuration information, and how to group and manage the hosts to which jobs are distributed.

6. Maintaining System Configuration Information and Host Groups

Chapter 6 describes how to maintain system configuration information and host groups in a system that uses Remote Install Manager to distribute software.

7. Distributing Software

Chapter 7 describes how to distribute (and remotely install) software.

8. Managing Updates

Chapter 8 describes how to package Windows updates for distribution by using the Remote Install Manager.

9. Collecting Files from Managed Computers

Chapter 9 describes how to collect files from managed computers (by using remote collection).

10. Managing Jobs

Chapter 10 describes how to create and manage jobs.

11. Outputting Management Information

Chapter 11 explains how to output (to CSV files) information managed by the managing server, and how to print such information.

12. Performing Operations on the Agent

Chapter 12 describes how to use the functions of the agent.

13. Reporting JP1 Events to JP1/IM

Chapter 13 describes the information (for example, types and attributes of JP1 events) used to check JP1 events sent from JP1/IT Desktop Management 2 to JP1/IM.

14. Commands of the Distribution Function That Uses Remote Install Manager

Chapter 14 describes how to automate job execution and packaging in linkage with JP1/AJS, which is a program associated with JP1/IT Desktop Management 2. This chapter also describes the commands of the distribution function that uses Remote Install Manager.

15. Troubleshooting

Chapter 15 describes how to check information about problems that occur during the use of JP1/IT Desktop Management 2, and how to handle such problems.

16. Remote Installation Using an AIT File

Chapter 16 describes how to perform remote installation by using AIT files, and also provides some cautionary notes on creating and using AIT files.

17. Creating an AIT File

Chapter 17 describes how to create AIT files with the Automatic Installation Tool.

18. AIT Language Reference

Chapter 18 describes the format of AIT files and the syntax of the AIT language.

19. API Function Reference

Chapter 19 describes the APIs that can be used in the AIT language.

20. Troubleshooting the AIT

Chapter 20 describes the messages that are output when problems occur with the Automatic Installation Tool, and explains the actions to be taken.

A. Notes on Using JP1/IT Desktop Management 2 - Agent

Appendix A provides points to be noted when using JP1/IT Desktop Management 2 - Agent in Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, or Windows Server 2008 R2.

B. Outputting Audit Logs Related to Distribution by Using Remote Install Manager

Appendix B describes the information that is output to the audit log.

C. List of Menus

Appendix C lists the menus displayed in each window and icon in JP1/IT Desktop Management 2.

D. List of Icons

Appendix D lists the icons used in the user interface of JP1/IT Desktop Management 2.

E. Launching Tools from Remote Install Manager

Appendix E describes how to register and launch tools in Remote Install Manager, and provides an operation example.

F. Editing a Program Product ID File

Appendix F describes how to edit a program product ID file generated when an AIT file is created.

G. Collecting System and Software Information from Agents for UNIX and Agents for Mac

Appendix G describes how to collect system and software information from agents for UNIX and agents for Mac.

H. Relaying system integration procedure

Appendix H describes the procedure for integrating relay systems.

I. Version Changes

Appendix I describes the changes in each version.

J. Reference Material for This Manual

Appendix J provides reference materials for readers of this manual.

K. Glossary

Appendix K defines terms used in this manual.

1 Overview of the Distribution Function That Uses Remote Install Manager

By using the distribution function that uses Remote Install Manager, you can distribute software and data to managed computers, collect files from managed computer, and store the collected files on the managing server.

This chapter describes the distribution function that uses Remote Install Manager.

1.1 Distributing software (remote installation)

You can use the remote installation function of JP1/IT Desktop Management 2 to distribute Hitachi program products and software by other companies to managed computers.

This function allows you to start the distribution process at a specific date and time, and to distribute software only to computers that match certain conditions. You can also install software on standalone computers on which JP1/IT Desktop Management 2 is installed, and allow users to specify which software they want to install.

The following provides an overview of the remote installation function.

1.1.1 Overview of the remote installation process

The remote installation process consists of two steps: packaging in which the software to be installed is registered, and creating and executing a remote installation job in which the registered package is distributed to a remote computer and installed.

The following figure shows an overview of the remote installation process:

Figure 1‒1: Overview of the remote installation process

(1) Package software for distribution

Before you can remotely install software, you need to package the software on the managing server. This process uses a program called the Packager.

The Packager stores both the software for remote installation and the information necessary for installation in a location (referred to as a cabinet) on the managing server. Software stored in this manner is called a package.

You can view and delete packages stored in a cabinet from the Packager or from the managing server. However, you cannot rename a package or move it to another cabinet. For this reason, carefully consider the cabinet structure on the managing server before packaging the software. You can create cabinets on the managing server in advance, or create them from the Packager during packaging.

Software that has been packaged by the Packager can then be distributed by using Remote Install Manager or by using commands. You cannot use the ITDM-compatible distribution function to distribute these packages. For details about packaging operations, see 7.1 Packaging method.

Packages that were created by using the distribution module in JP1/IT Desktop Management 2 can be distributed by the ITDM-compatible distribution function.

(2) Create and execute remote installation jobs

After packaging the software you want to remotely install, you then create and execute a job on the managing server that initiates the remote installation process. The remote installation process is controlled by Remote Install Manager. For details about remote installation operations, see 7.3 Performing remote installation.

Besides job creation and execution, the remote installation process includes tasks related to the management of cabinets and packages and the deletion of packages from relay systems. For details about how to manage cabinets and packages, see 1.1.7 Managing cabinets and packages. For details about how to delete packages from relay systems, see 1.1.9 Deleting packages from relay systems and management relay servers.

1.1.2 Types of software that can be distributed

In JP1/IT Desktop Management 2, remotely installed software falls into one of the three categories listed below. The category to which a software product belongs is called its package type.

Hitachi program products

Other companies' software

User programs and data

When packaging software, the Packager automatically determines whether the software is in the category Hitachi program products or Other companies' software. If the software does not belong to either of these categories, the Packager handles it as User programs and data.

Some package types require an AIT file (a file created by the Automatic Installation Tool) during remote installation. For details about remote installation using an AIT file, see Chapter 16. Remote Installation Using an AIT File.

(1) Hitachi program products

You can perform remote installation of multi-license products. For other program products, remote installation can only be used to upgrade the program. Remote installation is not available for some program products such as communications software. To determine whether a program product can be installed remotely, check the accompanying documentation or release notes.

Remote installation of JP1/IT Desktop Management 2

JP1/IT Desktop Management 2 - Manager

You cannot install this product remotely.

JP1/IT Desktop Management 2 - Agent (relay system)

You can install this product remotely.

JP1/IT Desktop Management 2 - Agent (agent)

You can install this product remotely.

(2) Other companies' software

The term other companies' software refers to commercially available programs provided by companies other than Hitachi. Most multi-license products from other companies are compatible with remote installation. However, remote installation might not be possible depending on the nature of the software or the licensing agreement. If you cannot determine whether remote installation is possible from the software agreement, it is the user's responsibility to obtain permission from the software provider.

If the software uses an interactive installer, you need to use an AIT file to automate the responses to the installer during remote installation.

(3) User programs and data

You can use remote installation to install some or all of the files in a directory. The data created by applications such as spreadsheet programs is also handled as user data.

1.1.3 Installation conditions that can be set during packaging

To install software remotely, you need to specify all the information required for its installation when you package the software. This might include the date and time of installation, the installation timing, and prerequisite programs. This information is called the installation conditions.

You can set installation conditions in the JP1/ITDM2 Packaging dialog box. You can also change the conditions in the Change Installation Conditions dialog box during remote installation (at the job creation stage).

The following describes the installation conditions you can set on each page of the JP1/ITDM2 Packaging dialog box. For details about these settings, see 7.2 Specifying package details.

(1) System Conditions

On this page, you can specify hardware requirements, such as the minimum hard disk space required for installation and the memory requirements of the software. For example, you might specify the condition that there must be 10 to 20 MB of free space available after installation. By specifying the amount of installed memory as a condition, you can also prevent situations in which the software fails to work after installation due to a lack of memory.

(2) Software Conditions

If the software you are installing requires a specific version of a particular software program to be installed, you can specify version information on this page that allows the system to confirm the presence of the prerequisite program. You can also specify a condition that remote installation is to be executed only if certain other software is not installed on the computer.

(3) Package Conditions

If the package you are installing requires a specific version of a particular package to be installed, you can specify version information on this page that allows the system to confirm the presence of the required package. You can also specify a condition that remote installation is to be executed only if a certain package is not installed on the computer.

(4) File Properties

On this page, you can specify the access permissions and ownership of files after remote installation.

(5) Schedule

You can specify the date and time for installation, and the execution timing of the installation. There are three types of execution timing:

Immediately

The package is installed when the job is executed, or at the specified installation date and time.

When System Starts up

The package is installed the next time the computer starts.

When System Stops

The package is installed when the computer stops. This type is valid only when the destination is an agent for UNIX.

(6) Installation Method

On this page, you can specify an installation mode (the installation method appropriate for the software installer). There are two installation modes:

GUI installation mode

Specify this mode when the software uses a special installer (such as an interactive installer). When the package type is Hitachi program products or Other companies' software, the installation method is always set to GUI installation mode.

Background installation mode

Use this mode when the installation process does not involve a special installer, and can be completed simply by copying files.

(7) Options

On this page, you can specify the following options for remote installation:

Compress package data

Use this option to compress packaged software. A compressed package can be transferred more quickly and occupies less space in the cabinet. However, packaging and remote installation will take longer due to the time required to compress and decompress the package.

Restore old version when upgrade failed

You can use the backup/restore function to protect the previous version of software in case the remote installation process fails. When you use this function, JP1/IT Desktop Management 2 - Agent makes a backup copy of the previous version when it upgrades a program by remote installation. If remote installation fails, the previous version of the program is restored from the backup.

Restart computer after installation

When you select this option, the computer will restart automatically after the package is installed.

Display processing message

Use this option to specify whether to display processing dialog boxes on the target computer while the package is being installed. This applies to dialog boxes indicating that downloading or installation is in progress.

(8) External Program

You can execute an external program on the target computer immediately before or after installation, or in the event of an installation error. This allows you to:

Start an external program before installation that assesses whether the computer meets certain user-specific conditions

Use an external program to start the installed program product

(9) AIT File

By using an AIT file during remote installation, you can set information such as the company name and owner and monitor the responses from the installation process.

(10) Select Components

When packaging JP1/IT Desktop Management 2 - Agent, you can use this page to select whether to package the product for use as an agent or a relay system.

1.1.4 Job types for remote installation

After creating the packages for distribution, you then need to create and execute jobs that tell the managing server how to conduct the remote installation. There are three types of jobs related to remote installation, referred to as job types.

The following describes each type of job related to remote installation.

(1) Install package job

The most basic type of remote installation job. Install package jobs distribute a package from the managing server to managed computers and install the software. Package distribution and installation are initiated by the managing server.

(2) Transfer package to relay computer job

A job that transfers a package from the managing server to a relay system or management relay server.

Packages transferred by a Transfer package to relay computer job are stored on a relay system or management relay server. The managing server will not redistribute the same package until it expires. You can specify the expiration date during the packaging process. If you want to change the expiration date of a package that has been transferred, you need to retransfer the package to the relay system or management relay server after changing the expiration date.

To distribute the package (transferred to the relay system or management relay server) to managed computers, execute an Install package job.

You can combine a Transfer package to relay computer job with an Install package job to perform a remote installation from the managing server in two stages. In this case, the execution date and time of the Transfer package to relay computer job is the date and time when the package is distributed from the managing server to the relay system or management relay server. Likewise, the execution date and time of the Install package job is the date and time when the package is distributed from the relay system or management relay server to the managed computers.

(3) Send package, allow client users to choose job

This job only grants permission for a managed computer to install a package, with the installation itself the responsibility of the user. When you use this type of job, the decision regarding which software to install and when is left to the user of the managed computer.

Although the standard approach to remote installation is appropriate for software that is required on every computer, it can result in the installation of software that is of no use to the user. In this situation, a Send package, allow client users to choose job might be the most appropriate type of job to use.

For details about the process by which users select and install software distributed by this type of job, see 1.1.5 Installation tailored to user circumstances.

1.1.5 Installation tailored to user circumstances

It can be handy for users to have remote installation initiated by the managing server. However, it can also result in unnecessary software being installed on a managed computer, or installation occurring at a time that is inconvenient for the user. You can avoid this by using Send package, allow client users to choose.

When the managing server executes a Send package, allow client users to choose job, this grants the user of the managed computer permission to install the package. The user can use Package Setup Manager to view a list of software he or she has permission to install, and install only the necessary software. On agents for UNIX, however, use the rdsinsset -x command instead of Package Setup Manager to install the package.

This approach is also useful when you want the user to interact with the installer manually throughout the installation process.

The following figure shows the general procedure for installation tailored to user circumstances:

Figure 1‒2: Overview of remote installation tailored to user circumstances

Execute a Send package, allow client users to choose job on the managing server.

The computer specified as the target of the job is granted permission to install the package.

At this point, the package remains on the managing server or the relay system and is not yet distributed to the computer.

The user selects the package in Package Setup Manager and begins the installation process.

The selected software is downloaded to the computer and installation begins.

For details about how to use Package Setup Manager, see 12.4 Operating Package Setup Manager.

1.1.6 Installing software on stand-alone computers

By using storage media such as USB memory, you can install software on a stand-alone computer (offline machine) on which JP1/IT Desktop Management 2 - Agent (agent) is installed, without using a network. This is called offline installation. You can also perform offline installation on a computer where job execution has been suspended by a directive from a higher system.

For details about how to perform offline installation, see 7.3.4 Offline installation.

The following figure shows the general procedure for offline installation:

Figure 1‒3: General procedure for offline installation

Offline installation is useful when:

You want to install a package on a computer that is not connected to a network

Package transfer will take a long time because the network is slow or the package is very large

To achieve offline installation using a managing server and offline computer, the following conditions must be satisfied:

On the managing server:

JP1/IT Desktop Management 2 - Manager is installed.

Remote Install Manager is used on the same computer as JP1/IT Desktop Management 2 - Manager.

On the offline computer:

JP1/IT Desktop Management 2 - Agent is installed.

Packages installed by offline installation do not appear on the Installed Packages page of the System Configuration window or in the Installed Packages window of Package Setup Manager. To check whether the software has been successfully installed, you need to open the installation result file in a text editor.

Note that the following functions are not supported by offline installation:

Installation of JP1/IT Desktop Management 2 - Agent

Specifying an installation schedule

Restarting the computer automatically after installation

Installing software from Package Setup Manager

Split distribution and multicast distribution

1.1.7 Managing cabinets and packages

The management of cabinets and packages is generally the role of the managing server. You can use the Package window of Remote Install Manager to view packages and edit them as needed. It can be useful to create cabinets in advance for different types of software and for different purposes. For example, you might create cabinets for commercial software, for user data, and for anti-virus products.

The following figure shows the Package window:

Figure 1‒4: Package window

Cabinets and packages are represented by the following icons in the left pane of the Package window:

: Cabinet (for Windows)

: Cabinet (for UNIX or Mac)

: Package (successfully packaged)

: Package (error occurred or currently being packaged)

In the Package window, you can perform the following operations on cabinets and packages:

View cabinets and packages

Create cabinets

Rename cabinets

Delete cabinets and packages

For details about how to manage cabinets and packages, see 7.4 Managing cabinets and packages.

1.1.8 Transferring packages to relay systems or management relay servers

On a higher management server, a package that is created can be transferred to a relay system or management relay server.

Transferring packages to a relay system or management relay server enables efficient package distribution to managed computers under the relay system or management relay server while reducing the load on the network.

1.1.9 Deleting packages from relay systems and management relay servers

A relay system or management relay server temporarily stores the package files to be transferred to each managed computer. Because these packages are not deleted until the time specified in Expiration of package storage at the relay computer in the Packager, disk space might come under pressure. If a relay system or management relay server runs out of disk space, relaying of jobs will terminate with an error during job execution. In such a case, use one of the following methods to delete unnecessary packages from the relay system or management relay server:

Execute a Batch delete packages on relay computer job on the managing server.

A Batch delete packages on relay computer job deletes all the packages stored on the destination relay system or management relay server.

From the managing server, select packages on the relay system or management relay server under it and delete them.

You can use Remote Install Manager on the managing server to delete unnecessary packages from the relay system or management relay server under it. For details about how to do so, see 7.4.6 Deleting packages on relay systems and management relay servers.

1.2 Collecting files (by remote collection)

You can use the remote collection function to collect files from managed computers and store them on the managing server. This function can collect user data created by applications such as spreadsheet programs, and the error logs of application programs.

Note that the remote collection function can only collect user programs and data. It cannot collect Hitachi program products or other companies' software.

This section provides an overview of remote collection.

1.2.1 General procedure for remote collection

You can collect files (user programs and data) from managed computers by creating and executing a remote collection job on the managing server.

Files collected by remote collection (called collected files) are stored on the managing server in an archived or compressed format. You need to restore the files to their original form before you can use them on the managing server.

The following figure shows the general procedure for remote collection:

Figure 1‒5: General procedure for remote collection

For details about how to perform remote collection, see 9.1 Remote collection operations.

1.2.2 Types of remote collection jobs

The figure below shows the types of jobs that are involved in the remote collection process. Use the jobs that are appropriate for your network environment and the way you use the system.

Figure 1‒6: Types of remote collection jobs

When you create a Collect files from agent job or a Remote-collect files from agent to relay computer job, you can specify remote collection options for the job. These include the collection time on the managed computer, whether to compress the files, and whether to start an external program.

For details about how to set these options, see 9.1.1 Executing remote collection.

Each type of job is described below.

(1) Collect files from agent job

This job collects files from managed computers via relay systems and management relay servers and places them on the managing server. You can also use this job to collect files from managed computers without using relay systems and management relay servers, from managed computers to relay systems or management relay servers, or from relay systems or management relay servers to managing sever.

(2) Remote-collect files from agent to relay computer job

This job collects files as instructed by the managing server, and stores the collected files on the relay system or management relay server under the managing server where the job was executed. If the relay systems or management relay servers are in a hierarchical structure, collected files will be stored in the relay system or management relay server directly under the managing server where the job was executed.

You can collect files in two stages by using this job together with an Acquire collected files from relay computer job.

(3) Acquire collected files from relay computer job

This job transfers the files collected by a Remote-collect files from agent to relay computer job from the relay system or management relay server to the managing server.

Remote collection imposes a high load on the network between a relay system or management relay server and the managing server. You can make file collection more efficient by using a Remote-collect files from agent to relay computer job first to store collected files temporarily on a relay system or management relay server. Later, such as at night when network traffic is low, you can use an Acquire collected files from relay computer job to transfer those files to the managing server. When relay systems or management relay servers are in a hierarchical structure, you might specify the job destination as a relay system or management relay server not directly under the managing server. In this case, however, files will be collected from the relay system or management relay server directly under the managing server.

(4) Delete collected files from relay computer job

This job deletes files collected onto relay systems or management relay servers by a Remote-collect files from agent to relay computer job. When relay systems or management relay servers are in a hierarchical structure, you might specify the job destination as a relay system or management relay server not directly under the managing server. In this case, however, files will be deleted from the relay system or management relay server directly under the managing server.

1.2.3 Restoring collected files

Because files collected by remote collection are stored on the managing server in an archived or compressed format, they cannot be read from or written to directly. To use these files on the managing server, you need to restore the files to their original form.

To restore files, you use a program called an unarchiver. This program restores files that were archived or compressed during remote collection to their original form.

For details about how to restore collected files, see 9.1.2 Restoring collected files.

1.3 Managing jobs

Many of the features of JP1/IT Desktop Management 2, such as remote installation and file transfer, are implemented by executing jobs on managed computers from the managing server.

This section provides an overview of these jobs, including the general concept of a job, the types of jobs you might use, and the tasks involved in job execution.

1.3.1 About jobs

JP1/IT Desktop Management 2 implements all manner of distribution management tasks, such as remote installation of software and collection of files, by creating and executing instructions called jobs from the managing server.

You can execute jobs on computers for which Managed is specified for Mode in the device information. If you execute a job that targets a computer whose mode is Discovered or Ignored, the job remains in Waiting for transmission status. For details about the mode in the device information, see the description of device discovery in the JP1/IT Desktop Management 2 Administration Guide.

Basic job-related tasks such as creating, saving, and executing jobs are common to many JP1/IT Desktop Management 2 components. To make the most of distribution management in JP1/IT Desktop Management 2, you must have a thorough understanding of jobs.

For details about how to create and execute jobs, see 10.1 Creating and executing a job.

Note:

You cannot execute a job and ITDM-compatible distribution concurrently on an agent. If ITDM-compatible distribution is in progress in an agent, jobs executed on that agent might remain in Waiting for transmission status.

1.3.2 Types of jobs that can be created

The following table lists the types of jobs you can create:

Table 1‒1: Types of jobs that can be created on managing servers

No.

Job type

Description

1

Install package job

Remotely installs a package.

2

Transfer package to relay computer job

Transfers a package to a relay system or management relay server.

3

Batch delete packages on relay computer job

Deletes all packages from a relay system or management relay server.

4

Collect files from agent job

Collects files from managed computers and stores them on the managing server.

5

Remote-collect files from agent to relay computer job

Collects files from managed computers and places them on the relay system or management relay server directly under the managing server.

6

Acquire collected files from relay computer job

Transfers collected files from a relay system or management relay server to the managing server.

7

Delete collected files from relay computer job

Deletes all collected files from a relay system or management relay server.

8

Send package, allow client users to choose job

Grants a user permission to install a software package on his or her computer. Users who have this permission can install the software from Package Setup Manager.

9

Get system information from computer (UNIX) job

Collects system information from a computer running UNIX or Mac.

10

Get software information from computer (UNIX) job

Collects information about software installed on a computer running UNIX or Mac.

11

Get system configuration information job

Collects information about the system configuration under a relay system or management relay server. This job can collect the following information:

Information about relay systems and computers under the management relay server specified as the destination, and about the management relay server directly under the specified management relay server

Information about computers under the relay system specified as the target of the job

12

Hold report job

Instructs a relay system or management relay server to temporarily stop reporting job results.

13

Cancel holding of report job

Instructs a relay system or management relay server to resume reporting job results.

14

Suspend file transfer job

Instructs a relay system or management relay server to suspend file transfer to and from the system directly under it.

15

Resume file transfer job

Instructs a relay system or management relay server to resume file transfer to and from the system directly under it.

The only jobs that can be executed for agents for Mac are the Install package job, the Get system information from computer (UNIX) job and the Get software information from computer (UNIX) job.

The Send package, allow client users to choose job cannot be executed on Citrix XenApp and Microsoft RDS servers.

1.3.3 Detailed job settings

You can create jobs in the Create Job dialog box of Remote Install Manager.

Figure 1‒7: Create Job dialog box

The Create Job dialog box displays the appropriate pages for the specified job type. On these pages, you can specify the job name, destination, execution conditions, and other detailed settings. For details about the pages displayed in the Create Job dialog box, see 10.2.2 Pages displayed in the Create Job dialog box.

The following table lists the pages displayed in the Create Job dialog box, and describes the information you can set on each page.

Table 1‒2: Pages displayed in Create Job dialog box

Page

Information that can be set

Job page

The name of the job.

Destination page

The hosts that are targeted by the job.

Package page

The attributes of packages to be installed remotely, the installation environment, and other options.

Job Distribution Attributes page

Information required for multicast distribution or split distribution of a package. These options are useful when distributing large packages. Note that you can only specify multicast distribution for Install package jobs.

Acquisition Target page

The items to be collected when a Get system information from computer (UNIX) job is executed.

Search Target page

The software for which information is to be collected when a Get software information from computer (UNIX) job is executed. If you use a software search list, you can specify the software search list to be used. You can also specify whether to include network file systems in the search targets.

Collect File page

Files to be collected remotely.

Schedule page

The registration date and time, execution date and time, and execution time limit of the job.

Client Control page

If the destination computer of a job is turned off, an option on this page allow you to turn on the computer remotely when the job is executed. You can also configure the computer to shut down after the job has been executed. Note that agents for UNIX and agents for Mac cannot be shut down automatically after the job has been executed.

1.3.4 Executing and saving jobs

You can execute a job immediately after creating it in the Create Job dialog box, or you can save the job first in the Job Definition window. By saving a job, you can use it as a template that allows you to execute the same kind of job over and over with minimum effort.

To save a job, you first need to create a folder in which to manage the job. You can create a folder in the Job Definition window.

For details about how to edit saved jobs and create folders, see 10.3.2 Managing saved jobs and folders.

1.3.5 Executing jobs on grouped hosts

In large-scale systems, it is more efficient to specify groups of systems as job execution targets, rather than individual systems. You can use host groups or ID groups to group hosts.

Host group

A host group is a hierarchical group of distribution destinations based on arbitrary conditions, such as a department or project. The managing server manages not only the creation of the groups but also which computers belong to each group. This type of grouping provides a logical hierarchical structure for job destinations, making them easier to manage in the user interface. We recommend that you create host groups for this reason.

If you specify a host group as the destination of a job, the job will be executed on every computer that belongs to that host group.

You can group computers by department as well as by project. This lets you assign groups by department or by project when a project crosses departmental lines, as shown in the figure below.

The following figure illustrates the concept of a host group:

Figure 1‒8: Concept of host groups

ID group

When you use ID groups, not only can system administrators register computers in ID groups, but users can do so themselves by selecting the ID groups to which they want to belong. A job executed with an ID group as the destination is automatically executed each time a new computer is registered in the corresponding ID group. This means that the managing server does not need to redistribute the software to every new computer that joins the group. If ID groups are based on information that is subject to change, such as the operating system or the purpose for which the computer is used, only users affected by such a change need to alter their ID group memberships. This reduces the burden on the system administrator.

The following figure illustrates the concept of an ID group:

Figure 1‒9: Concept of ID groups

1.3.6 Flow of job execution

This section describes the flow of job execution.

You can specify Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently and Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently during JP1/IT Desktop Management 2 - Manager setup and in the agent configurations.

The job is executed from Remote Install Manager.

The managing server sends execution requests to the destinations specified during job execution. This notifies the lower systems that a job has been executed.

The lower systems receive the execution requests, and request the job from the higher system.

The job is downloaded to the lower systems that requested it.

The lower systems report the execution results to the managing server.

The following figure shows the flow of job execution:

Figure 1‒10: Flow of job execution

The managing server monitors jobs at one-minute intervals. If there are lower systems that require a connection, the managing server sends an execution request to those lower systems. The maximum number of lower systems to which the managing server can send an execution request at one time is the value of Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently. If the number of connected lower systems is less than the value specified for this parameter, the managing server sends only as many execution requests as there are lower systems that can establish new connections.

Note that the number of lower systems corresponding to the destinations specified in a job refers to only the number of lower systems directly connected to the managing server that executed the job. Therefore, if the distribution route contains relay systems and management relay servers, the number of lower systems includes only the number of relay systems and management relay servers that are directly connected to the managing server. It does not include lower systems connected to these relay systems and management relay servers.

(1) Example of job execution

An example of job execution is described below.

Conditions

Number of destination specified for job: 60

Value of Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently: 20

Value of Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently: 50

Job download time: 200 seconds

The following figure shows the flow of job execution with these conditions:

Figure 1‒11: Example of job execution flow

Execution requests are sent to 20 destinations, the number specified for Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently.

Number of connected subsystems (20) < Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently (50)

Execution requests are sent to another 20 destinations, the number specified for Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently.

Number of connected subsystems (40) < Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently (50)

Execution requests are sent to the remaining 10 destinations permitted by the number specified for Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently.

Number of connected subsystems (50) = Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently (50)

No further execution requests are sent because the number of connected subsystems is equivalent to the value of Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently.

The subsystems that were connected in step 1 report their execution results to the managing server.

Number of connected subsystems (30) < Number of JP1/IT Desktop Management 2 - Agent instances that can connect to the management server concurrently (50)

Of the 60 destinations specified in the job, the execution request is sent to the remaining 10 subsystems.

1.3.7 Job execution sequence

When multiple jobs are executed on a managed computer at the same time, the rules below govern the sequence in which they are executed. Here, jobs for which an execution time (installation date and time) is specified are referred to as scheduled jobs, and other jobs are referred to as real-time jobs.

Scheduled jobs are executed in order of their scheduled times.

Real-time jobs are executed in the order in which they were executed in Remote Install Manager.

When the system contains real-time jobs and scheduled jobs, if Remote Install Manager executes a real-time job before a scheduled job, the real-time job is executed before the scheduled job on the managed computer.

(1) Executing multiple packages according to a schedule

In some circumstances, you might need packages to be installed in a certain order. To achieve this, keep the above rules in mind and follow the conventions below when you execute each job:

Use the same route (via relay systems and management relay servers) to execute each job.

Specify the same installation mode (GUI or background) for each package.

If you specify When System Starts up as the execution timing of the package, the package is not installed until the managed computer is restarted. Therefore, if you want to install packages with When System Starts up specified and those with Immediately specified in a specific order in relation to each other, be careful about the timing with which the managed computer restarts.

If multiple packages in the same job have the same execution timing and installation mode, the packages are installed on the computer in the sequence described below.

Basic rules for package installation sequence:

Packages are installed in ascending order of a character string generated from information specified in the Create Job dialog box of Remote Install Manager. This character string consists of the cabinet ID (two digits), package ID (44 digits), version (6 digits), and generation number (4 digits). When distributing several packages at once, set the cabinet IDs, package IDs, and other information in a way that results in the desired installation sequence. For example, suppose that packages called Package A and Package B are registered with the following attributes:

ID

Package A value

Package B value

Cabinet ID

'DD'

'AA'

Package ID

'AAA'

'CCCCC'

Version

'0100 '

'0100/A'

Generation number

'0000'

'0001'

String generated from these values

'DDAAA0100 0000'

'AACCCCC0100/A0001'

Because the packages are installed in ascending order of the generated string, Package B is installed before Package A.

The Package page of the Create Job dialog box lists packages in ascending order of these generated strings. This means that you can use this page to identify the sequence in which packages will be installed.

For user programs and data and other companies' software:

For packages to be installed, assign package IDs in ascending order of alphanumeric characters in the ASCII encoding.

For Hitachi program products:

Hitachi program products have fixed package IDs. However, you can control the installation sequence by changing the cabinet ID when you package the product. For software products to be installed, assign cabinet IDs in ascending order of alphanumeric characters in the ASCII encoding. Note that when you package products, you must keep the installation order in mind when selecting the cabinet in which each package is stored.

Also note the following points:

If you specify an installation date and time as a package attribute or specify an execution date and time when creating jobs, packages will not be installed in the order in which Remote Install Manager executes the jobs. If you want to control the package installation order, do not specify an installation date and time or job execution date and time.

Packages in background installation mode are installed before packages in GUI installation mode. If there are packages with different installation modes, use different jobs to execute them. When executing these jobs, execute one job first, and then execute the other job after the previous job has finished.

If you execute a job for which split distribution is specified, and another job is then started by Remote Install Manager, the latter job might be executed on the managed computer before the split-distribution job.

A job with Distribute specified will be executed before a job that has been suspended.

1.3.8 Checking job execution statuses

You can check job execution statuses in the Job Status window of Remote Install Manager. This window displays the status of executed jobs by folder or by job, in a hierarchical structure. The left pane displays the hierarchy of folders and jobs, and the right pane displays information about an item selected in the left pane.

Figure 1‒12: Job Status window

The color of a job in the Job Status window indicates the most serious status of the hosts targeted by that job. For example, if a job is displayed in red (indicating that an error has occurred), you can identify the host where the error occurred by navigating down through the hierarchy one level at a time.

For details about how to check job execution statuses, see 10.4 Checking the job status.

1.3.9 Action to take after checking execution results

After checking job execution results, delete the jobs that terminated normally from the Job Status window. If you leave these completed jobs in the system, jobs that are still executing might take longer to process or Remote Install Manager might become less responsive. If there are jobs that are waiting for transmission or have resulted in a recoverable error, you can select and re-execute those jobs. For details about these and other actions you can take after checking execution results, see 10.5 Actions after checking the job results.

For details about how to display jobs that require action to be taken, see 10.4.6 Displaying the jobs with a specific execution status.

1.4 Managing system configuration information

To use JP1/IT Desktop Management 2, you must not only install the programs, but also manage the configuration and addresses (host names or IP addresses) of the relay systems, management relay servers, and managed computers on the managing server. This information is called system configuration information. A computer that is registered in the system configuration information can be specified as a target of an executed job.

This section provides an overview of managing system configuration information.

1.4.1 Viewing system configuration information

You can view and create system configuration information in the System Configuration window of Remote Install Manager. The network hierarchy in this window defines the actual routes used for job execution. The following figure shows the System Configuration window:

Figure 1‒13: System Configuration window

The left pane of the System Configuration window displays the system hierarchy. The icon representing the managing server () appears at the top of the hierarchy. When you double-click the icon for a relay system (), the icons for the lower systems and managed computers under the relay system () appear. When managing servers are displayed in a hierarchical structure, the icons for management relay servers () appear under the managing server.

The host name or IP address of each management relay server, relay system, or managed computer appears beside the corresponding icon.

If you select a resource other than a managed computer in the left pane, the right pane shows the hierarchy under the selected resource.

For details about how to create system configuration information, see 5. Creating System Configuration Information and Host Groups.

1.4.2 Grouping managed computers

When executing a job such as remote installation from the managing server, you specify the hosts (destinations) that are the targets of the executed job. Although you can specify the destinations individually using the system configuration information, this method is inefficient when the job targets a large number of computers. JP1/IT Desktop Management 2 lets you organize computers into a number of groups according to their purpose without being tied to the physical network configuration. You can then execute jobs that target these individual groups.

(1) Types of groups

You can create two types of groups: host groups and ID groups. Both types of group can be created based on any criteria, such as for a specific department or project. You can also register the same host in multiple host groups or ID groups. This allows a particular computer to belong to a department group and a project group, for example. These groups allow you to manage destination hosts in an efficient way.

(a) Host groups

Host groups are a way of grouping hosts on the managing server. Because host groups are not tied to the system configuration, you can group hosts hierarchically based on any criteria, such as for a specific department or project. You can also give a host group any name you wish. By grouping hosts by department or project and assigning descriptive names to the groups, you can make the process of job execution more intuitive.

When you specify a host group as the destination of a job, the job is executed on every computer that belongs to that group.

(b) ID groups

ID groups are a way of grouping hosts in which the managing server only assigns a name to the group and specifies a relay system or management relay server that manages the ID group (called the ID-management relay computer). The user determines the ID groups to which the managed computer belongs. A managed computer can belong to multiple ID groups.

You can also use a file on the managing server to register multiple computers in an ID group. Note that ID groups cannot be managed hierarchically.

When a job that specifies an ID group as the destination (ID group job) is transferred to an ID-management relay computer, the ID-management relay computer executes the job on the computers that belong to the ID group.

Users place their own managed computers into the appropriate ID groups. This means that the administrator does not have to keep track of the individual computers that are the destination for ID group jobs. When a new computer is added, provided that the user registers the computer in the appropriate group, the jobs meant for that group will be executed automatically on the new computer. This allows the system to dynamically handle changes to the system configuration.

You can set passwords that the user must specify to register a computer in an ID group. This prevents a computer from being registered in the wrong ID group.

(2) Grouping destinations

You can set host groups and ID groups in the Destination window of Remote Install Manager.

Figure 1‒14: Destination window

For details about how to create host groups, see 5.2 Creating host groups.

For details about how to create ID groups, 5.3 Creating ID groups.

The left pane of the Destination window displays the hierarchical structure of the groups. Double-clicking on an item in the left pane displays the hierarchy below. The right pane displays information about the host selected in the left pane.

The destination window uses the following icons to represent groups:

: Host group

: ID group

In most circumstances, you use the Destination window to specify a computer as a target of a job. Although you can also use the System Configuration window, it is harder to identify hosts in this window because hosts are displayed by their IP address or host name. In the Destination window, you can use groups to specify the hosts that are targets of executed jobs.

In broad terms, system configuration information is used to manage the network configuration of individual managed computers, while host groups and ID groups are used to manage computers in groups. Consider the grouping criteria so that jobs will be executed in the most efficient way possible.

1.4.3 Maintenance of system configuration information

Regular maintenance of system configuration information is required to keep the system running smoothly. This subsection describes how to search for newly added hosts and register them in host groups, and how to automatically assign new hosts added to the system configuration to the appropriate host groups and ID groups, based on preset conditions.

Note that if duplicate devices and idle devices that were detected as devices suggested for deletion during device maintenance are deleted automatically or manually, the system configuration information for those devices is also deleted automatically. The devices are also deleted automatically from the host group and ID group to which they belong. For details about device maintenance, see the description of automatic maintenance of devices in the JP1/IT Desktop Management 2 Overview and System Design Guide.

(1) Searching for system configuration information

From the System Configuration window or Destination window, you can search for destinations that match certain conditions. There are two types of searches:

Search using a destination name, host group name, or ID group name as the key

Search using the host registration date as the key

You can use these search functions to maintain the system configuration information, by such means as copying the hosts from the search results to the Destination window or deleting them from the system configuration information.

For details about how to manually maintain the system configuration information using the search functions, see 6.1 Maintenance of system configuration information.

(2) Automatic maintenance of destination group

Approaches to host group maintenance include editing them in the Destination window or importing data from a file. However, in a large-scale system with thousands of hosts, it is an undue burden on the system administrator to add and delete host groups as regularly as would be needed.

JP1/IT Desktop Management 2 can automatically detect new and moved hosts by monitoring the system configuration information, and assign them to the appropriate host groups based on predefined grouping conditions (called a policy). This is called Automatic maintenance of destination group, and takes place when device information is notified from a managed computer.

The following figure shows an overview of automatic maintenance of destination group:

Figure 1‒15: Overview of automatic maintenance of destination group

Maintenance of host groups can be performed at any time, not just when the managing server receives device information from managed computers. This means that at any time you can assign batches of hosts registered in the system configuration information to host groups based on the policies you have created (apply policies to all hosts).

For details about how to apply policies to host groups, see 6.2.2 Applying policies to all host groups.

You can also create policies from a file. By importing or exporting policy files, you can back up existing policies or swap one policy for another. For details about creating a policy from a file, see 6.4 Creating a policy from a file.

(3) Automatic ID group maintenance

As a rule, the user determines which ID groups a managed computer joins. If you prefer an approach in which computers are assigned to groups on the managing server, you can configure the system to automatically register computers based on whether they satisfy specific conditions. This is a more reliable and efficient way of registering computers in ID groups than by using the Destination window or importing files.

The process of setting conditions (policies) for ID groups and automatically registering computers based on these conditions is called Automatic ID group maintenance.

There are three types of policy available for automatic ID group maintenance:

ID group registration associated with creation of new hosts

This policy allows JP1/IT Desktop Management 2 to automatically detect new computers and register them in ID groups.

ID group registration based on asset management items

This policy allows you to set asset management items (such as the department, installation location, or additional management items of hardware asset information) as conditions, and automatically register computers in ID groups based on those conditions.

ID group registration based on device information

This policy allows you to set conditions for the system information items, installed software programs, and asset management items of devices, and automatically register computers in ID groups based on those conditions.

The following figure shows an overview of automatic ID group maintenance:

Figure 1‒16: Overview of automatic ID group maintenance

For details about how to use automatic ID group maintenance, see 6.3 Automatic ID group maintenance.

As with automatic maintenance of destination group, you can create a policy from a file. For details, see 6.4 Creating a policy from a file.

Before you can conduct automatic maintenance of an ID group, you must have already executed a job on that ID group.

For example, suppose there is a job that you want to execute every time a new computer is deployed. By executing the job in advance with an ID group as the destination, and creating a policy that adds new computers to that ID group, you can automatically execute the job on all new computers.

The following figure shows the flow of the job when using automatic ID maintenance:

Figure 1‒17: Job flow using automatic ID group maintenance

1.4.4 Managing the deletion history of system configuration information

JP1/IT Desktop Management 2 - Manager allows you to manage deletion histories in order to keep track of when and why managed computers, relay systems, and management relay servers were removed from the system configuration information. Because this deletion history contains the system configuration information for deleted hosts, you can use it to restore those hosts to the system configuration information.

To manage the deletion history of system configuration information, you need to enable the Save deletion history option when setting up JP1/IT Desktop Management 2 - Manager.

The host groups, ID groups, and device information of deleted hosts is not stored as historical data. Deletion history is also not saved for hosts that are deleted as a batch when creating system configuration information from a system configuration information file.

For details about how to manage the deletion history of system configuration information, see 6.5 Managing the deletion history of system configuration information.

1.5 Managing system and software information of agents for UNIX and agents for Mac

You can use the managing server to execute jobs to acquire system and software information from computers whose OS is UNIX or Mac and use that information to manage agents for UNIX and agents for Mac.

For details about how to acquire system and software information from agents for UNIX and agents for Mac, see Appendix G. Collecting System and Software Information from Agents for UNIX and Agents for Mac.

1.5.1 Managing system information of agents for UNIX and agents for Mac

You can acquire system information that can be used to manage the system usage statuses of agents for UNIX and agents for Mac.

1.5.2 Managing software information of agents for UNIX and agents for Mac

You can check the types, versions, and other information about software programs installed on agents for UNIX and agents for Mac.

JP1/IT Desktop Management 2 enables you to collect information about remotely installed software or about software in the search list that exists on agents. Unless information notification is disabled on the agent for UNIX, you can also collect information about OS patches applied to the computer and manage it in the same way as software information.

To acquire software information from agents for UNIX and agents for Mac and manage it in the JP1/IT Desktop Management 2 windows, you must edit the configuration file (jdn_manager_config.conf). For details about how to edit the configuration file, see the section that describes the procedure for modifying the software information management settings of agents for UNIX and agents for Mac in the JP1/IT Desktop Management 2 Configuration Guide.

1.6 Outputting managed information

You can output the device information, host attributes, package attributes, job statuses, and other information managed by the managing server to a CSV file or a printer.

This section provides an overview of how to output information managed by the managing server.

1.6.1 Outputting information to a CSV file

You can output the information managed by the managing server (managed information) to a file in CSV format. You can then use the information in the CSV file by importing it into tools such as spreadsheet software.

To output managed information to a CSV file, you use the CSV File Output function. You can set the output items and the output destination of the file in the CSV File Output dialog box.

For details about how to output managed information to a CSV file using the CSV File Output, see 11.1.1 Items that can be output to CSV files.

1.6.2 Printing information

You can print information managed by the managing server. In the Print Setup dialog box, select the print items that you want to print and then enter the necessary print information.

For details about how to print managed information, see 11.2 Printing management information.

1.7 Configuring managed computers

The concept of managed computers includes not only computers positioned at the bottom of the system configuration hierarchy, but also the management relay servers and relay systems that receive and send jobs.

The following table lists the systems that can be managed computers:

Table 1‒3: Systems that can be managed computers

System

Program

Management relay server

JP1/IT Desktop Management 2 - Manager

Relay system

JP1/IT Desktop Management 2 - Agent

Agent

The following describes how to install distributed software.

1.7.1 Installing distributed software

When you execute an Install package job on the managing server, the managed computer automatically downloads and installs the indicated software. Because the software is downloaded and installed automatically, the user does not need to be aware of what software is being installed and when.

However, if an entirely automated process is not appropriate for a user, he or she can use the approach described in (1) below. Users can also choose to select and install software manually as described in (2).

(1) Controlling job execution timing

In most circumstances, the timing of jobs that download and install packages is determined by the higher server (the managing server) in a way that is transparent to the user. The user simply waits for packages to be transferred from the managing server and installed automatically.

With this mode of operation, however, installation might start suddenly while the user is busy with other tasks, causing difficulty for the user. To avoid scenarios like this, users are able to prevent jobs from being executed unilaterally, and tailor the timing of job execution to suit their circumstances.

To control job execution timing on the user side, a user can use the job hold facility.

(a) Using the job hold facility

One way users can prevent higher servers from executing jobs unilaterally is by using the job hold facility. With this facility enabled, the JP1/IT Desktop Management 2 Job Suspended dialog box appears when a job is transferred from a higher server, allowing the user to select whether to execute the job. If the user does not wish to execute the job immediately, he or she can temporary hold it for later execution.

You can enable the job hold facility during the agent setup process. To enable the facility, select the Permit users to hold jobs check box in the Settings to permit job holds area of the Job settings page.

Only Install package jobs running in GUI installation mode can be held. However, jobs for which an execution date and time (a package installation date or job execution date) is specified cannot be held.

For details about how to hold jobs, see 12.3.1 How to hold a job.

(2) Selecting which software to install

When software is distributed from the managing server by a Send package, allow client users to choose job, the software is not installed automatically. Instead, the user is granted permission to install the software if they wish. This allows the user to select and install only the software that is required for their circumstances. Users use a tool called Package Setup Manager to view a list of software that can be installed, and to select and install the required software.

Note that a single instance of Package Setup Manager cannot be shared among multiple non-Administrator users.

For details about how to use Package Setup Manager, see 12.4 Operating Package Setup Manager.

1.7.2 Notes on installing software manually

This section provides cautionary notes that apply when installing software manually.

If the managed computer is running Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, or Windows Vista, see also Appendix A. Notes on Using JP1/IT Desktop Management 2 - Agent.

Notes on installing other companies' software

When remotely installing other companies' software, do not perform operations in the user interface of the installer while the software is installing. Doing so might cause the installer to stop responding.

Notes on password-protected computers

If a managed computer is password-protected (it displays a dialog box asking the operator to press Ctrl + Alt + Delete), software that requires user intervention in GUI installation mode cannot be installed remotely. This is because the password protection prevents the required responses from being provided. This issue does not affect Hitachi program products that are compatible with remote installation, because such programs do not require user intervention during remote installation.

What to do if the installation process stops responding

If a user program that was started during remote installation stops responding, or the user program termination code notification interface is configured incorrectly in GUI installation mode, the remote installation process also stops responding. If this happens, restart the managed computer.

Notes on split distribution

Split distribution in environments where the managed computer does not conduct polling:

If the managed computer does not conduct polling, split distribution can be initiated by an instruction from the server. We recommend that you avoid using split distribution in environments where the server might fail to start the split distribution process.

Held jobs and split distribution:

When using split distribution, when all split packages have been transferred, the JP1/IT Desktop Management 2 Job Suspended dialog box appears asking the user whether to install the packages. If the user chooses to install the packages, the installation process begins. If the user chooses to hold the packages, installation is put on hold and the packages are not installed until requested by the user.

Split distribution with an installation date and time specified:

When using split distribution with an installation date and time specified, the installation date and time might elapse while split distribution is still in progress. In this case, installation begins as soon as all the split packages for the split distribution process have been transferred.

Installation of split packages at startup

If you perform split distribution with installation at system startup, installation will begin when the system next starts after all the split packages have been transferred.

Limitations when using JP1/IT Desktop Management 2 - Agent in virtual environments

Certain limitations apply when using JP1/IT Desktop Management 2 - Agent (agent) in a virtual environment. JP1/IT Desktop Management 2 - Agent (agent) does not support some operating systems in virtual environments.

Limitations related to Remote Desktop

You cannot use offline installation when you use Remote Desktop to install a package.

If the OS is Windows Server 2003, when using Remote Desktop to install or operate JP1/IT Desktop Management 2 - Agent (agent), connect to a console session.

If the OS is Windows Server 2019, Windows Server 2016, Windows Server 2012 or Windows Server 2008, when using Remote Desktop to operate JP1/IT Desktop Management 2 - Agent (agent), multiple users cannot concurrently run the JP1/IT Desktop Management 2 application.

Limitations related to Fast User Switching

If the OS is Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008, or Windows Vista, when using Fast User Switching to operate JP1/IT Desktop Management 2 - Agent (agent), multiple users cannot concurrently run the JP1/IT Desktop Management 2 application.

1.8 Executing jobs automatically by linking with JP1/AJS

JP1/AJS is a program for running jobs automatically. Using JP1/AJS, you can execute a sequence of processes according to a predefined schedule, or initiate processing when a specific event occurs.

By using the command interface provided by JP1/IT Desktop Management 2 for operations such as creating or executing jobs, you can register a command execution sequence that JP1/AJS executes automatically. You can also have JP1/AJS execute JP1/IT Desktop Management 2 commands when a specific event such as a file update occurs.

The following figure provides an overview of automatic job execution by linking with JP1/AJS:

Figure 1‒18: Overview of automatic job execution by linking with JP1/AJS

For details about JP1/AJS functions and how to use them, see the documentation for JP1/AJS. For details about the commands provided with JP1/IT Desktop Management 2, see Chapter 14. Commands of the Distribution Function That Uses Remote Install Manager.

2 Examples of Typical System Operation

This chapter introduces key concepts regarding the operation of a JP1/IT Desktop Management 2 system, using operation examples that relate to package distribution using Remote Install Manager.

2.1 Operating a remote JP1/IT Desktop Management 2 system

You can build a system that lets you operate JP1/IT Desktop Management 2 remotely.

For example, you can install JP1/IT Desktop Management 2 on a server in an office, and have the administrator operate it from his or her own computer.

There are two ways to remotely operate a JP1/IT Desktop Management 2 system:

Install Remote Install Manager on a different computer from the managing server of JP1/IT Desktop Management 2

For details about how to install Remote Install Manager separately, see the JP1/IT Desktop Management 2 Configuration Guide.

Remotely control a computer configured as the managing server

For details about the remote control function, see the description of the flow of operating remote servers in the JP1/IT Desktop Management 2 Administration Guide.

2.2 Distributing JP1/IT Desktop Management 2 - Agent using the remote installation function

When you need to upgrade the software on a relay system or the agent, you can use JP1/IT Desktop Management 2 to remotely install the latest version of the software. The procedure is the same as for other Hitachi program products.

When JP1/IT Desktop Management 2 - Agent is installed remotely, it inherits the configuration of the previous version.

The following cautionary notes apply when using the remote installation function to distribute JP1/IT Desktop Management 2 - Agent:

Notes on programs and components

You can remotely install the components listed below. When you install JP1/IT Desktop Management 2 - Agent, you can select which components you want to install.

When installing JP1/IT Desktop Management 2 - Agent (agent)

Agent

Remote control agent

Packager

Automatic Installation Tool

When installing JP1/IT Desktop Management 2 - Agent (relay system)

Relay system

Remote control agent

Packager

Automatic Installation Tool

Notes on remote installation

Close any JP1/IT Desktop Management 2 - Agent dialog boxes before starting the remote installation process.

Note that the following dialog boxes are sometimes displayed automatically:

Dialog boxes reporting job errors

Dialog boxes confirming deletion of shortcuts in the ITDM2_Startup folder that failed to start

Update User Information dialog boxes displayed at startup

JP1/IT Desktop Management 2 Job Suspended dialog box

Dialog boxes confirming shutdown or restart

The disk on which the agent software is being remotely installed must have three times as much free space available as the size of the JP1/IT Desktop Management 2 - Agent software.

Do not install JP1/IT Desktop Management 2 - Agent together with other packages.

To distribute JP1/IT Desktop Management 2 - Agent by remote installation, you must use the Packager whose version matches the version of JP1/IT Desktop Management 2 - Agent.

When packaging the software or creating a remote installation job, in the Start external program area of the External Program page, do not specify an external program that starts immediately after installation or when an installation error occurs.

Installation might fail if you restart the computer or operate the JP1/IT Desktop Management 2 - Agent menus during the installation process. Clicking the Cancel button in the progress dialog box during installation will also stop the installation process.

If you have configured the system to not display dialog boxes during installation, the message telling the user that the computer needs to be restarted does not appear after JP1/IT Desktop Management 2 - Agent installation.

Refrain from executing the following jobs:

Distributing multiple packages with JP1/IT Desktop Management 2 - Agent included in one remote installation job.

Executing multiple remote installation jobs at the same time with the JP1/IT Desktop Management 2 - Agent remote installation job included.

When distributing packages other than JP1/IT Desktop Management 2 - Agent, make sure that the distribution of JP1/IT Desktop Management 2 - Agent has been completed before executing.

To complete the remote installation of JP1/IT Desktop Management 2 - Agent, perform any of the following method to restart the computer after installation has finished and before installing any other products.

Manually restart the computer.

Enabling Restart computer after installation setting when executing remote installation job of other packages.

You can check the execution results of remote installation in the Job Status window on the managing server.

The return code is the value of Maintenance code in the Detailed Information dialog box displayed from the Job Status window.

You cannot install JP1/IT Desktop Management 2 - Agent on a relay system or agent using Package Setup Manager on a managed computer by executing a Send package, allow client users to choose job.

2.3 Distributing software with a distribution or installation date and time specified

2.3.1 Overview

You can distribute software according to a set schedule. You can also specify the date and time when software is to be installed at the destination, and control the installation timing so that the software is installed when the system starts or shuts down.

For example, by distributing a package with the same installation date and time specified to multiple computers in advance, you can install software on all those computers at the same time.

When you package software, you can specify the date and time when the software is to be installed on the destination, and the timing of its installation. You can specify the execution date and time of a job when you create the job.

For an example of executing a job at a specific time, see 7.6.5 Installing software at a specified time.

The following figure shows the general procedure for distributing software with dates and times specified for distribution and installation:

Figure 2‒1: General procedure for distributing software with dates and times specified for distribution and installation

2.3.2 Procedure

Package the software to be distributed, specifying an installation date and time, and job execution timing.

For details about how to package software, see 7.1 Packaging method.

For details about how to specify an installation date and time for a package, see 7.2.7 Schedule page.

Create a remote installation job, specifying an execution date and time.

For details about how to create a job, see 7.3.1 Remote installation procedure.

For details about how to specify an execution date and time for a job, see 10.2.5 Setting up the Schedule page.

Execute the job.

For details about how to execute a job, see 10.3 Executing and saving a job.

For details about the sequence in which jobs are executed, see 1.3.7 Job execution sequence.

The job is executed according to the schedule you specify when creating the job. The packages distributed to the computer are installed according to the schedule you specify during packaging.

Checking the job execution status:

For details about how to check the execution status, see 10.4.3 Items displayed in the Job Status window.

Re-executing failed jobs:

For details about how to re-execute jobs, see 10.5.2 Re-executing a job with an error.

2.3.3 Cautionary notes

For notes on packaging, see 7.1.4 Notes on packaging.

For notes on checking job execution statuses, see 10.4.2 Important notes on checking a job status.

2.4 Automatically distributing software to new managed computers

2.4.1 Overview

By setting conditions for ID groups (called a policy), you can automatically register new managed computers in the appropriate ID groups as soon as they are added to a system managed by JP1/IT Desktop Management 2.

By executing a software distribution job for an ID group in advance, you can distribute software automatically to new managed computers whenever they are added to that ID group. This is useful from a security perspective because it allows you to distribute software that is essential at deployment, such as antivirus software.

The following figure shows the general procedure for creating the ID group ID_NEWCLT, and automatically distributing software to computers added to that ID group.

Figure 2‒2: General procedure for automatically distributing software to newly added computers

2.4.2 Procedure

Create an ID group.

For details about how to create an ID group, see 5.3.2 Creating ID groups.

Package the software to be distributed.

For details about how to package software, see 7.1 Packaging method.

Create a remote installation job (ID group job) with the ID group you created as the destination.

For details about how to create a job, see 7.3.1 Remote installation procedure.

For details about how to specify a destination when creating a job, see 10.2.4 Setting up the Destination page.

Execute the ID group job.

Assign a policy to the ID group.

New computers are automatically registered in the ID group. Whenever a new computer is registered in the ID group, the job executed as an ID group job is automatically executed on the computer the next time that computer connects to the higher system.

For details about how to assign policies to ID groups, see 6.3 Automatic ID group maintenance.

Checking the job execution status:

For details about how to display the execution status, see 10.4.3 Items displayed in the Job Status window.

For details about how to check the execution status, see 10.4.5 Checking the status of an ID group job.

Re-execute failed jobs:

For details about how to re-execute jobs, see 10.5.2(2) Re-executing a job with an error.

2.4.3 Cautionary notes

For notes on packaging, see 7.1.4 Notes on packaging.

For notes on using ID groups, see 5.3.5 Notes on using ID groups.

For notes on linking system configuration information with ID groups, see 5.4.3 Notes on linking system configuration information with ID groups.

For notes on checking execution statuses of ID jobs, see 10.4.5(3) Important notes on checking the status of an ID group job.

For notes on automatically adding computers to ID groups, see 6.3.2 Notes on automatic ID group maintenance.

2.5 Maintaining performance levels through regular maintenance

When you use the system for extended periods of time, device information accumulates in the system. Not only does this cause the database to occupy more space, but tasks such as searching and updating the database will take longer. These factors reduce the performance of the system as a whole.

To avoid this kind of drop in performance, we recommend that you regularly review how much of the information below is being retained by the system, and delete any that is no longer needed. One way to do this is by outputting the information to a CSV file.

For details about how to output information to a CSV file, see 11.1.1 Items that can be output to CSV files.

To minimize fragmentation of the database, we recommend that you re-organize the database after deleting the information.

System configuration

You can use CSV file output to output destination attributes and check the number of registered items.

You can delete unnecessary hosts as part of device maintenance.

For details about device maintenance, see the description of auto maintenance of devices in the JP1/IT Desktop Management 2 Overview and System Design Guide.

For details about how to delete deletion history information that is no longer needed, see 6.5.4 Deleting deletion history.

Installed package information

You can use CSV file output to output installed package information and check the number of registered items.

For details about how to delete installed package information, see 7.5 Deleting installed package information.

Jobs

Job definitions

You can view the number of registered items in the Job Definition window of the Remote Install Manager.

You can also make jobs easier to manage by creating folders in which to store jobs of a certain type.

For details, see 10.3.2 Managing saved jobs and folders.

Job execution results

You can use CSV file output to output job statuses and check the number of registered items.

In addition to the Job Status window, you can use commands to execute and delete jobs.

For details about how to delete jobs, see 10.5.1 Deleting a job.

You can also reduce disk usage by configuring the saving of job execution results so that the system only records important job execution results.

For details about how to configure the saving of job execution results, see the description of the procedure for setting up the management server in the JP1/IT Desktop Management 2 Configuration Guide.

Note:

If a vast number of jobs remains, the performance of the management server is deteriorated. Delete unnecessary jobs such as completed jobs from the Job Status window periodically.

Packages

You can use CSV file output to output package attributes and check the number of registered items.

In addition to the Package window, you can use commands to delete registered packages.

For details about how to delete packages, see 7.4.5 Deleting cabinets and packages.

3 System Design

This chapter describes the issues you need to consider when designing a system in which Remote Install Manager is used to distribute software. For information about the design of a JP1/IT Desktop Management 2 system in general, see the JP1/IT Desktop Management 2 Overview and System Design Guide. Having completed the design process, you can then build the JP1/IT Desktop Management 2 system. For details about how to build the system, see the description of building various system configurations in the JP1/IT Desktop Management 2 Configuration Guide.

3.1 Network environment considerations

This section describes the network environment used by JP1/IT Desktop Management 2. It also explains the configuration required to use by JP1/IT Desktop Management 2 in systems that use firewalls and in multi-LAN environments.

3.1.1 Network environment for distribution function

JP1/IT Desktop Management 2 exclusively uses the TCP/IP protocol for network communication. As such, it does not depend on a specific network operating system such as Windows Server. You can also use JP1/IT Desktop Management 2 in environments where multiple network operating systems coexist with communication programs (TCP/IP protocol stacks) on managed computers.

You can use WINS or DNS to manage host names. However, we do not recommend that you design a system in which a single name server manages the host names of every computer. In such a system, name resolution queries are concentrated on a single name server, resulting in significantly lower system performance. In this scenario, using a hosts file to manage names places a lesser burden on the network.

Note:

When you control the network bandwidth used for distributions using Remote Install Manager, if multiple computers whose settings of controlling the data flow are different are designated to distribution destinations and jobs are executed simultaneously, it might take a long time to complete the jobs regardless of the settings of controlling the data flow. To complete the jobs in time according to the settings of controlling the data flow, designate only computers whose settings of controlling the data flow are same to distribution destinations and execute the jobs.

3.1.2 Determining the ID key used to identify hosts

There are two types of keys you can use to identify hosts: host IDs and node identification keys. You can use either as the ID key for operations on a JP1/IT Desktop Management 2 host.

Host ID

A host ID is a value that uniquely identifies a computer in the JP1/IT Desktop Management 2 system. Unlike the node identification key described below, host IDs are not affected by changes to the network configuration. A host ID is created when JP1/IT Desktop Management 2 - Agent is installed on a computer, and stored in the host ID management file.

Node identification key

You can use host names or IP addresses as the node identification key. You cannot use both, so one or the other must be selected during the setup process before you start using JP1/IT Desktop Management 2.

You can change the node identification key that you are using in the middle of the operation, but you will need to delete the following information:

System Configuration

Destination

Job Definition

Job Status

When determining the ID key used to identify JP1/IT Desktop Management 2 hosts, evaluate whether to use host names or IP addresses as the node identification key.

(1) Selecting the node identification key

In a network that uses JP1/IT Desktop Management 2, the name used to manage a node (host) is called the node identification key. You can use host names or IP addresses as the node identification key.

Because you cannot use host names and IP addresses together, you must decide which you want to use before you start using the system. For managing servers in a hierarchical structure, there is no need to unify node identification keys within the entire system. Unify node identification keys within the systems managed by a management relay server.

(a) Using host names to manage nodes in JP1/IT Desktop Management 2

You must use host names to manage nodes in the following systems:

Systems in which a firewall is deployed

Systems that use DHCP

Assign host names according to the rules described in 5.1.2 Assigning host names in JP1/IT Desktop Management 2.

(b) Using IP addresses to manage nodes in JP1/IT Desktop Management 2

In systems where host names are not an ideal way to manage the nodes in the network, you can use IP addresses instead. When you use IP addresses to manage nodes, relay systems and managed computers do not need name resolution definitions such as the hosts file, but management relay servers need such definitions.

3.1.3 Setting up the TCP/IP environment

Before installing JP1/IT Desktop Management 2, you need to prepare the TCP/IP environment. This involves the following task:

Defining host names and IP addresses

When you use IP addresses as node identification keys, relay systems and managed computers do not need to have host names defined, but management relay servers do need to have host names defined.

(1) Defining host names and IP addresses

First, you must define the host names and IP addresses in the user network.

When using host names as the node identification key, you use the host names defined in the user network in the user interface (the System Configuration window and Destination window) on the managing server. If you change a host name in these windows, you also need to change the definition of the host name in the user network.

JP1/IT Desktop Management 2 - Manager uses TCP/IP host names to identify computers. For this reason, the computer on which you install JP1/IT Desktop Management 2 - Manager must be able to determine an IP address from the associated host name.

There are three ways to define host names and IP addresses and allow the managing server to determine the IP address of a computer from its host name:

Using DHCP and WINS

Using DNS

Editing the hosts file

Each method is described below.

(a) Using DHCP and WINS

Because DHCP dynamically assigns IP addresses to computers, it can reduce the workload associated with IP address allocation and maintenance. However, JP1/IT Desktop Management 2 cannot use a dynamically changing IP address as a node identification key. In environments that use DHCP, you need to use host names to identify nodes.

If you use WINS to manage the host names of individual computers, you do not need to define the host names on each computer. When DHCP dynamically assigns a new IP address to a computer that has been moved from one subnet to another, the WINS database is updated automatically to reflect the change. This removes the need to change definitions manually.

When a computer is shut down, its information is removed from the WINS database. As a result, JP1/IT Desktop Management 2 will no longer be able to determine an IP address for the computer from its host name, and jobs may end in an error. For details about how to configure DHCP and WINS, see the Windows Help.

(b) Using a DNS

You can use a DNS if you need to specify hosts connected via the Internet as connection destinations. By defining the host names managed by the DNS in JP1/IT Desktop Management 2, you can execute jobs that perform remote installation in a remote domain.

For details about how to configure the DNS, see the Windows Help.

Note the following when using a DNS:

To use a DNS, you must configure the network software associated with the TCP/IP protocol. Specify the name of the domain to which the computer belongs, and the IP address of the server that manages the name.

Configure the DNS so that it supports bidirectional conversion, allowing conversion from host name to IP address and vice versa.

When using both a hosts file and a DNS, do not specify the fully qualified domain name of a host that uses a DNS for name resolution under another name in the hosts file. A fully qualified domain name consists of the host name followed by a period and then the domain name.

If a remote host that is directly connected to a network provider is assigned a temporary name as its host name, JP1/IT Desktop Management 2 will not be able to manage that host.

(c) Editing the hosts file

In environments that do not use DHCP, WINS, or DNS, you must define the host name of the connection destination for each host. On the host where the managing server is running, you must define the host names and IP addresses of the connected relay systems, management relay servers, and managed computers. On each host where JP1/IT Desktop Management 2 - Agent is running, you must also define the host name and IP address of the managing server.

To define host names and IP addresses, edit the following file:

Windows-directory\system32\drivers\etc\hosts

Format:

IP-address host-name alias

Example:

192.0.0.1 hostA NetworkA-hostA

192.0.0.2 hostB NetworkA-hostB

(2) Using JP1/IT Desktop Management 2 - Agent (agent)

Before using JP1/IT Desktop Management 2 - Agent (agent), check the following aspects of the system:

Check TCP/IP settings

From the Control Panel, select Network. On the Configuration page, make sure that TCP/IP appears in the The following network components are installed area. If TCP/IP is not listed, click the Add button on the Configuration page and add TCP/IP.

Next, on the Configuration page, select TCP/IP and click Properties. When the TCP/IP Properties dialog box appears, make sure that the required network settings are in place.

Configure the communication environment file

The hosts file can be found in the Windows directory (called windows by default). In the hosts file, define the name of the higher connection destination host and its IP address.

3.1.4 Using the distribution function in a firewall environment

You can use JP1/IT Desktop Management 2 in systems that use a firewall without compromising the security of the system as a whole. Even when a firewall controls the network between the distribution site where the managing server is located and the departmental networks where the relay system is deployed, software can still be distributed from the managing server to the relay system.

This subsection describes how to use JP1/IT Desktop Management 2 in an environment that uses firewalls.

When you use JP1/IT Desktop Management 2 in an environment that uses firewalls, you need to enter the port numbers used by JP1/IT Desktop Management 2 in the firewall settings. For details about these port numbers, see the description of port numbers in the JP1/IT Desktop Management 2 Overview and System Design Guide.

(1) Supported firewalls

JP1/IT Desktop Management 2 supports the following types of firewall:

Packet filtering

Application gateway

(a) Packet filtering firewall

A packet filtering firewall is an approach to building a firewall that limits which packets can pass through the firewall.

You can use JP1/IT Desktop Management 2 in an environment with a packet filtering firewall by setting the port numbers and IP addresses of the applicable nodes.

(b) Application gateway firewall

An application gateway firewall is an approach to building a firewall that prohibits packet relay and uses an application gateway to control access.

Because an application gateway firewall uses gateways to control access at the application level, you must permit access to JP1/IT Desktop Management 2 in the firewall settings.

3.1.5 Using the distribution function in a multi-LAN environment

You can use JP1/IT Desktop Management 2 in environments with multiple LAN connections, in which a single computer incorporates multiple network adapters (such as NICs).

JP1/IT Desktop Management 2 supports the following multiple LAN connection environments:

Environments divided into multiple networks

Environments with duplex networks

The following describes how to use JP1/IT Desktop Management 2 in each of these environments.

(1) Environments divided into multiple networks

The following figure shows an example of an environment divided into multiple networks:

Figure 3‒1: Example of environment divided into multiple networks

In a network environment that is divided into multiple networks, each job execution request includes the IP address of the requesting system. This allows managed computers to request jobs from the correct source.

When a higher system requests job execution:

The higher system acquires the IP address of the local system that successfully established a socket connection with the lower system, and communicates it to the lower system as the requesting source IP address.

When a lower system requests job reception:

The lower system establishes a socket connection to the requesting source IP address received with the job execution request from the higher system, and requests job reception.

(2) Environments with duplex networks

The following figure shows an example of an environment with duplex networks:

Figure 3‒2: Example of environment with duplex networks

In an environment with duplex networks, operation might switch to the backup network when a failure occurs in the main network. You might also have adopted a configuration in which the communication lines used by JP1/IT Desktop Management 2 are limited to those of the main network.

You can use JP1/IT Desktop Management 2 in this kind of environment by assigning an order of priority to network adapters when you configure the agent software. The relevant settings can be made in the Settings to perform polling for multiple higher systems area of the Communication settings page during agent setup.

3.1.6 Minimizing the load on the network

JP1/IT Desktop Management 2 transfers distributed software and various forms of management information over the network. To ensure that the system operates at its full potential, you need to take measures to minimize network congestion, for example by executing jobs when the load on the network is lightest. JP1/IT Desktop Management 2 provides a number of functions that help minimize the load on the network. This includes adjusting the network traffic during setup, and distributing software in segments. This subsection describes how to make the best use of network resources and distribute software as efficiently as possible. Efficient software distribution in JP1/IT Desktop Management 2 requires you to consider the settings and operations on managed computers, not just the managing server. For details about the tasks performed on managed computers, see Chapter 12. Performing Operations on the Agent.

(1) Using relay systems

To transfer packages efficiently during remote installation, you need to understand the role of relay systems.

A relay system distributes the load on the network by reducing the number of managed computers that connect directly to the managing server. It also helps transfer packages to the managed computers under the relay system more efficiently by creating and saving copies of packages. Also, by combining a Transfer package to relay computer job with an Install package job, you can transfer a package in two stages.

The following figure shows the operation of a relay system during remote installation:

Figure 3‒3: Operation of a relay system during remote installation

A package specified in a Transfer package to relay computer job is stored on the relay system. The managing server will not redistribute the same package as long as it remains on the relay system. You can specify the storage period during packaging.

(2) Adjusting the number of hosts that can be connected concurrently

If the number of leased lines is limited or the network is unable to handle additional traffic, you need to adjust the number of hosts that can connect to the managing server at one time. There are two ways to adjust the number of concurrent connections on the managing server:

Adjust concurrent connections during setup or in the agent configurations

Adjust concurrent connections through user operations during job execution

(a) Adjust the maximum concurrent connections during setup or in agent configurations

You can control network traffic in the setup of the managing server. From the menu, select Setup to display the Setup for Distribution by Using Remote Install Manager window, and then display the Server Customization Options page. For a relay system, use the Relay system settings page of the agent configurations.

Figure 3‒4: Server Customization Options page

The setting that governs the number of concurrent host connections is Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently. For a relay system, the relevant setting is Specify the number of job download requests to be executed concurrently, in the Processing settings for the relay system area of the Relay system settings page.

If a managing server executes jobs that target a large number of managed computers at the same time, the load on the network will increase dramatically. By specifying Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently, you can limit the number of lower hosts on which jobs can be processed at one time. For example, if you specify 20 for this setting, a job that remotely installs software on 300 computers is executed in 15 batches of 20 computers each.

(b) Adjust the maximum concurrent connections by user operations

During setup, you can specify a value that takes into account PC performance, the network configuration, and the operating environment. This provides a sufficiently reliable system in most cases. However, when large amounts of data are being transmitted, the network might become overloaded even if you control the amount of data being distributed. Ultimately, it might still be necessary for users to make adjustments.

Adjusting the number of computers targeted by a job

Suppose that you transfer a 5 MB package over a 64 Kbps line. If the line is 60% efficient, the transfer will take approximately 18 minutes. The transmission of a package from the managing server to the relay systems and from the relay systems to the managed computers takes place in parallel. Determine the number of computers to which a single job can be distributed by considering the load on the connection lines, the transfer speed, and the efficiency of the line.

Adjusting the number of concurrent connections by relay systems

To prevent a situation in which a large number of relay systems connect to the managing server at the same time, we recommend that you use split job execution. Although this method places additional burden on the user, it is an effective way of reducing the load on the network.

First, decide which relay systems connect concurrently to the managing server by considering the network traffic and other factors. Then, classify the managed computers under each relay system as a group. When you execute the job, leave an interval between job execution times for each group. The interval should be equivalent to the time it takes to process the job. In this way, you can avoid a situation in which a large number of relay systems connect to the managing server at the same time.

(3) Scheduled distribution

When you create a remote installation job, you can specify the date and time at which the job is executed. This serves as the transmission time of the package. You can transfer packages efficiently by specifying a time when network traffic is relatively light, such as at night.

If you use different jobs to transfer packages from the managing server to relay systems and from the relay systems to managed computers, you can specify different execution times for these jobs.

You can reduce the load on the network by scheduling package transfer in a considered way, rather than reducing the volume of data to be transmitted.

Note that software distribution cannot take place if the destination computer is in power saving mode. JP1/IT Desktop Management 2 - Agent (agent) is not active in this mode. If certain destination computers might enter power saving mode, take care when scheduling jobs that target those computers.

(4) Split package distribution

The software to be installed on a computer can be distributed in multiple segments. This is called split distribution. Split distribution offers the following benefits:

You can reduce the load on the network when distributing large packages.

You can insert intervals (distribution interval) between segments.

If there is a relay system or management relay server on the route to the distribution destination, you can change the size of each segment and the transmission interval at the relay location.

If you no longer wish to perform split distribution of a particular package, you can change the mode from split distribution to normal distribution and transfer the remainder of the package in a single transfer.

The following figure shows software distribution using split package distribution:

Figure 3‒5: Software distribution using split package distribution

(5) Multicast distribution

When distributing software normally, the number of packets sent from higher systems increases in proportion to the number of managed computers. However, JP1/IT Desktop Management 2 also supports a distribution method in which the higher system distributes software to a large number of specified managed computers by transmitting the packets for a job only once. This method is called multicast distribution, and can help reduce the total number of packets that need to be sent.

By specifying multicast distribution when you distribute software, you can reduce the amount of packet data sent by the managing server. This shortens the time required for distribution and reduces the load on the network. Multicast distribution is useful in the following situations:

When simultaneously distributing software to a large number of computers

When distributing large software packages

The figure below shows software distribution using multicast distribution. You can use multicast distribution only between computers and their connection-destination higher systems.

Figure 3‒6: Software distribution by multicast distribution

For details about the system configuration and settings required to implement multicast distribution, see 3.2 Settings for multicast distribution.

(6) Suspending and resuming jobs

You can temporarily suspend job execution on a host where remote installation or package transfer is in progress. For example, you might schedule a job to be executed outside business hours. In this case, if the job has not finished when the business day begins, you can suspend the job and resume it after business hours.

You can also distribute a specific job while distribution of other jobs is suspended. For example, if you need to distribute a virus definition file urgently, you can suspend other distribution jobs and prioritize distribution of the virus definition file.

(a) Mechanism for suspending and resuming jobs

You can suspend and resume jobs by:

Issuing an instruction from the managing server that directs relay systems or management relay servers to suspend or resume distribution

Issuing an instruction to the managing server directing it to suspend or resume distribution

Executing the dcmsusp command on the managing server

For details about the dcmsusp command, see 14.17 dcmsusp.exe (suspending and resuming file transfer).

You can suspend file transfer in units of 4,096 bytes.

Issuing an instruction from the managing server that directs relay systems or management relay servers to suspend or resume distribution

You can direct relay systems to suspend or resume distribution by executing a Suspend file transfer job or a Resume file transfer job. As the destination of these jobs, specify the higher system that is directly connected to the hosts on which you want job distribution to be suspended.

The following figure shows the operation of the system during execution of a Suspend file transfer job:

Figure 3‒7: System operation during Suspend file transfer job

From the managing server, execute a Suspend file transfer job to the relay system or management relay server.

The destination relay system or management relay server enters suspended status.

File transfer is suspended between the relay system or management relay server in suspended status and the systems directly under it, and the status of jobs destined for these lower systems changes to Suspended.

The following figure shows the operation of the system during execution of a Resume file transfer job:

Figure 3‒8: System operation during Resume file transfer job

From the managing server, execute a Resume file transfer job to the relay system or management relay server in suspended status.

The destination relay system or management relay server is released from suspended status, and the status of jobs destined for the lower systems changes to Resumed.

Suspended file transfers are resumed, and the job status changes back to Running.

Issuing an instruction to the managing server directing it to suspend or resume distribution

You can use Remote Install Manager to issue an instruction to the local system directing it to suspend or resume distribution. To do so, from the Execute menu, select Suspend/Resume File Transfer and then Suspend or Resume.

The following figure shows the operation of the system when file transfer is suspended or resumed locally:

Figure 3‒9: System operation when suspending or resuming file transfer locally

From the Remote Install Manager menu, select Suspend.

The local system enters suspended status.

File transfer is suspended between the local system and the systems directly below it, and the status of jobs destined for these lower systems changes to Suspended.

From the Remote Install Manager menu, select Resume.

The local system is released from suspended status, and the status of jobs destined for the lower systems changes to Resumed.

Suspended file transfers are resumed, and the job status changes back to Running.

(b) Distributing jobs to suspended destinations

You can ensure that a job is distributed even when the system immediately above the destination is in suspended status. You can do this by selecting Distribute on the Job Distribution Attributes page when creating the job in the Create Job dialog box.

The following figure shows the distribution of a job to a suspended destination:

Figure 3‒10: Job distribution to suspended destination

When you suspend job distribution for a host, file transfer to systems directly below that host is suspended as soon as the host enters suspended status. However, file transfer will not be suspended for jobs for which the Distribute option was selected.

(c) Scope of suspension and resumption of job distribution

The scope of job suspension and resumption is as follows:

The following three types of jobs can be suspended:

Install package jobs

Transfer package to relay computer jobs

Send package, allow client users to choose jobs

You must use the managing server to create Suspend file transfer and Resume file transfer jobs.

(7) Using Client Control

Client Control is a function that allows you to start and shut down PCs remotely via a network. By using this function, JP1/IT Desktop Management 2 can remotely turn on remote PCs and install software at night, on weekends, and on holidays.

To use the Client Control function, the remote PC must support AMT or Wake on LAN, and also support automatic shutdown. Note that agents for UNIX cannot be shut down automatically after a job is executed. In addition, you cannot specify to shut down a computer for the following jobs executed on an agent for UNIX or an agent for Mac: Get system information from computer (UNIX) and Get software information from computer (UNIX).

The following figure provides an overview of remote installation using Client Control:

Figure 3‒11: Remote installation using Client Control

For notes on remote installation using Client Control, see 3.3 Settings for using Client Control.

(8) Using offline installation

You can install software on a computer with JP1/IT Desktop Management 2 - Agent installed that is used as a standalone device (an offline machine) without using the network. This process is called offline installation.

Offline installation involves creating media on the managing server that contains the files required for installation, and then physically transporting the media to the offline machine.

For details about how to perform offline installation, see 7.3.4 Offline installation.

3.2 Settings for multicast distribution

By specifying multicast distribution when you create a job, you can reduce the amount of data that is transferred, lessening the load on the network and shortening transfer times.

This section provides an overview of multicast distribution, and describes how to configure a system to support it. It also describes the steps involved in multicast distribution, and provides notes on its use.

3.2.1 Unicast distribution and multicast distribution

In JP1/IT Desktop Management 2, there are two ways to distribute jobs: unicast distribution and multicast distribution. You can specify a different distribution method for each job.

A method of job distribution in which packets are sent from a higher system to each computer individually is called unicast distribution. Because the higher system has to send each job packet to each target computer, the number of times a packet is sent increases in proportion to the number of computers in the system.

In contrast, multicast distribution uses the IP multicast protocol to send packets to many specific computers from a higher system. In multicast distribution, the higher system distributes packets to a conceptual group called a multicast group. The packets are then distributed to each computer in that group. This method uses less traffic because the higher system only needs to send the job packet to one multicast group, regardless of how many computers belong to the group.

Each multicast group has its own unique IP address called a multicast address. During multicast distribution, packets are sent to this address. You can specify a multicast address when setting up the agent software on a managed computer. This registers the computer in the multicast group. Packets sent to a multicast address are distributed to all computers registered in that multicast group. Because a packet travels the common parts of the routes to the computers only once, jobs can be distributed efficiently without overloading the network.

The following figure illustrates the concept of unicast and multicast distribution:

Figure 3‒12: Concepts of unicast and multicast distribution

(1) Jobs distributed using multicast distribution

In JP1/IT Desktop Management 2, only Install package jobs can be distributed by multicast distribution. You can reduce the amount of traffic on the network considerably by using multicast distribution for the following types of jobs:

Jobs with a large number of destinations

Jobs requiring distribution of large packages

If a job has only a few destinations, or the associated package is small, multicast distribution can actually be less efficient. For jobs of this nature, specify unicast distribution when you create the job.

Note that whether you select multicast or unicast distribution when you create a job governs only the method of job distribution. It does not affect the destinations of the job. Regardless of whether the destination is an individual host, host group, or ID group, the job is distributed to the specified destinations using multicast distribution. If a computer specified as a destination is not registered in a multicast group, the job is distributed to that computer using the unicast method.

(2) Routes used by multicast distribution

When you specify multicast distribution for a job in JP1/IT Desktop Management 2, the packets are sent by multicast distribution only between the higher system and the managed computers directly connected to it. Unicast distribution is used between the system that executes the job and the higher system to which the managed computers are directly connected.

3.2.2 Network configuration required for multicast distribution

Multicast distribution requires the following network environment:

If a router is present between the managed computers and the higher system to which they connect, that router must support IP multicasting and have IP multicasting enabled. If a router on the route does not support IP multicasting, jobs are distributed using unicast distribution from that network segment onward.

3.2.3 System configuration required for multicast distribution

This subsection explains how the system must be configured in order to use multicast distribution.

(1) Standard system configuration for multicast distribution

The figure below shows the standard system configuration for implementing multicast distribution, and the flow of packets through the system.

Figure 3‒13: Standard system configuration for multicast distribution and packet flow

You need to create a multicast group for each higher system to which managed computers connect. Each of these multicast groups must be assigned a unique multicast address. The descriptions below relate to the corresponding number in the figure. 1 and 2 describe settings in the system configuration, and 3 and 4 describe the packet flow when a job is executed.

The group of computers that connect to relay system A is deemed multicast group A, and the group that connects to relay system B is deemed multicast group B. Assign the multicast address 239.255.0.1 to the computers in multicast group A, and the multicast address 239.255.0.2 to the computers in multicast group B.

Specify the multicast address of multicast group A (239.255.0.1) on relay system A, and the multicast address of multicast group B (239.255.0.2) on relay system B.

Relay system A can now use multicast distribution to distribute jobs to the computers in multicast group A, and relay system B can use multicast distribution to distribute jobs to the computers in multicast group B.

On the managing server, create a job with multicast distribution specified, and execute the job.

The managing server sends the packets for the job to each relay system. In this example, two relay systems are connected to the managing server, which means that an amount of packets equivalent to two jobs are sent. The jobs are sent to relay systems A and B by unicast distribution.

Relay systems A and B each send packets for just one job, regardless of the number of computers. Packets equivalent to one job flow on the common routes to each computer (multicast distribution).

Assuming the same system configuration, suppose the job were distributed using unicast distribution. In this scenario, the number of job packets flowing from the higher systems to which the managed computers are connected to the destination computers would be equivalent to the number of computers. Therefore, three times the number of packets would be sent from relay systems A and B along the routes shown in 4.

You can use multicast distribution to distribute jobs even in a configuration in which the managed computers connect directly to the managing server. In this case, you must specify the multicast address of the destination multicast group on the managing server.

3.2.4 Executing multicast distribution

After you decide the system configuration, you can use multicast distribution by following the procedure below.

Enable multicast distribution when setting up the hosts that will send or receive multicast distribution.

When creating a job on the managing server, specify Multicast distribution as the distribution method.

Each step is described in more detail below.

(1) Setup

When setting up a higher system to which managed computers will connect, specify the settings for multicast distribution. The location of the relevant settings is as follows:

Settings in JP1/IT Desktop Management 2 - Manager

The Multicast Distribution page of the Setup for Distribution by Using Remote Install Manager window, or the Multicast distribution settings area of the Communication settings page during agent setup.

Specify the port numbers and multicast address during the setup process. You also need to specify the packet size. You can then specify this multicast address as the destination for a job. Note that jobs for which unicast distribution is specified will be distributed by the unicast method even if you specify multicast distribution during setup.

Notes on setup:

You do not need to configure multicast distribution on systems that are higher in the hierarchy than the systems to which managed computers connect. For example, if the connection sequence is manager, relay system, then managed computer, you do not need to set up multicast distribution on the manager.

If a router that is not compatible with IP multicasting is present between managed computers and the higher system to which they connect, unicast distribution takes place instead of multicast distribution. In this scenario, do not specify multicast distribution for the higher system or relay system. If you specify multicast distribution, a delay occurs while the system switches to unicast distribution.

(2) Creating a job for multicast distribution

You can specify multicast distribution at the job level. To distribute a specific job using multicast distribution, in the Create Job dialog box, display the Job Distribution Attributes page and specify Multicast distribution in the Distribution methods area. For details about how to create a job, see 7.3 Performing remote installation.

3.2.5 Notes on multicast distribution

Note the following when using multicast distribution:

If you specify the same multicast address for multiple relay systems or management relay servers in a network, the job will be distributed by multicast distribution from each of those relay systems or management relay servers to their respective connected computers. To avoid this kind of duplicate job distribution, specify a unique multicast address for each relay system or management relay server.

If a managed computer has a different multicast address from its higher system, jobs are distributed by unicast distribution even if you specify multicast distribution. For example, if a relay system goes down and jobs have to be temporarily distributed via another relay system with a different multicast address, those jobs will be distributed by unicast distribution.

You cannot use multicast distribution to distribute jobs with split distribution specified.

If the agent software is not running or the managed computer has not been turned on when multicast distribution starts, multicast distribution takes place after the agent starts or the managed computer is turned on.

If a computer is unable to receive an entire job sent by multicast distribution, the remainder is sent automatically by unicast distribution.

When creating a job, do not select Multicast distribution together with Start the target computer if it is not running (Client Control page). If you execute a job with both specified, distribution will take a long time to computers that are turned off. If you want to distribute a job by multicast distribution to a computer that is turned off, turn on the computer before executing the job.

If there are machines that receive a unicast package (a dialog box is displayed during the download) a few minutes after executing the job which is specified as Multicast distribution, specify a smaller value (a few KB) in the agent configuration Communication settings - Multicast distribution - Maximum packet size for job transmission.

However, when you specify a smaller value, the time required for downloading takes longer inversely. If the packet size is halved, the time required for downloading will be doubled.

3.3 Settings for using Client Control

This section describes the settings required to use the Client Control facility, and provides cautionary notes that apply to its use.

The Client Control facility can use Wake on LAN to start managed computers. When you use the Client Control facility, it automatically selects the appropriate startup method for the environment of the managed computer and executes the job accordingly.

Note that agents for UNIX cannot be shut down automatically after a job is executed. In addition, you cannot specify to shut down a computer for the following jobs executed on an agent for UNIX or an agent for Mac: Get system information from computer (UNIX) and Get software information from computer (UNIX).

3.3.1 Settings for using Wake on LAN

This subsection describes the settings you need to specify in the agent configurations.

(1) Items requiring careful consideration

Max. number of subsystems in which jobs can execute concurrently

You cannot start destination systems if 0 is specified for the following options in the setup of the manager that starts the computer, or in the agent configurations of the relay system:

On the management server, the value of Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently on the Server Customization Options page of the Setup for Distribution by Using Remote Install Manager window.

On the relay system, the value of Number of JP1/IT Desktop Management 2 - Agent instances that can execute jobs concurrently in the Processing settings for the relay system area of the Relay system settings page.

(2) Items with recommended values

Polling settings

We recommend that you enable the Client will poll the managing server option in the polling settings.

(3) Notes

The cautionary notes below apply when using Wake on LAN to perform Client Control.

(a) Notes on the system configuration

When using the Client Control facility in a system configuration in which a router is located on job routes, you must use one of the network configurations below. From a security perspective, the first environment is preferred.

Deploy one or more management relay servers or relay systems for each router, and ensure that they are always running (recommended).

Configure the router to pass broadcast packets.

In this case, you do not need to deploy management relay servers or relay systems for each router.

If you configure the router to pass broadcast packets, the system might be vulnerable to Denial of Service (DoS) attacks. To avoid this possibility, use the first environment above.

(b) Notes on hardware

Note the following in relation to hardware when using the Client Control facility:

In the BIOS settings, enable any items relating to Wake on LAN.

If a hub or NIC supports the LinkChange function, turning on that device will cause computers with Wake on LAN enabled to start. To avoid this issue, either leave the device on, or disable the LinkChange function.

A LAN card outputs three types of signals: RWU-High, RWU-Low, and PME. Because the type of signal the card uses depends on the motherboard, you need to set the jumper pins appropriately. For details about the pin settings, see the documentation for your LAN card.

(c) Notes on startup

Note the following when using the Client Control facility to start computers:

If you execute multiple jobs using the Client Control facility, and each job is configured to start the destination computer, only the first startup request to a given destination takes effect. Subsequent requests to the same destination by other jobs are ignored.

The Client Control facility might not be able to start a computer that incorporates more than one network interface card.

If you execute a job with Start the target computer if it is not running specified, some computers might freeze during startup. This occurs when the interval between startup requests from JP1/IT Desktop Management 2 - Manager or JP1/IT Desktop Management 2 - Agent (relay system) is too short in relation to the startup time of the computer. You can resolve this issue by changing the following registry value of JP1/IT Desktop Management 2 - Manager or JP1/IT Desktop Management 2 - Agent (relay system) to a larger value than the startup time of the PC.

Registry keys:

- For JP1/IT Desktop Management 2 - Manager

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\HITACHI\JP1/IT Desktop Management - Manager\DM

- For JP1/IT Desktop Management 2 - Agent (relay system) on a 32-bit OS

HKEY_LOCAL_MACHINE\SOFTWARE\HITACHI\JP1/IT Desktop Management - Agent\DMP

- For JP1/IT Desktop Management 2 - Agent (relay system) on a 64-bit OS

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\HITACHI\JP1/IT Desktop Management - Agent\DMP

Name:

DeliveryExecSelectInterval

Data:

Minimum value (seconds): 30

Maximum value (seconds): 9,999

Default value (seconds): 60

3.3.2 Notes on shutdown

This section provides notes on using the Client Control facility to shut down computers.

When you attempt to automatically shut down a Windows computer, the computer might fail to shut down or might restart instead. Because this might occur when the hardware or Windows environment does not support automatic shutdown, check whether the hardware is compatible with automatic shutdown. Also, install the most recent updates provided by the hardware manufacturers to make sure that Windows conforms fully to the hardware specifications. If the hardware supports automatic shutdown and installing the latest updates does not resolve the issue, consult the documentation provided by Microsoft or the hardware manufacturer.

Shutdown requests issued to relay systems or management relay servers are ignored.

UNIX computers cannot be shut down automatically.

You cannot specify to shut down a computer for the following jobs executed on a computer running a UNIX or Mac OS: Get system information from computer (UNIX) and Get software information from computer (UNIX).

You cannot automatically shut down a Windows computer whose screen saver is active and password-protected.

A computer cannot be automatically shut down if a file is being edited on the computer when the job with the shutdown instruction is received.

When you execute a job that specifies shutdown from a higher system, the agent software does not behave as intended if the user has not yet logged on to the target computer. That is, the action specified in the Settings to shut down and restart the computer area of the User notification settings page in the agent configuration does not take place.

If the user has not yet logged on, and Automatically start if no response is received from the user within the specified period is selected in the agent configuration, the system shuts down without displaying a confirmation dialog box.

Here, executing a job from a higher system means all types of job execution except using Package Setup Manager on the managed computer.

3.4 Configuring the agent operating environment

This section describes how to configure the operating environment for the agent software to suit the network environment and the way the system is used.

3.4.1 Setting the agent polling method

An agent executes jobs it receives from the managing server. The managed computer must be running for the agent software to receive jobs from the managing server. If a communication error occurs or the managed computer is inactive, the agent cannot receive jobs from the higher system. In this situation, the agent can still monitor whether there are jobs with the local system specified as the destination. The process of monitoring for jobs from higher systems is called polling.

You can specify the polling timing and interval in the agent configurations. The available polling methods are listed below. Select the polling method that is most appropriate for how the agent is used.

No polling.

Perform polling only once, at system startup.

Perform polling at regular intervals beginning when the system starts.

Perform polling once a day at a scheduled time (JP1/IT Desktop Management 2 - Agent (agent) only).

Perform polling once a day when the system starts (JP1/IT Desktop Management 2 - Agent (agent) only).

3.4.2 Creating a multi-polling environment on an agent

The configuration of distribution destinations is defined in the system configuration information. This means that the jobs destined for an agent are executed over a predetermined route. Also, an agent will only connect to the relay system that is defined as its connection destination in the system configuration information.

If you want to specify multiple distribution routes or for an agent to connect to multiple relay systems, you must create a multi-polling environment. You can assign an order of priority to the relay systems to which the agent connects. When an error occurs in a relay system in a multi-polling environment, the managing server can execute a job on the agent via another relay system. The agent can also connect to multiple relay systems according to the priority of each relay system at the time the connection is made.

Note

If you are using ID groups for distribution, you can configure a multi-polling environment to enable automatic switching from one higher system to another (that is, change the destination to which the agent connects).

(1) Setting up a multi-polling environment

You can assign an order of priority to higher systems in the Higher systems to be polled area under Settings to perform polling for multiple higher systems on the Communication settings page of the agent configurations.

Figure 3‒14: Settings to perform polling for multiple higher systems on Communication settings page

Add button

Adds a higher system as a connection target. You can add a maximum of eight higher systems. In the Addition of a higher system to be polled dialog box, specify the product type of the higher system and its host name or IP address.

Remove button

Removes the selected higher system from the list.

▲ button

Moves the selected higher system up one priority level.

▼ button

Moves the selected higher system down one priority level.

(2) Selecting the polling method in a multi-polling environment

An agent can find out whether there are any jobs addressed to it by checking with the higher relay system. This is called polling. The method of polling the relay system is governed by the settings in the Settings to perform polling for multiple higher systems area of the Communication settings page. There are two polling methods:

Hot standby

In hot-standby mode, the agent only polls one relay system. Normally, the relay system with the highest priority in the Higher systems to be polled area is polled. If the agent cannot connect to that relay system, it polls the relay system with the second-highest priority. If this relay system cannot be reached, the agent polls the relay system with the next-highest priority. This continues until the agent successfully connects to a relay system, from which point it polls that system exclusively.

Multiple hosts

In multiple hosts mode, the agent polls every relay system listed in the Higher systems to be polled area. Polling takes place in order from the relay system with the highest priority.

Tip

If you want to enable automatic switching from one higher distribution system to another for file distribution, specify the following settings:

For Type of Polling for Multiple Higher Systems, select Hot Standby.

Select Poll higher systems according to their priority when the system starts.

Select the Perform a switchover of the higher system for distribution if polling fails for a specified period of time check box.

For details, see 7.6.15 Enabling automatic switching from one higher distribution system to another for file distribution.

(3) Notes on multi-polling environments

Note the following when using the agent in a multi-polling environment:

For agents operating in a multi-polling environment, you can register ID groups only on the higher system with the highest priority.

In hot standby mode, if the relay system with the highest priority recovers from an error, you can have the agent poll that system again by shutting down the relay system to which the agent is connected. The agent will poll the recovered relay system when polling next occurs.

When you execute jobs on all routes in an environment that uses the hot standby method, the job on the route to the relay system to which the agent is connected is executed. However, the jobs on all other routes remain on the relay systems in Not running status. Therefore, you must use the managing server to periodically delete the jobs remaining on the relay systems and the completed jobs. If a large number of jobs are left on a relay system, the performance of the relay system might suffer.

When you execute jobs on all routes in an environment that uses the multiple hosts method, the agent receives the same job from each relay system it polls. In this scenario, we recommend that you clear the Replace existing package check box in the job installation conditions when you execute a remote installation job. If this check box is selected, a package is sent each time the job is executed, which might place an excessive load on the network. If the check box is cleared, any job that the agent has already received ends normally without the package being sent again. The job maintenance code in this scenario is 900090009000.

3.4.3 Automatically changing the agent connection destination

If you distribute information to agents that can be used to determine connection destinations, the agent software can determine and automatically set the optimum higher system to which to connect, based on the IP address of the managed computer. Because the connection destination updates automatically when the IP address of the computer changes, this feature is useful when a computer is relocated. This subsection describes the automatic updating of connection destinations of agents.

You can use this function with JP1/IT Desktop Management 2 - Agent.

Note that this function is not supported on the Citrix XenApp and Microsoft RDS server.

(1) Automatically setting and changing the higher system

To automatically set and change the higher system to which an agent connects, you need to create an information file for higher connection destinations (dmhost.txt) and distribute it to the managed computers. After the file is distributed to the agent, the connection destination is reset automatically at specific times.

Note

You can also use the file for connection destinations (itdmhost.conf) to perform the same operation as when you use the information file for higher connection destinations (dmhost.txt). For details about itdmhost.conf, see the description of the procedure for automatically setting the connection destination of an agent in the JP1/IT Desktop Management 2 Configuration Guide.

(a) Creating an information file for higher connection destinations

An information file for higher connection destinations is used to determine the higher system to which an agent connects. This file defines connection-target higher systems corresponding to ranges of IP addresses of computers. For example, a file might define a PC at the New York branch as the connection destination of computers with IP addresses in the range from 172.16.22.1 to 172.16.22.255. The same file might define a PC in Chicago as the connection destination of computers with IP addresses in the range from 172.17.22.1 to 172.17.22.255. For details about how to create an information file for higher connection destinations, see 3.4.3(2) Creating an information file for higher connection destinations (dmhost.txt).

By placing the file you created in the data folder of JP1/IT Desktop Management 2 - Manager, you can incorporate it when creating the installation set.

(b) Distributing the information file for higher connection destinations to managed computers

When you install JP1/IT Desktop Management 2 - Agent using an installation set that incorporates an information file for higher connection destinations, the information file for higher connection destinations is placed in the following directory on the managed computer:

JP1/IT Desktop Management 2 - Agent-installation-directory\MASTER\DB

You can also distribute the file to target computers by registering the file as a package and creating a job that distributes the package. In this case, use the following settings when creating the package:

Installation target directory settings on System Conditions page:

Drive: None

Directory: %ITDM2AGT%\MASTER\DB

To store file manually, wait until the computer is registered as managed computer.

Note

If both the information file for higher connection destinations (dmhost.txt) and the file for connection destinations (itdmhost.conf) exist, dmhost.txt is ignored.

(c) Timing with which the connection destination changes

After placing the information file for higher connection destinations on the managed computer, either wait until polling takes place or restart the operating system of the managed computer. The contents of the file determine the higher system to which the agent connects.

There are two types of polling that can result in the connection destination of the agent changing:

Perform polling based on the system startup

The Perform polling based on the system startup check box is selected on the Basic settings page in the agent configuration

Perform polling at the specified time

The Perform polling at the specified time check box is selected on the Basic settings page in the agent configuration

After you enable these settings, the connection target will be set again if you wait for polling or restart the OS after the following operations:

The IP address of the managed computer changes

The information file for higher connection destinations is edited or overwritten

The connection destination changes when you restart the computer after redistributing the information file for higher connection destinations to the agent. It also changes when you restart the computer after directly editing and overwriting the file in the installation-directory\MASTER\DB directory of the agent.

If you relocate a managed computer and change its IP address, its connection destination changes to the appropriate higher system when polling takes place or you restart the operating system. This process is transparent to the end user.

When the connection destination of an agent is automatically set or changed based on the information file for higher connection destinations, the change is logged to the installation-folder\LOG\USER.LOG file on that computer.

(d) Relationship of other functions to automatic updating of connection destinations

The automatic updating of connection destinations based on the information file for higher connection destinations might be incompatible with some other JP1/IT Desktop Management 2 functions. Take note of the following.

If there is an information file for higher connection destinations in the installation-folder\MASTER\DB\ folder of the agent on a managed computer, the information in the file determines the higher system (managing server or relay system) of the agent. In this case, the connection destination of the agent will not be the higher system specified in the agent configurations.

You can stop an agent from using the contents of the information file for higher connection destinations by using the methods below. Either method results in the agent connecting to the connection destination specified in the agent configurations.

Distribute a blank information file for higher connection destinations to the agent

Delete the information file for higher connection destinations from installation-directory\MASTER\DB\ on the agent

Rename the information file for higher connection destinations in installation-directory\MASTER\DB\ on the agent to a file name other than dmhost.txt

(2) Creating an information file for higher connection destinations (dmhost.txt)

The information file for higher connection destinations is a text file with the name dmhost.txt. The following describes how to create this file.

(a) Format of information file for higher connection destinations

Each line of the information file for higher connection destinations defines a connection destination and the range of IP addresses of managed computers to which it corresponds. Each line can contain up to 1,023 bytes of characters (including single-byte and/or double-byte characters). Use a comma (,) as the delimiter between items. You can comment out a line by placing a semicolon at the beginning of the line. Do not enter a linefeed character at the end of the last line of the file.

The file format is as follows:

Format:

lowest-IP-address,highest-IP-address,connection-destination,connection-type[,connection-destination,connection-type] ... [,multicast-distribution-address]

Description:

lowest-IP-address (required)

Specify the lowest IP address in the range of managed computer IP addresses. Specify the address in the format xxx.xxx.xxx.xxx using single-byte numerals.

highest-IP-address (required)

Specify the highest IP address in the range of managed computer IP addresses. Specify the address in the format xxx.xxx.xxx.xxx using single-byte numerals.

connection-destination# (required)

Specify the host name or IP address of the connection destination. Specify a host name if host names are the ID key for connection destinations, or an IP address if IP addresses are the key. A host name must not exceed 64 bytes of single-byte alphanumeric characters. Specify IP addresses in the format xxx.xxx.xxx.xxx using single-byte numerals.

connection-type# (required)

Specify netmdm if the connection destination is a management server, and netmdmw if the connection destination is a relay system.

multicast-distribution-address (optional)

If you want to distribute jobs to managed computers using multicast distribution, specify the multicast address set at the connection destination. Specify the address in the format xxx.xxx.xxx.xxx using single-byte numerals. The range of addresses you can use as multicast addresses is 224.0.1.0 to 239.255.255.255.

#

You can specify a maximum of eight pairs of connection destinations and connection types on one line. If you specify multiple connection destinations and connection types, pairs defined earlier have higher priority.

Notes:

If the IP address of a managed computer is not within a defined range, the connection destination will not be changed.

If the IP address of a managed computer is the loopback address 127.0.0.1, the connection destination will not be changed.

If you specify a range of IP addresses that overlaps another specified range, the range that is defined earlier in the file takes effect.

A line is invalid in the following cases:

- Any of the first four items is omitted

- An invalid IP address is specified

- When connection-destination is 65 single-byte characters or longer

- A value other than netmdm or netmdmw is specified as the connection type

If you do not specify a multicast-distribution-address value or you specify an invalid value, the multicast address cannot be set. However, the IP address ranges and corresponding connection destinations in the first four parameters remain valid.

If you specify more parameters than the five described above, the additional parameters are ignored.

If a line is longer than 1,023 characters, the 1,024th and subsequent characters are ignored.

(b) Example of creating an information file for higher connection destinations

An example of creating an information file for higher connection destinations is shown below.

;Information about higher connection destinations
172.17.12.1,172.17.12.250,dmsub01,netmdmw,dmsub02,netmdmw,dmman01,netmdm
172.17.13.1,172.17.13.250,dmman01,netmdm,dmman02,netmdm
172.17.11.1,172.17.11.60,dmsub02,netmdmw
0.0.0.0,255.255.255.254,dmman02,netmdm

Suppose that the IP address of the managed computer is 172.17.11.6. In this example, because this IP address is in the range from 172.17.11.1 to 172.17.11.60 on the fourth line, the higher system that serves as the connection destination is the relay system with the host name dmsub02.

If you define a range that includes all IP addresses (0.0.0.0 to 255.255.255.254) as the last line of the information file for higher connection destinations, managed computers with no corresponding IP address range defined will connect to the host dmman02. In this example, this means managed computers whose IP address is outside the ranges from 172.17.12.1 to 172.17.12.250, 172.17.13.1 to 172.17.13.250, and 172.17.11.1 to 172.17.11.60. If you specify multiple connection destinations as on the second and third lines, the connection destination specified earlier has the higher priority (dmsub01 on the second line and dmman01 on the third line).

(c) Notes on system behavior after distribution of an information file for higher connection destinations

If you intend to change the IP address of a connection destination host after an information file for higher connection destinations has been distributed to the managed computers, you must delete the file from the managed computers first. If you do not delete the file before changing the IP address, the change to the IP address will trigger automatic changing of the connection destination. This might result in a managed computer connecting to the wrong higher system.

3.4.4 Connection settings when the name of the higher system cannot be resolved

In an environment that uses host names as the ID key for operations, a computer could lose the ability to access the DNS server due to quarantining or other actions. This means the agent would no longer be able to resolve the name of the connection-target higher system. In this situation, the agent can resolve the name from the IP address in the communications protocol when it receives an execution request from the higher system. If the network environment does not allow the agent to resolve the name of the connection-target higher system, the agent can use this approach to poll for jobs and send device information to the higher system. During this time, the agent will recognize the higher system that sends the execution request as its connection target.

To use this function, the Use the received IP address for connections with higher systems check box must be selected under Communication protocol for receiving execution requests on the Communication settings page of the agent configurations.

When you enable this function, a file for higher system addresses is automatically created on the managed computer when an execution request is received from a higher system. This file contains the mappings between IP addresses and host names of the higher systems. From that point onward, the managed computer uses the information in this file to resolve the host names of higher systems.

Under most circumstances, you do not need to edit the file for higher system addresses. However, in an environment in which the name of the higher system cannot be resolved, you need to create the file before deploying a computer that uses host names to access higher systems.

For details about the settings you need to use when deploying a computer that uses host names in an environment where the name of the higher system cannot be resolved, see 3.4.4(1) Settings for deploying a new managed computer in an environment where the name of the higher system cannot be resolved. For details about the format of the file for higher system addresses, see 3.4.4(2) Format of file for higher system addresses.

Notes:

You do not need to specify these settings in environments where IP addresses are used as the ID key for operations.

If the higher system is a cluster system, the managed computer might not be able to establish a connection.

(1) Settings for deploying a new managed computer in an environment where the name of the higher system cannot be resolved

If you deploy a computer that uses host names as the ID key for operations in an environment in which the name of the higher system cannot be resolved, the computer cannot connect to a higher system. This prevents the system from recognizing the computer as a destination. In this situation, you need to create a file for higher system addresses in advance, and use the following method to place the file on the managed computer.

Placing the file for higher system addresses on the managed computer after installing the agent software:

After installing the agent software, place the file for higher system addresses in the following folder:

JP1/IT Desktop Management 2 - Agent-installation-directory\MASTER\DB

When you restart the computer after finishing setup, the computer connects to a higher system based on the contents of the file for higher system addresses.

(2) Format of file for higher system addresses

You can enter mappings for multiple connection destinations in the file for higher system addresses. The managed computer connects to higher systems using the IP addresses that correspond to the host names in the file.

The file format is as follows:

File name:

SERVERIP.ini

Format:

[host-name]
IPaddress=IP-address
[#-filecheck]
key=Programcheck

Description:

host-name

Specify the host name of a connection destination of the managed computer. Host names are not case sensitive. If you specify the same host name more than once, the first appearance is valid.

IP-address

Specify the IP address that corresponds to the host name.

You can specify multiple combinations of host name and IP address.

Example:

The following is an example of a file for higher system addresses:

[host001]
IPaddress=10.100.100.20
[host005]
IPaddress=10.100.100.15
[host007]
IPaddress=10.100.100.57
[#-filecheck]
key=Programcheck

Note the following when creating a file for higher system addresses:

If an attempt to connect to an IP address results in an error, the pairing of host name and IP address that caused the error are deleted from the file.

If you delete the [#-filecheck] line from the file, the file for higher system addresses will be deleted.

The contents of the file for higher system addresses must consist of single-byte alphanumeric characters.

4 Performing Operations on the Managing Server

This chapter describes the basic operations of the managing server. The operation of a managing server requires the presence of a full JP1/IT Desktop Management 2 system. For details about how to build such a system, see the description for each system configuration in the JP1/IT Desktop Management 2 Configuration Guide.

4.1 Starting and stopping a managing server

The server functions of a managing server start automatically when the operating system starts, and cease automatically when the operating system shuts down.

If you want to start the managing server at any other time, execute the startservice command. To stop the managing server at any time, execute the stopservice command. For details about these commands, see the JP1/IT Desktop Management 2 Administration Guide.

4.2 Menus associated with the managing server

You can access the functions of the managing server by selecting them in the JP1/IT Desktop Management 2 program folder in the Start menu. The menu items for these functions are created in the Start menu when you install JP1/IT Desktop Management 2 - Manager with the Remote Install Manager component selected.

Of the menu items associated with the managing server, this section describes those used solely in the context of distribution by using Remote Install Manager.

Remote Install Manager

This menu item starts Remote Install Manager, a component that implements the main functions of the managing server such as software distribution and file collection.

For details about how to use Remote Install Manager, see 4.3 Starting and stopping Remote Install Manager and 4.4 Window structure and basic operations.

Unarchiver

This menu item starts the Unarchiver, a tool that restores compressed or archived files to their original form. Because files collected from managed computers by remote collection are archived or compressed, they cannot be read from or written to on the managing server until they are restored to their original form by the Unarchiver.

For details about how to use the Unarchiver, see 9.1.2 Restoring collected files.

4.3 Starting and stopping Remote Install Manager

The main functions of the managing server are operated from Remote Install Manager.

This section describes how to start and stop Remote Install Manager.

4.3.1 Starting Remote Install Manager

To start Remote Install Manager:

From the Windows Start menu, select JP1_IT Desktop Management 2 - Manager and then Remote Install Manager.

The Login (Remote Install Manager) dialog box appears.

Figure 4‒1: Login (Remote Install Manager) dialog box

Enter the information required to log in to the managing server.

In Management Server, enter the host name or IP address of the management server.

In Connection port number, enter the port number used for incoming connections from the computer used to log in to the management server.

In User ID and Password, enter the ID and password of a user who has system administrator permission and distribution management permissions in JP1/IT Desktop Management 2.

When you start Remote Install Manager, the window below appears. For details about the function of each menu item, see C. List of Menus.

Figure 4‒2: Remote Install Manager

Toolbar

Clicking a button on the toolbar executes the function associated with that button. You can display the function of a button by resting your mouse pointer over the button. You can show or hide the toolbar by selecting Toolbar from the View menu. While the toolbar appears at the top of the window when the system starts, you can drag it to another part of the window.

Labels

By clicking the labels (column headers) in each window, you can sort the window contents by the column whose label you clicked.

Status bar

The status bar shows JP1/IT Desktop Management 2 messages. You can show or hide the status bar by selecting Status bar from the View menu.

Operate Remote Install Manager as a user with administrator privileges (a user who belongs to the Administrators group in Windows).

4.3.2 Closing Remote Install Manager

To close Remote Install Manager, from the File menu, select Exit. Remote Install Manager will retain its window layout the next time it starts.

4.4 Window structure and basic operations

This section describes the role of each window in Remote Install Manager, and the basic operations you can perform in these windows.

The following table lists the windows displayed in Remote Install Manager:

Table 4‒1: Windows in Remote Install Manager

No.

Window

1

System Configuration window

2

Destination window

3

Package window

4

Job Definition window

5

Job Status window

6

List of Software Information window

4.4.1 System Configuration window

The System Configuration window displays information about the physical configuration of the systems managed by JP1/IT Desktop Management 2. Before you execute a job in JP1/IT Desktop Management 2, you must use this window to define each system targeted by the job.

Figure 4‒3: System Configuration window

The left pane of the window displays the system hierarchy. The right pane contains the tabs listed below. You can use these tabs to select which information appears in the right pane.

These tabs also appear in the Destination window.

List tab

Displays a list of systems under the system selected in the left pane.

Attributes tab

Displays the attributes (such as the host ID and host name) of the system selected in the left pane. Update date/time shows the date and time the system configuration was last updated. The item for which an icon appears in the Key column is the node identification key of the host.

Installed Packages tab

Displays a list of packages installed by Remote Install Manager on the system selected in the left pane.

Important

In the left frame of the System Configuration window of Remote Install Manager, when you select hosts and perform the following operation, an intended result might not be attained. When you perform these operations, select hosts in the right frame of the System Configuration window and perform the operation.

Even if you press the F2 key to change a host name, you cannot change the name.

When you change a host name with the Rename menu or by pressing the F2 key, another host name is changed.

After changing a host name, the selected state of the host whose name has been changed is released.

After deleting a host with the Delete menu or by pressing the Delete key, when you change the host name to the name same as another host whose host name is deleted and then display the Attributes tab or the property, the information of the deleted host is displayed.

When a management relay server is deleted, message "System error has occurred" is displayed.

When you cut a host with the Cut menu or the Ctrl + X key and display the Attributes tab or the property of the cut host, the hosts that have the same name and same information are displayed. And then, the message "Item with same name already exists" or the message that indicates an item exists that has different capitalization from the destination name in the window in the destination route is displayed.

4.4.2 Destination window

The Destination window displays the hosts defined in the System Configuration window in groups so that they can be more easily managed as job destinations. In this window, you can create and edit host groups and ID groups.

Figure 4‒4: Destination window

The left pane of the window displays the grouped destinations as a hierarchy. The right pane has the same tabs as the System Configuration window, plus the following tab:

ID-management Relay Computer tab

If an ID group is selected in the left pane, this tab lists the relay systems or management relay servers that manage the ID group.

When an ID group is selected in the left pane, the List tab shows a list of destinations that belong to that ID group. However, if you select the Double-click ID to Show Destinations option in the View menu, a single click does not show the destinations. We recommend that you use this option when there are more than 10,000 computers under an ID group and you do not need them to be readily visible.

4.4.3 Package window

The Package window displays information about the packages in cabinets. You can use this window to view and edit packages.

Figure 4‒5: Package window

The left pane of the window shows the hierarchy of cabinets and packages. The right pane contains the three tabs listed below. You can use these tabs to select which information appears in the right pane.

List tab

Lists the information (cabinets or packages) that is one level below the item selected in the left pane.

Attributes tab

Displays attribute information (such as the cabinet name, package name, package size, and compression status) of the cabinet or package selected in the left pane.

Package Contents tab

If the package type is User programs or data, this tab shows the names, sizes, and last update times of the files in the package.

4.4.4 Job Definition window

This window displays created (saved) jobs. Jobs that you create then save appear as folders in the Job Definition window. When you execute a job with an execution date and time specified, that job will be saved in the Job Definition window.

Figure 4‒6: Job Definition window

In this window, you can create a folder in which to save jobs. You can also edit and re-execute saved jobs.

4.4.5 Job Status window

The Job Status window displays job statuses. The window displays the status of executed jobs in a hierarchy consisting of folders, jobs, destinations, and packages, in that order. You can use this window to check job execution results and to re-execute jobs that ended with errors.

Figure 4‒7: Job Status window

4.4.6 List of Software Information window

This window displays a software search list.

Software search lists are lists that are used to search software programs installed on agents for UNIX or agents for Mac. Searches are conducted by checking the registration contents of the list against the contents of folders on agents for UNIX or agents for Mac, and any matched software will be reported as installed packages. Users create software search lists optionally. Software search lists can be created and edited in this window. Software search lists optionally created by users are called optional software lists.

Figure 4‒8: List of Software Information window

4.4.7 Window operations

This section describes how to work with the Remote Install Manager windows.

(1) Opening a new window

To open a new window in Remote Install Manager, from the File menu, select New. Then, choose the desired window from the menu that appears. There is no limit to the number of windows that can be open at once. You can also open more than one instance of the same type of window.

(2) Arranging windows

When displaying multiple windows in Remote Install Manager, you can arrange the windows to make Remote Install Manager easier to use. Note that you can arrange only three or four windows at one time.

To arrange the windows:

From the Options menu, select Arrangement Pattern.

The Arrangement Pattern dialog box appears.

Figure 4‒9: Arrangement Pattern dialog box

Pattern

Select the number of windows to display and the pattern in which to display them. Windows of the same type will be arranged at the same location. This means that if you display multiple windows of the same type, they will be displayed on top of each other.

Window

Select the windows to arrange in the pattern. When you select a window name in Select from and click the > button, the window name moves to the Selected window area and will be displayed in Remote Install Manager. To remove a selection, select the window name in the Selected window area and click the < button. To remove all selections, click the << button.

The sequence in the Selected window area corresponds to the numbers (1 to 4) in the patterns. In the example above, the System Configuration, Package, and Job Status windows will appear at positions 1, 2, and 3 of pattern 1, respectively. If a particular window is not being displayed when you arrange the windows, the corresponding location in the Remote Install Manager window will be empty.

Click OK.

The settings take effect, and the Arrangement Pattern dialog box closes.

From the Window menu, select Arrange Windows.

The windows are arranged in the layout you specified.

5 Creating System Configuration Information and Host Groups

This chapter describes how to create system configuration information, and how to group and manage the hosts to which jobs are distributed.

5.1 Creating system configuration information

Before you can start using JP1/IT Desktop Management 2, you need to create system configuration information, the information used to manage the configuration of relay systems, management relay servers, and managed computers. This information is called system configuration information, and defines the system configuration and the address of each host. The type of host address you set in the system configuration information (host name or IP address) is determined by the address type selected as the node identification key.

This section describes how to create and modify system configuration information, including the different ways of creating this information and how to assign host names.

5.1.1 Approaches to creating system configuration information

The following describes the ways you can create system configuration information in a JP1/IT Desktop Management 2 system, and the criteria for selecting the appropriate method for your situation.

(1) Methods of creating system configuration information

There are three ways to create system configuration information:

Creating system configuration information automatically

This method creates system configuration information automatically based on the physical configuration of the network, and applies it to the System Configuration window.

When changes are made to the system configuration, the managing server is automatically notified of the changes. Examples include the addition or removal of a managed computer or relay system, or changes to a host name or IP address. This eliminates the need to perform maintenance of system configuration information on the managing server.

By using the facility for automatically registering the system configuration, you can also update ID group memberships automatically when the system configuration changes. For details about linking system configuration information with ID groups, see 5.4 Linking system configuration information with ID group information.

Updating system configuration information by outputting it to a file

You can save system configuration information to a file. You can then restore the system configuration from the file if a problem occurs in the system.

Creating system configuration information in the System Configuration window

You can define the host name or IP address of individual managed computers and relay systems in Remote Install Manager.

Collecting system configuration information for systems under management relay servers

To manage system configuration information for the entire system from the manager in a managing server system in a hierarchical structure, you must collect system configuration information for systems under management relay servers according to the following procedure:

Create system configuration information for each management relay server.

From the manager, execute a Get system configuration information job for each management relay server.

You can use the manager to collect system configuration information for the entire system.

After collecting system configuration information for the entire system, you can use the facility for automatically registering the system configuration to maintain the system configuration information. When the system configuration under a management relay server is changed, the change details are automatically reported to the manager from the management relay server.

If one of the following methods is used on a management relay server to change the system configuration, the change details will not be automatically reported to the manager from the management relay server. In this case, execute a Get system configuration information job for the management relay server.

Creating system configuration information as a file

Creating system configuration information in the System Configuration window

Deleting system configuration information in the System Configuration window

Deleting system configuration information in the Search dialog box

If you change the connection destinations of relay systems or management relay servers in a large-scale system with three or more tiers, information about system configuration under the systems you moved might not be reported to the new managing server. If the information has not been reported, from the new managing server, execute a Get system configuration information job for the relay systems or management relay servers that you moved.

5.1.2 Assigning host names in JP1/IT Desktop Management 2

The following describes how to assign host names in JP1/IT Desktop Management 2.

(1) Assigning host names

Host names cannot be longer than 64 bytes.

The following conventions apply when assigning host names:

You can only use single-byte alphanumeric characters (A to Z and a to z), numerals (0 to 9), hyphens (-), and periods (.).

Periods (.) can only be used as a delimiter in domain names.

When using a DNS, specify host names in the format host-name.domain-name. The entire string including the domain name must not exceed 64 bytes.

The host name must begin with an alphabetic character.

You cannot use spaces.

Because host names are not case-sensitive, you cannot use a host name that is the same as another except for case.

You cannot use double-byte characters in host names.

A host name cannot end with a hyphen (-) or period (.).

You cannot use an alias defined in the hosts file as a host name.

In a system that uses host names as the node identification key, each host that uses JP1/IT Desktop Management 2 must have a unique host name.

You cannot use localhost as a host name.

The total length of all host names from the host directly under the managing server (the highest-level host in the system) to the lowest-level host cannot exceed 255 bytes. This includes the host names themselves and the delimiters between them. We also recommend that host names in networks using JP1/IT Desktop Management 2 be unified as all upper-case or lower-case letters because host names are case-sensitive in some systems, such as UNIX systems.

5.1.3 Creating system configuration information automatically

The facility for automatically registering the system configuration can automatically create system configuration information based on information reported by lower systems.

The following describes the settings required to create system configuration information automatically, and provides cautionary notes that apply to the use of this facility.

(1) TCP/IP settings required to create system configuration information automatically

If you intend to access the managing server using a host name, the managing server must be defined in the definition database of the TCP/IP protocol. On relay systems, the lower hosts must be defined in the TCP/IP definition database.

(2) Notes on automatically creating system configuration information

If you mistakenly delete the system configuration information on a higher system or the database becomes corrupted, you can restore the information from a backup or have the lower systems provide another system configuration information file.

The following notes apply when building the system and when editing system configuration information:

(a) Notes on building the system

If there is no system configuration information registered for a relay system, the system configuration information that lower systems report to that relay system might be lost. To avoid this issue, when building a system in JP1/IT Desktop Management 2, build the managing server first, followed by the relay servers, and then the agents. If the system configuration information is compiled incorrectly, execute a Get system configuration information job in JP1/IT Desktop Management 2 - Manager (manager).

(b) Notes on editing system configuration information

Do not edit system configuration information that has been automatically registered on the managing server. If you need to edit this information, output the system configuration information to a file using Remote Install Manager, back up the file, and then edit the file contents.

If you delete a relay system from the system configuration information, the system configuration information associated with the computers connected to this relay system is also deleted. From this point, system configuration information reported by those computers will not be recorded on the managing server.

For details about how to output system configuration information to a file, and how to apply the contents of a file to the system configuration information, see 5.1.4 Updating system configuration information output to a file.

5.1.4 Updating system configuration information output to a file

You can output the system configuration information created in the JP1/IT Desktop Management 2 system to a file called a system configuration information file. You can keep this file as a backup, or edit it using a text editor.

If you want to restore the system configuration from a backup or update the system configuration based on the contents of an edited file, you need to import the system configuration information file into Remote Install Manager.

The following describes how to output a system configuration information file, how to edit the file, and how to apply the contents of the file to the system configuration information.

(1) Outputting system configuration information to a file

You can output the system configuration information displayed in the System Configuration window to a file. This process allows you to modify system configuration information by outputting the existing system configuration information to a file and then editing the file contents.

If managing servers are in a hierarchical structure, the file output by the manager does not contain information about the system configuration under management relay servers. To output information about the system configuration under management relay servers, log in to the management relay servers and then output system configuration information.

To output system configuration information to a file:

In the System Configuration window, from the File menu, select Save to File.

The Save System Configuration dialog box appears. Before you perform this step, click Refresh to refresh the window contents. If the automatic application of system configuration information takes place and the information displayed on screen no longer reflects the underlying data, the correct information might not be output to the file.

Enter a file name, and then click OK.

The system configuration information is output to a file.

The following figure shows an example of system configuration information output to a file:

Figure 5‒1: File output example of system configuration information

When you output the system configuration to a file, xxx.xxx.xxx.xxx replaces the IP addresses in the file. If you want to use the output file to manage hosts by their IP addresses, you must use a text editor or similar tool to enter the IP addresses in the file.

(2) Editing system configuration information

In a system configuration information file, you can specify an IP address, host name, host type, creation date and time, comment, route, and other information for each host. Note, however, that you can specify a creation date and time only in JP1/IT Desktop Management 2 - Manager.

If the display language is Japanese, use a text file in the Shift_JIS encoding format. If the display language is Chinese (simplified characters), use a text file in the GBK encoding format. If the display language is English, use a text file in the ASCII encoding format. You can comment out a line by placing a single-quotation mark (') or hash mark (#) in the first column.

Format

IP-address host-name HID=host-ID,TYPE=host-type,MAC=MAC-address,COMMENT=comment,ROOT=route,DATE=creation-date-and-time

Description

After the IP address and host name, you can place items in any order.

IP-address (required)

Set the IP address of the host.

Although the IP address is not part of the information managed JP1/IT Desktop Management 2 - Manager, you must specify this operand to keep the file format consistent with the TCP/IP hosts file.

You can also use the TCP/IP hosts file directly as a system configuration information file. In this case, all hosts in the file are registered as managed computers.

You can simplify the process of creating a system configuration information file by using the TCP/IP hosts file as the basis and adding the host type (TYPE), comment (COMMENT), and route (ROOT) information for the hosts.

host-name (required)

For details about how to specify host names, see 5.1.2 Assigning host names in JP1/IT Desktop Management 2.

HID=host-ID

Set a host ID that uniquely identifies the host. You must use the host ID as it appears in the file output when you select Save to File from the File menu in the System Configuration window. Do not specify this operand if no host ID is set for the host in the output file, or the host is a new host.

TYPE=host-type

As the host type, enter MANAGER (management relay server), MASTER (relay system), or CLIENT (agent). If you omit this operand, CLIENT is set by default.

If you intend to use the file as both a TCP/IP hosts file and a system configuration information file, specify a hash mark (#) before TYPE, leaving a single-byte space between # and TYPE. The TCP/IP protocol will interpret the information after the hash mark as a comment.

MAC=MAC-address

Set the MAC address of the host. Because MAC address information is used by functions such as Wake on LAN, you should not change the value of this operand as a general rule. If you change the value, some functions might not work.

COMMENT=comment

Set a comment. The comment cannot contain commas (,). You can enter a maximum of 64 single-byte characters.

ROOT=route

When a host is configured below multiple relay servers, set the full path from the highest to lowest relay system using host names, IP addresses, or host IDs. When a host is configured below two or more relay systems and management relay servers, separate them with a backslash (\) or exclamation mark (!). You can omit this operand if the host connects directly to JP1/IT Desktop Management 2 - Manager.

DATE=creation-date-and-time

The date and time when the host will be (or was) first registered on the management server. Specify the date and time in the format MM/DD/YYYY/hh/mm/ss. For YYYY, you can specify a value in the range from 1971 to 2037. For hh, you can specify 0 to 23.

If you omit this operand, the date and time at which you clicked Create from File is set for this parameter in the system configuration information file.

(3) Using a system configuration information file to update system configuration information

To apply the contents of a system configuration information file to the system configuration information:

In the System Configuration window, from the File menu, select Create from File.

A dialog box appears in which you can select a file.

Select the system configuration information file you created, and then click OK.

The system configuration information is updated based on the contents of the system configuration information file.

Note the following when applying the contents of a system configuration information file to the system configuration information:

If you have already created system configuration information, the contents of the System Configuration window is replaced with the information set in the file. Hosts for which there is no information in the file are removed from the existing system configuration information.

The existing contents of the Destination window are deleted, with the exception of ID group information.

If host IDs were originally assigned in the System Configuration window, you must continue to use the same host IDs.

If the facility for automatically registering the system configuration starts operating while the system configuration information is being updated, an illegal root error might occur. In this case, wait a while and then try again.

5.1.5 Creating system configuration information in the System Configuration window

To define a host in the System Configuration window:

Make the System Configuration window the active window, and click the position in the hierarchy where you want to create a host.

You can now create a host under the selected hierarchical level.

From the File menu, select Create Host.

The Create Host dialog box appears.

Figure 5‒2: Create Host dialog box

Specify the host

Specify a host name or IP address.

For details about how to specify host names, see 5.1.2 Assigning host names in JP1/IT Desktop Management 2.

Type

Select Management relay server, Relay system, or Agent as the host type. If you do not select an option, Agent is set by default.

Comment

Enter a comment using a maximum of 64 single-byte characters.

After entering the settings, click Exit.

The host is defined. You can add further hosts by clicking Add.

5.1.6 Collecting system configuration information of the systems under management relay servers

When managing server systems in a hierarchical structure, you cannot use the manager to create or change system configuration information of the systems under the management relay servers. In this case, execute a Get system configuration information job to collect the system configuration information managed by the management relay servers, and add it to the system configuration information for the manager. You can also use the facility for automatically registering the system configuration to collect the information, but to do so you must complete the setup for the higher systems before the setup for the lower systems. Therefore, if you cannot take the setup sequence into account in situations such as during installation or when significantly changing system configuration information, execute a Get system configuration information job to collect the system configuration information.

After collecting system configuration information for the systems under the manager, you can maintain that information by using the facility for automatically registering the system configuration. When information about the system configurations of the systems under a management relay server is changed, the change details are automatically reported from the management relay server and reflected in the system configuration information for the manager.

If you change the connection destinations of relay systems or management relay servers in a large-scale system with three or more tiers, information about the system configurations of the systems under the systems you moved might not be reported to the new managing server. If the information has not been reported, from the managing server, execute a Get system configuration information job on the relay system or management relay server that you moved.

(1) Executing a Get system configuration information job

(a) Creating and executing a job

This subsection explains how to create a job for collecting system configuration information. For operation and setting details, see 10.2 Creating a job.

In the Destination or System Configuration window, select Execute and then Execute Job. Alternatively, in the Job Definition window, select File and then Create Job.

The Define New Job dialog box appears.

In the Define New Job dialog box, select the desired job type (Get system configuration information), and then click the OK button.

The Create Job dialog box appears.

Set the items on each panel.

The types and settings of the panels displayed in the Create Job dialog box are as follows:

Job panel

Specifies the job name.

Destination panel

Specifies the management relay server from which system configuration information is to be collected. Specify the management relay server or its destination group.

Schedule panel

Specifies the registration date/time, execution date/time, and execution time limit of the job.

Click the Execute, Save, or Save and Execute button.

The job is saved or executed.

(b) Checking the execution results

When a job is executed, information about the system configurations of the systems under the management relay server is reflected in the System Configuration window for the manager.

Figure 5‒3: System Configuration window

(c) Notes on job execution

When a Get system configuration information job is executed, not only system configuration information but also information about destination groups under management relay servers is reflected in the Destination window for the manager. However, information about ID groups under management relay servers is not reflected in the Destination window for the manager even if operations are performed to link system configuration information and ID groups.

The system configuration information collected by a Get system configuration information job is only applied to the system where the job was executed. For example, suppose that a hierarchical system is configured with three tiers, that is, a primary management server, management relay servers, and relay systems. If a Get system configuration information job is executed from the primary management server for relay systems, the system configuration information for the primary management server is updated, but the information for management relay servers is not. If you also want to update system configuration information for management relay servers, execute the Get system configuration information job on a management relay server.

Suppose that the Get system configuration information job is executed for relay systems and management relay servers for which system configuration information is not registered. In this case, the system configuration information retained in the system where the job was executed is deleted according to the newly collected system configuration information.

(2) Setting up the facility for automatically registering the system configuration

If the following settings are specified on the manager, the system configuration information managed by management relay servers is automatically reported to the manager and reflected in the system configuration information for the manager.

Settings

Select the Automatically apply system configuration information check box in the System Configuration panel of the Setup for Distribution That Uses Remote Install Manager window. By default, the check box is selected. Clear the check box first, and then select the check box again after using the manager to collect information about the system configurations for the systems under management relay servers.

Important

If the facility for automatically registering the system configuration is set up beforehand, not only system configuration information but also information about destination groups under management relay servers is reflected in the Destination window for the manager. However, information about ID groups under management relay servers is not reflected in the Destination window for the manager. To reflect information about ID groups as well, you must link system configuration information with ID group information. For details about how to do this, see 5.4 Linking system configuration information with ID group information.

5.1.7 Modifying system configuration information

When you add or remove a relay system or managed computer, the facility for automatically registering the system configuration automatically notifies the managing server, and the information in the System Configuration window is updated accordingly. This subsection describes how to modify system configuration information manually from the managing server.

To change the host names (or IP addresses if IP addresses are the ID key for operations) of managing servers, relay systems, or management relay servers, you must have all jobs completed or deleted beforehand.

(1) Changing system configuration information from a file

This process involves outputting the existing system configuration information to a file, updating the file contents, and then creating system configuration information based on the updated file.

Even when changing only some aspects of the system configuration, the file from which you create the system configuration must contain information for every host that you want to remain in the system. Any host that is not in the file will be deleted from the system configuration.

To delete a host, delete the information associated with that host from the file.

For details about how to output system configuration information to a file, and how to create system configuration information from a file, see 5.1.4 Updating system configuration information output to a file.

(2) Changing the system configuration in the System Configuration window

The following describes how to change system configuration information from the System Configuration window. For details about how to search for the hosts you want to change or delete, see 6.1.1 Searching for hosts by name.

(a) Moving hosts

When you move a management relay server or relay system, all its subordinate hosts also move with it. You can move multiple hosts at once by selecting them in the right pane of the System Configuration window.

You can move a host by using Remote Install Manager on the management relay server that directly manages it.

To move a host or hosts:

Make the System Configuration window the active window, and select the host or hosts you want to move.

The hosts you select are highlighted in the System Configuration window.

From the Edit menu, select Cut.

The selected hosts are cut. After clicking Cut, do not double-click the Network node in the left pane. If you double-click this node, the Paste command becomes unavailable in the Edit menu, and you will be unable to paste the hosts. In this case, click Cut again.

Select the destination for the hosts.

The location you selected is highlighted in the System Configuration window.

From the Edit menu, select Paste.

The hosts you cut are pasted to the selected destination.

Note that you can also move hosts by dragging them to the desired location.

(b) Deleting hosts

You cannot restore a host after deleting it. When you delete a management relay server or relay system, all its subordinate managed computers are also deleted. You can delete multiple hosts by selecting them in the right pane of the System Configuration window.

When you delete a host in the System Configuration window, the Delete Host dialog box appears. If you select the Delete a host from the registered IDs check box in the Delete Host dialog box, the selected host is also deleted from the ID groups in which it is registered. This check box is only available when the selected host is an agent. If the selected host is a management relay server or relay system, you cannot delete it. In this case, use the System Configuration window to delete the agent on the same computer as the management relay server or relay system and its subordinate agents before deleting the management relay server or relay system itself.

To delete hosts:

Make the System Configuration window the active window, and select the host or hosts you want to delete.

The hosts you select are highlighted in the System Configuration window.

From the Edit menu, select Delete.

A confirmation dialog box appears.

Click OK.

The selected hosts are deleted.

You can also delete hosts by searching for them in the Find dialog box. For details, see 6.1.4 Deleting found hosts from system configuration information.

(c) Changing host names

When you change a host name, the changes are automatically reported to the managing server. The information that has been reported is automatically reflected in the System Configuration window. The host name that was specified can be changed in the System Configuration window. To change the host name, use the management relay server that manages the host.

To change a host name in the System Configuration window:

In the System Configuration window, select the host whose host name is to be changed.

The selected host is highlighted.

Select File and then Rename.

Specify a name, and press Enter.

The name will be changed to the specified name.

Changing the host name in the System Configuration window also changes the same host name in the Destination window.

(d) Changing host attributes

To change host attributes from a relay system to an agent (or from an agent to a relay system) or modify routes or comments, use the Change Attributes dialog box, which is displayed by selecting File and then Change Attributes.

Note the following when changing host types:

Changing the attributes of a host in the System Configuration window also changes the attributes of the same host in the Destination window.

You cannot change the host types of management relay servers. For management relay servers, you can change only IP addresses and comments.

Figure 5‒4: Change Attributes dialog box

Host name

Displays the host name. You can change the host name if IP addresses are the ID key.

IP address

Displays the IP address. You can change the IP address if host names are the ID key.

Type

Select Relay system or Agent as the host type. If you change the host type from Relay system to Agent, all the current hosts under the relay system will be deleted.

Route

Specify a route by separating each host name with an exclamation mark (!). If a non-existent route is specified, the route will not be changed and an error will be returned.

Browse button

Clicking this button displays the Set Path dialog box where you can select a route from the system configuration.

Comment

You can enter a comment of up to 64 single-byte characters.

(3) Changing system configuration information under management relay servers

From the local server, you cannot change information about system configuration under management relay servers. If information about system configuration under management relay servers has been changed, add the changed information to the system configuration information on the local server. To do this, use the facility for automatically registering the system configuration or execute a Get system configuration information job from the local server.

However, you can use the System Configuration window on the local server to change comments about hosts under management relay servers.

If you change the connection destinations of management relay servers or relay systems in a large-scale system with three or more tiers, information about system configuration under the systems you moved might not be reported to the new managing server. If the information has not been reported, from the new managing server, execute a Get system configuration information job for the management relay servers or relay systems that you moved.

(4) Notes on changing system configuration information

The following are notes on changing system configuration information:

Changing node identification keys

Before changing a node identification key, delete system configuration information from Remote Install Manager. It is convenient to output system configuration information to a file beforehand. This enables you to set up system configuration information by using the file (that was output) after changing the node identification key.

If system configuration information is created manually, the system configuration information file that is output contains the address of each host that is specified according to the node identification key in use. Therefore, the file that is output must contain either the host name or IP address of each host. For example, if a node identification key is to be changed from host names to IP addresses, no IP address is specified in the file that is output before the node identification key is changed. In this case, create system configuration information by specifying IP addresses in a text editor such as Notepad or by reading the hosts file.

Changing host names

When you change the host name of a management server, change the host name of the connection destination on the lower system connected to that host. You can make this change during setup if the lower system is a management relay server or in the agent configurations if the lower system is a relay system or agent.

When you change the host name of a relay system, on the management server that manages that relay system, change the name of the relay system defined in the agent configurations.

If the node identification key is specified as host names, change the host name and then restart the computer.

5.1.8 Notes on creating system configuration information

Note the following when creating system configuration information:

JP1/IT Desktop Management 2 supports a maximum of seven tiers in the system configuration.

When you create a relay system in the system configuration, there must be an agent with the same name as the relay system under the relay system, whose address is specified using the ID key (host name or IP address). Do not move this agent to another route.

5.2 Creating host groups

In the Destination window, you can use host groups to manage the hosts defined in the System Configuration window.

This section describes how to create host groups.

5.2.1 Method of creating host groups

You can use the methods below to create host groups. Use the method that is appropriate for the characteristics of the host group you are creating.

Create host groups using system configuration information

This method involves outputting system configuration information to a text file, editing the file to create host groups, and then importing the file in the Destination window. This method is useful when you want to create host groups that reflect the physical network configuration.

For details, see 5.2.3 Creating host groups from a file.

Create host groups using on-screen operations in the Destination window

This method involves creating host groups directly in the Destination window. This method is useful when you want to create host groups that are not tied to the network configuration, or change the parameters of an existing host group.

For details, see 5.2.4 Creating host groups in the Destination window.

Creating host groups automatically according to preset conditions (policies)

In this method, new or moved hosts are assigned automatically to host groups based on preset grouping conditions (policies). For details, see 6.2 Automatic maintenance of destination group.

5.2.2 Assigning group names

You can specify names for host groups and ID groups using a maximum of 32 bytes. However, the following restrictions apply:

You cannot use the following single-byte characters.

Exclamation marks (!), double quotation marks ("), percent signs (%), apostrophes ('), asterisks (*), periods (.), forward slashes (/), colons (:), left angle brackets (<), right angle brackets (>), question marks (?), at marks (@), backslashes (\), and vertical bars (|).

The name cannot contain spaces.

Because host names are not case-sensitive, you cannot use a name that is the same as another except for case.

You can create a maximum of seven tiers of host groups. The group names you specify must be such that the total length from the top group to the bottom group plus the host name does not exceed 255 bytes. This includes the delimiters between group names and the delimiter before the host name.

5.2.3 Creating host groups from a file

You can create host groups by first creating a host group file that defines the host groups you want to create.

(1) Creating a host group file

For a given destination, a host group file defines information including the destination name, destination type, and the path of the host group to which it belongs. If the display language is Japanese, use a text file in the Shift_JIS encoding format to perform I/O operations. If the display language is Chinese (simplified characters), use a text file in the GBK encoding format to perform I/O operations. If the display language is English, use a text file in the ASCII encoding format to perform I/O operations. You can comment out a line by placing a single-quotation mark (') or hash mark (#) in the first column.

You can streamline the process of creating a host group file by outputting the system configuration information to a text file and then editing the file. For an example of creating a host file, see 5.2.6 Example of host group creation.

Format

destination-name HID=host-ID,TYPE=destination-type,MAC=MAC-address,ROOT=path-of-host-group,DATE=creation-date-and-time

Description

You can place items in any order after the destination name and host ID.

destination-name (required)

Set the name of the host group or host.

If destination-name is a host group, specify it in the format * host-group-name. The initial character is a single-byte asterisk (*). Separate the asterisk and the host group name with a single-byte space. The host group name must be unique. For details about how to name host groups, see 5.2.2 Assigning group names.

If destination-name is a host, specify it according to the node identification key used in the system.

If you are using host names as the node identification key, specify the destination name in the format * host-name. The initial character is a single-byte asterisk (*), and the asterisk is separated from the host name by a single-byte space. You can specify another character or character string (except a space) in place of the asterisk. For example, you can replace the asterisk with an IP address.

If you are using IP addresses as the node identification key, specify the destination name in the format IP-address *. The IP address is separated from the asterisk by a single-byte space. You can specify another character or character string in place of the asterisk. For example, you can replace the asterisk with a host name. You can also omit the asterisk altogether.

When you create a host group file on the manager, you can only specify hosts registered in the system configuration information as destination names.

HID=host-ID

Set a host ID that uniquely identifies the host. If host IDs are set in the file output by selecting Save to File from the File menu in the Destination window, you must use the host IDs exactly as they appear in the file. Do not specify this operand for hosts for which no host ID is set in the host group file output by Save to File, or for newly added hosts.

TYPE=destination-type

Specify the host type as one of the following. If you omit this operand, CLIENT is set by default.

GROUP (host group)

MANAGER (management relay server)

MASTER (relay system)

CLIENT (agent)

MAC=MAC-address

Set the MAC address of the host. Because MAC address information is used by functions such as Wake on LAN, you should not modify this operand as a general rule. If you modify this operand, some functions might not work.

ROOT=path-of-host-group

Set the full path of the host group to which the host belongs. If you do not specify a value for this operand, the destination is created with the host group of the preceding entry and the value of the TYPE operand as the type.

DATE=creation-date-and-time

The date and time when the host will be (or was) first registered on the management server. Specify the date and time in the format MM/DD/YYYY/hh/mm/ss. For YYYY, you can specify a value in the range from 1971 to 2037. For hh, you can specify 0 to 23.

If you omit this operand, the date and time at which you clicked Create from File is set for the destination.

(2) Creating host groups from a file

When you create host groups from a host group file, the information in the Destination window is replaced with the contents of the host group file. You can save the existing contents of the Destination window by backing it up to a file.

If the existing information in the Destination window includes host IDs, you must use the host IDs as they appear in the window.

To create host groups from a file:

In the Destination window, from the File menu, select Create from File.

Select the host group file you created, and then click OK.

(3) Outputting host groups to a file

You can output the host group configuration displayed in the Destination window to a file. You can use this process to modify host configuration information by outputting the existing host groups to a file and then editing the file contents.

To output the host group configuration to a file:

In the Destination window, from the File menu, select Save to File.

The Save Destination dialog box appears. Before you perform this step, click Refresh to refresh the window contents. If automatic application of system configuration information occurs and the information displayed on screen conflicts with the underlying data, the correct information might not be output to the file.

Enter a file name, and then click OK.

The host group configuration is output to a file.

The following figure shows an example of the host group configuration output to a file:

Figure 5‒5: File output example of host group configuration

5.2.4 Creating host groups in the Destination window

After creating host groups, you can register hosts (relay systems and agents) in those groups.

(1) Procedure for creating host groups

The procedure for creating a host group is shown below. Although you can create host groups under other host groups, you cannot give a host group the same name as a host group that is above it in the hierarchy. You can create a maximum of seven tiers of host groups.

Make the Destination window the active window, and click the position in the hierarchy where you want to create a host group.

You can now create a host group under the selected hierarchical level.

From the File menu, select Create Host Group.

The Create Host Group dialog box appears.

Figure 5‒6: Create Host Group dialog box

Select Create a host group, and enter the name of the host group you want to create. The name must be unique. For details about how to name host groups, see 5.2.2 Assigning group names.

After entering the relevant settings, click Execute.

The host group is created. To exit the Create Host Group dialog box without creating a host group, click Exit.

(2) Registering hosts

The following describes how to register hosts in the host groups you created. You cannot select a host in the Destination window that does not appear in the System Configuration window.

Make the Destination window the active window, and click the position in the hierarchy where you want to place a host.

You can now place a host under the selected hierarchical level.

From the File menu, select Create Destination (or click the Create Host button).

The Create Destination dialog box appears.

Figure 5‒7: Create Destination dialog box

Host group belongs to

Displays the name of the host group in which the host will be registered.

Host name or IP address

Specify the host name or IP address of the host you want to register in the host group.

If there is more than one host with the specified name in the system configuration when you click Add, the Select Destination dialog box appears. Specify which type of host you want to add.

Figure 5‒8: Select Destination dialog box

After entering the relevant settings, click Exit.

The settings are saved and the Create Destination dialog box closes.

You can add another host by clicking the Add button again.

You can also register a host in the System Configuration window by dragging its icon to the icon of a host group.

5.2.5 Modifying host groups

This section describes how to modify a host group.

If you want to add a host group or host to the existing information, see 5.2.5(1) Adding hosts and host groups from a file. If you want to initialize the existing information and register host and host groups again, see 5.2.5(2) Modifying hosts and host groups from a file.

(1) Adding hosts and host groups from a file

You can use the Remote Install Manager component of JP1/IT Desktop Management 2 - Manager to add host groups and hosts from a file.

To add host groups or hosts from a file:

Create a host group file that defines only the host groups and hosts that you want to add.

For details about how to create a host group file, see 5.2.3(1) Creating a host group file.

In the Destination window, from the File menu, select Add from File.

The Add Destination dialog box appears.

Select the host group file you created in step 1, and then click Open.

The system begins the process of registering the host groups and hosts.

(2) Modifying hosts and host groups from a file

This process involves outputting the host group configuration to a file, updating the file contents, and then creating host groups based on the updated file.

For details about how to save the host group configuration to a file, and how to create host groups from a saved file, see 5.2.3 Creating host groups from a file.

(3) Modifying hosts and host groups from the Destination window

The following describes how to modify host groups from the Destination window. For details about how to search for the host groups or hosts you want to modify, see 6.1.1 Searching for hosts by name.

(a) Renaming a host group

The following describes how to rename a host group. You cannot change the destination name of a host in the Destination window.

In the Destination window, select the host group you want to rename.

The host group you selected is highlighted in the window.

From the File menu, select Rename.

Enter the new name, and press Enter.

The name will be changed to the specified name.

(b) Editing (deleting, copying, or moving) a host group or host

To edit (delete, copy, or move) a host group or host, make the Destination window the active window, and select the host group or host that you want to edit. Then, select Delete, Copy, Cut, or Paste from the Edit menu.

You can also edit host groups and hosts by dragging them in the user interface.

Notes:

Do not double-click the Network node in the left pane after clicking Copy or Cut.

If you double-click this node, the Paste command becomes unavailable in the Edit menu, and you will be unable to paste the host group or host. In this case, click Copy or Cut again.

When displaying multiple instances of the Destination window, you cannot copy a host group or host in one window and paste it into another.

(c) Notes on editing destinations

If a communication error or other problem occurs while you are editing (deleting, copying, or moving) a host group or host in the Destination window, you might be unable to restore it to its previous state. For this reason, we recommend that you save the host group configuration to a file before editing a large number of host groups or hosts.

For details about how to save the host group configuration to a file, and how to create host groups from a saved file, see 5.2.3 Creating host groups from a file.

5.2.6 Example of host group creation

The following shows an example of creating system configuration information and host groups.

Structure of system configuration information and host groups

For a system with the configuration below, JP1/IT Desktop Management 2 creates the system configuration information automatically. The host groups are created by editing the system configuration information file.

Figure 5‒9: Structure of system configuration and host groups

System configuration information file

The figure below shows the result of outputting the automatically created system configuration information to a file.

Figure 5‒10: System configuration information file

Host group file

The figure below shows the host group file created by editing the system configuration information file. To output the system configuration information from the System Configuration window, open the File menu and select Save to File.

Figure 5‒11: Host group file

5.3 Creating ID groups

Like host groups, you can create ID groups in the Destination window of Remote Install Manager. Although ID groups are created on a managing server, the created ID groups are reported to and managed by a relay system or management relay server responsible for managing the ID group (called the ID-management relay computer). This ID-management relay computer also manages the registration status of users in the ID group.

This section provides an overview of the use of ID groups. It then describes in detail how to create ID groups and register managed computers in those groups.

5.3.1 Using ID groups

The following figure shows an example of using ID groups in a JP1/IT Desktop Management 2 system:

Figure 5‒12: Example of using ID groups

The following describes the procedures associated with ID groups, how to use ID groups in a hierarchical system, and how to use ID groups in a relay system or management relay server.

(1) Procedures associated with ID groups

(a) Creating ID groups

You can create an ID group by specifying the following information on the managing server:

ID group name

The name you specify is used to select the ID group as a destination during job distribution.

Password (optional)

You can specify a password that the user must provide when registering a managed computer in the ID group. Users cannot register their computers in the ID group without entering the correct password.

ID-management relay computer

Specify a host (relay system or management relay server) to be used as an ID-management relay computer. You can specify multiple relay computers for a single ID group.

(b) Registering managed computers in ID groups

Use the Register ID dialog box on a managed computer to register a managed computer in an ID group. To do this, connect to the ID-management relay computer from the managed computer and then register the computer in the ID group managed by the ID-management relay computer. You can also register computers in ID groups from the managing server. There is also a process by which computers newly added to the JP1/IT Desktop Management 2 system are automatically registered in ID groups.

The ID-management relay computer for a managed computer is the higher system that is displayed on the Connection-destination settings panel when the agent is set up. For JP1/IT Desktop Management 2 - Manager, the ID-management relay computer for a managed computer is the higher system that is specified when the management relay server is set up.

(c) Executing jobs on the managing server with ID groups specified as the destination

You can execute the following jobs with an ID group specified as the destination:

Install package job#

Send package, allow client users to choose job

Get system information from computer (UNIX) job#

Get software information from computer (UNIX) job#

#

This job is also applicable to agents for Mac.

A job for which an ID group is specified as the destination (ID group job) is transferred to the ID-management relay computers managing the specified ID group. The ID-management relay computer stores the job and executes it on each computer registered in the specified ID group. If you register a computer in an ID group after executing an ID group job that specifies that ID group as a destination, the stored job is executed on the computer as soon as it joins the ID group. Therefore, you must consider the retention period of the distributed packages on the relay system when executing a job with an ID group specified as the destination. Because packages are deleted from the relay system when the retention period of the job expires, the packages will no longer be distributed to computers that join the ID group after that point.

(d) Execution results of ID group jobs

When you execute the following jobs with an ID group as the destination, you can check the results of job execution at the managed computer from the managing server. For details about how to check the execution results of ID group jobs, see 10.4.4 Displaying the job status.

Install package job

Send package, allow client users to choose job

(e) Editing ID groups

After creating an ID group, you can edit it in the following ways on the managing server:

Add or delete an ID-management relay computer

Change the password

Delete the ID group

Register managed computers in the ID group (from a file)

Register an ID group in an ID-management relay computer

Note:

Do not edit the same ID at the same time.

(2) Using ID groups in a hierarchical system

The following describes the considerations that apply when using ID groups in a system that incorporates multiple managing servers in a hierarchy.

(a) Creating ID groups on a management server

When you create an ID group on a management server, you can set subordinate relay systems or management relay servers as the ID-management Relay Computer.

For details about how to set a relay system or management relay server as the ID-management relay computer, see 5.3.2 Creating ID groups.

(b) Managing ID groups on management relay servers

On a management relay server, the Destination window displays the ID group specified as an ID-management relay computer by the higher management server, as well as the ID group created on the management relay server.

On a management relay server, you can perform the following operations on an ID group created by a higher management server:

Deleting ID groups

Deleting computers registered in ID groups

(c) Managing the same ID group for multiple managing servers

As shown in the following figure, you can create a single ID group for multiple management servers.

Figure 5‒13: Managing the same ID group for multiple managing servers

On both the primary management server (Man00) and the management relay server (Man01), an ID group called Windows7 can be created by using the relay system (Sub00) as an ID-management relay computer.

However, Man00 cannot create an ID group called Windows7 by using Man01 as an ID-management relay computer. Because another ID group of the same name was created on Man01, that server cannot become an ID-management relay computer for Man00 with the same ID as the ID created on the local system.

If you delete an ID group or change an ID-management relay computer, the change details will be reported from the changed system and automatically reflected in the information held by its higher system.

The following figure shows an example of deleting the ID groups managed by multiple managing servers.

Figure 5‒14: Deleting the ID groups managed by multiple managing servers

5.3.2 Creating ID groups

To create an ID group:

In the Destination window, from the File menu, select Create ID Group.

The Create ID Group dialog box appears.

Figure 5‒15: Create ID Group dialog box

ID group name

Set the name of the ID group. For details about the conventions for ID group names, see 5.2.2 Assigning group names.

Password

Set the password a user must enter to register a managed computer in the ID group, using no more than 14 single-byte alphanumeric characters. You do not need to specify a password. If you enter a password, it is displayed as asterisks (*) in the window.

Specify ID-management Relay Computer

Specify an ID-management relay computer. You can specify multiple hosts as the ID-management relay computers.

The System configuration area displays the relay systems and management relay servers that are some of the hosts displayed in the System Configuration window. To add a host as an ID-management relay computer, select it in the System configuration area and then click the > button. You can select multiple hosts in the System Configuration area.

By clicking the ALL> button, you can set all relay systems and management relay servers as ID-management relay computers at the same time.

After entering the appropriate settings, click Add.

The ID group is created.

When you attempt to add an ID-management relay computer, the process might fail with an ID group remaining in now being registered status. If this occurs, remove the cause of the problem and then try again.

You can forcibly delete an ID-management relay computer that is in now being registered status by clicking Delete ID Group.

Click Exit.

The Create ID Group dialog box closes.

You can check the ID group you defined in the Destination window. To display the relay systems or management relay servers managing a particular ID group, click the ID-management Relay Computer tab in the right pane of the Destination window.

Figure 5‒16: ID-management Relay Computer tab in Destination window

5.3.3 Registering managed computers in ID groups

There are three ways to register managed computers in ID groups:

Register a managed computer in an ID group from the computer itself

Using a file to register managed computers in ID groups from the managing server

Register managed computers in ID groups as part of automatic ID group maintenance

(1) Registering managed computers in ID groups directly

You can register a managed computer in an ID group in the Register in ID Group dialog box that is displayed when you select Register in ID Group from the Windows Start menu.

Registration in an ID group takes place with a managed computer connected to an ID-management relay computer. However, you can put registration in an ID group or deregistration from an ID group on hold without a managed computer connected to an ID-management relay computer. In this case, actual registration or deregistration is reported to the ID-management relay computer when you log on or select Register in ID Group after the managed computer is ready to connect to the ID-management relay computer. This allows you to register managed computers in ID groups during the pre-installation and system building stages. Also, while a managed computer is performing processing such as remote installation, it is connected to its higher system by using a different function from an ID-management relay computer. In this case, the system assumes that the managed computer is not connected to an ID-management relay computer.

For details about how to register a managed computer in an ID group from the computer itself, see 12.2.1 Registering a managed computer in an ID group.

(2) Using a file to register managed computers in ID groups from the managing server

On the managing server, you can register managed computers in ID groups based on the contents of a file. This approach is useful in situations where you need to register a large number of computers in ID groups, such as when first building the system. The file, called an ID group file, contains the information required to register multiple computers in ID groups. The following describes how to use a file to register managed computers in ID groups.

(a) Creating an ID group file

An ID group file specifies settings (such as a host name, host ID, ID group name, and the name of an ID-management relay computer) for each host.

If the display language is Japanese, use a text file in the Shift_JIS encoding format to perform I/O operations. If the display language is Chinese (simplified characters), use a text file in the GBK encoding format to perform I/O operations. If the display language is English, use a text file in the ASCII encoding format to perform I/O operations.

You can comment out a line by placing a single-quotation mark or hash mark (#) in the first column.

Format

host-name HID=host-ID,MAC=MAC-address,ID=ID-group-name,MASTER=name-of-ID-management-Relay-Computer

Description

host-name (required)

Specify the host name or IP address of the host to add to the ID group. Host names must be 64 bytes or less.

HID=host-ID

Set a host ID that uniquely identifies the host. You must use the host ID as it appears in the file output when you select Save ID Hosts to File from the File menu. Do not specify this operand if no host ID is set for the host in the file output when you click Save ID Hosts to File, or the host is a new host.

MAC=MAC-address

Set the MAC address of the host. Because MAC address information is used by functions such as Wake on LAN, you should not change the value of this operand as a general rule. If you change the value, some functions might not work.

ID=ID-group-name (required)

Specify the ID group name of the ID group to which you want to add the host. The ID group name cannot be longer than 32 bytes.

MASTER=name-of-ID-management-Relay-Computer

Specify the host ID of the relay system or management relay server that contains the ID group to which you are adding the host. For management relay servers, specify a host name or host ID. You must use the host ID as it appears in the file output when you select Save ID Hosts to File from the File menu.

Host IDs must be 64 bytes or less. If you omit this parameter on a managing server, the managed computer will be registered in the ID group managed by the managing server.

(b) Using a file to register managed computers in ID groups

To register managed computers in ID groups from a file, in the Destination window, select File and then Use File for ID Registration. Then, select the ID group file you created for this purpose.

(c) Outputting ID groups to a file

You can output information about the ID groups defined on the managing server and the hosts registered in those ID groups to a file. To do so, from the File menu in the Destination window, select Save ID Hosts to File. Before you perform this step, click Refresh to refresh the window contents. If the automatic application of system configuration information takes place and the information displayed on screen conflicts with the underlying data, the correct information might not be output to the file.

The following figure shows an example of ID group information output to a file:

Figure 5‒17: File output example of ID group information

(3) Registering managed computers in ID groups as part of automatic ID group maintenance

You can use the automatic ID group maintenance process to automatically register managed computers in ID groups when they meet certain criteria.

For details about how to register managed computers in ID groups by using the automatic ID group maintenance function, see 6.3 Automatic ID group maintenance.

5.3.4 Editing ID groups

After creating an ID group, you can edit it in the following ways on the managing server:

Change the ID-management relay computer

Change the password

Delete the ID group

Register managed computers in the ID group

Remove computers from an ID group

Register the ID group in an ID-management relay computer

Note:

Do not edit the same ID at the same time.

(1) Changing passwords and ID-management relay computer

You can change the ID-management relay computers of the ID groups that was created on the local server, and the password required to register a computer in the ID groups. To change the attributes of the ID group:

In the Destination window, from the File menu, select Change ID Group Attribute.

The Change ID Group Attribute dialog box appears.

Specify a new list of ID-management relay computers and a new password.

Add or delete ID-management relay computers or specify a new password.

After changing the list of ID-management relay computers or a password, click the OK button.

The list of ID-management relay computers and the password are changed.

The system might take some time to process the change. If the new information does not appear in the Destination window, wait a while, and then from the Window menu, select Refresh to display the latest information.

(2) Deleting ID groups

To delete an ID group:

In the Destination window, select the ID group that you want to delete, and from the File menu, select Delete ID Group.

A confirmation dialog box appears.

Click OK.

The selected ID group is deleted. The deleted ID group remains in the Destination window in Now being deleted status. After the deletion process is complete, the ID group disappears from the window when you select Refresh from the Window menu.

(3) Removing computers from ID groups

To remove a computer from an ID group;

In the Destination window, select the computer you want to remove, and from the Edit menu, select Delete.

A confirmation dialog box appears.

Click OK.

The selected computer is removed. In a hierarchical system, the deletion process might take some time.

The removed computer remains in the Destination window in Now being deleted status. After the process of removing the computer from the ID group is complete, the computer disappears from the window when you select Refresh from the Window menu.

(4) Registering ID groups in ID-management relay computers

On the managing server where you created an ID group, you can register the group in an ID-management relay computer. You can register multiple ID groups in an ID-management relay computer at the same time, which is useful when you added a new ID-management relay computer to the system.

For details about how to register ID-management relay computers in ID groups, see 5.3.4(1) Changing passwords and ID-management relay computer.

(a) Registering ID groups in ID-management relay computers

To register an ID group in an ID-management relay computer:

In the System Configuration window, from the File menu, select Register/Delete ID Group on ID-management Relay Computer.

The Register/Delete ID Group on ID-management Relay Computer dialog box appears.

Figure 5‒18: Register/Delete ID Group on ID-management Relay Computer dialog box

In the Unregistered ID groups area, select an ID group you want to register and then click the > button.

The ID group is added to the Registered ID groups area.

Click OK.

The ID group is registered on the ID-management relay computer.

(b) Removing ID groups from ID-management relay computers

To remove an ID group registered on an ID-management relay computer:

In the System Configuration window, from the File menu, select Register/Delete ID Group on ID-management Relay Computer.

The Register/Delete ID Group on ID-management Relay Computer dialog box appears.

Select the ID group you want to remove in the Registered ID groups area, and then click the < button.

The ID group is removed from the Registered ID groups area.

Click OK.

The ID group is removed from the ID-management relay computer.

5.3.5 Notes on using ID groups

Note the following when using ID groups:

(1) When system configuration information is removed for a computer registered in ID groups

If you delete a computer from the system configuration information that is registered in one or more ID groups, information about its ID group memberships is not automatically deleted. Before deleting the system configuration information associated with a managed computer, de-register the computer from its ID groups.

If you deleted a managed computer from the system configuration information without de-registering it from its ID groups, you can remove the ID group information from Remote Install Manager. For details about how to remove a managed computer from an ID group, see 5.3.4 Editing ID groups.

You can also configure the system to automatically link system configuration information and ID group information. For details, see 5.4 Linking system configuration information with ID group information.

(2) If an Edit ID group folder was created

If the Edit ID group folder has been created in the Job Status window, do not delete the folder or its contents.

The Edit ID group folder contains jobs that register managed computers in ID groups and add ID-management relay computers. The system creates these jobs automatically, and deletes them automatically when the job has ended.

If you inadvertently delete a job that edits ID groups, ID groups will no longer be edited. In this case, repeat the operations for editing ID groups (such as registering ID groups on managed computers or adding ID-management relay computers).

5.4 Linking system configuration information with ID group information

When changes are made to the system configuration information, you can have the system automatically make the corresponding changes to ID group information. This function reduces the burden on the system administrator.

5.4.1 Procedure for linking system configuration information with ID group information

To link system configuration information and ID group information, you need to select the Synchronize changes to the system configuration option. The check box for this option can be found on the Related to System Configurations tab of the Setup for Distribution by Using Remote Install Manager window during setup of JP1/IT Desktop Management 2 - Manager.

5.4.2 Example of linking system configuration information and ID group information

The following provides examples of linking system configuration information and ID group information.

(1) Deleting hosts from system configuration information

The following describes how system configuration information and ID group information are linked when you remove an ID-management relay computer or a computer registered in an ID group from the system configuration information.

(a) When deleting an ID-management relay computer

The following figure shows an example in which a relay system defined as an ID-management relay computer is removed from the system configuration.

Figure 5‒19: Example of removing a relay system defined as an ID-management relay computer

(b) When deleting a computer registered in an ID group

The following figure shows an example in which a computer registered in an ID group is deleted from the system configuration:

Figure 5‒20: Example when computer in ID group is deleted from system configuration

(2) Changing routes in system configuration information

The following describes how system configuration information and ID group information are linked when you change the route of an ID-management relay computer or a computer registered in an ID group from the system configuration information.

(a) Changing the route of an ID-management relay computer

The following figure shows an example of changing the connection destination of a relay system defined as an ID-management relay computer.

Figure 5‒21: Example of changing the connection destination of a relay system defined as an ID-management relay computer

(b) When changing the route of a computer registered in an ID group

The following figure shows an example in which the connection destination of a computer registered in an ID group is changed:

Figure 5‒22: Example when connection destination of computer in ID group is changed

5.4.3 Notes on linking system configuration information with ID groups

This subsection provides cautionary notes that apply when linking system configuration information with ID groups.

(1) Handling ID groups with passwords

When the system configuration information of a computer registered in a password-protected ID group changes, the ID group information does not change with it.

(2) Linking with jobs

If you remove an ID-management relay computer or a computer registered in an ID group from system configuration information, jobs destined for or traveling through the ID-management relay computer or jobs destined for the managed computer are deleted.

If a route changes as a result of changing the connection destination of a computer registered in an ID group, ID group jobs destined for the computer on the original route are deleted. The system then registers and executes the ID group jobs again for the new route. If a route changes as a result of changing the connection destination of an ID-management relay computer, jobs are not linked with the system configuration information and are executed on the original route.

If you change the name of the node identification key of an ID-management relay computer or a computer registered in an ID group, jobs are not linked with the system configuration information. This means that the jobs defined for or traveling through the ID-management relay computer can no longer be used after the name is changed. In this case, you need to register the jobs again.

(3) Options during setup

To link system configuration information and ID group information, you need to select the Synchronize changes to the system configuration option. The check box for this option can be found on the Related to System Configurations tab of the Setup for Distribution by Using Remote Install Manager window during setup of JP1/IT Desktop Management 2 - Manager. If this option is enabled inconsistently, management information might become inconsistent between higher and lower systems.

(4) Registering relay systems or management relay servers in ID groups

A relay system or management relay server must be registered in an ID group on the local system. If you register the relay system or management relay server in ID groups on a higher system, the system configuration information might not link correctly with the ID group information.

(5) Changing the connection destination of computers registered in ID groups

If you change the connection destination of a computer registered in an ID group, that computer is automatically registered in the ID group at the new connection destination. This process may take some time. Before executing a job with the ID group specified, make sure that the client has been registered in the new ID group. When system configuration information is linked with ID group information, a job adding the computer to the ID group is generated automatically. You can view the status of this job in the Job Status window of Remote Install Manager.

5.4.4 Action to take when automatic notification from ID-management relay computer is delayed

If a computer changes its route while automatic notification from an ID-management relay computer is being delayed, the computer might not be deregistered from its ID group. The following describes how to work around this issue. Here, a managing server or management relay server that creates ID groups and manages ID-management relay computers is called the manager managing the ID group.

Action to take when a computer is not de-registered from ID groups

If a computer changes its route to the manager managing the ID group while an ID group deregistration notification from the ID-management relay computer is delayed, the computer will not be deregistered from the ID group. You can use one of the following approaches to work around this problem:

Perform de-registration again from the computer that was not de-registered from the ID group

For details about how to de-register a computer from an ID group, see 12.2.1 Registering a managed computer in an ID group.

In Remote Install Manager on the manager managing the ID group, delete the ID group registration information for the computer

For details about how to delete a computer from an ID group, see 5.3.4(3) Removing computers from ID groups.

Note:

You can prevent this issue altogether by not de-registering computers from ID groups immediately before changing routes. After changing the route, make sure that the computer has been successfully de-registered from the ID groups.

6 Maintaining System Configuration Information and Host Groups

This chapter describes how to maintain system configuration information and host groups in a system that uses Remote Install Manager to distribute software.

6.1 Maintenance of system configuration information

In the System Configuration window or Destination window, you can search for newly added hosts and register them in host groups. You can also execute jobs for hosts you find, and delete found hosts from the system configuration information.

You can use the following methods to search for hosts:

Search using a name (such as a destination name, host group name, or ID group name) as the search key

Search using the registration date of the host as the search key

Each method is described below. This section also describes how to copy hosts from the search results to the Destination window, and how to delete them from the system configuration information.

6.1.1 Searching for hosts by name

The following describes how to search for hosts by using a name as the search key. Examples of the names you can specify include IP addresses, destination names, host group names, and ID group names.

In the System Configuration or Destination window, from the Options menu, select Find.

The Find dialog box appears. The contents of the dialog box vary depending on whether it was opened from the System Configuration window or the Destination window.

The figures below show examples of the Find window displayed from each of these windows.

Figure 6‒1: Find dialog box displayed from System Configuration window

Figure 6‒2: Find dialog box displayed from Destination window

Destination (only when displayed from Destination window)

Select this option to search by destination name.

Host group/ID Group (only when displayed from Destination window)

Select this option to search by host group name and ID group name.

Find what:

Specify the search string using a maximum of 64 bytes. You cannot use single-byte spaces or the following symbols:

Backslashes (\), forward slashes (/), asterisks (*), double quotation marks ("), colons (:), exclamation marks (!), vertical bars (|), left angle brackets (<), right angle brackets (>), question marks (?), percent signs (%), at marks (@), and single quotation marks (').

The system searches for destinations whose names contain the specified character string.

Find host names

Select this option to search by host name.

This option is unavailable when you display the Find dialog box from the Destination window and select Host group/ID Group as the search target.

Find IP addresses

Select this option to search by IP address.

This option is unavailable when you display the Find dialog box from the Destination window and select Host group/ID Group as the search target.

Find whole word only

Select this check box if you want the search results to only include names that completely match the specified search string.

Match case

Select this check box when you want the search results to distinguish between upper and lower case letters.

Specify the search conditions, and then click Find.

The search process begins, and the search results appear in the Search result area at the bottom of the window.

You can resize the Find dialog box to make the search results more visible.

Select a destination in the Search result area, and then click Jump. Alternatively, double-click the destination.

The System Configuration window or Destination window becomes active and displays information about the destination you selected.

6.1.2 Searching for hosts by date

You can search for hosts based on the date when they were registered on the management server.

To search for hosts using a date as the search key:

In the System Configuration window, from the Options menu, select Find.

The Find dialog box appears.

Click the Find by Dates tab.

Figure 6‒3: Find by Dates page

Specify the date range you want to search.

Range

Specify the start date of the date range, the end date, or both. Specify the dates in the format MM/DD/YY, where MM is the month, DD is the day, and YY is a two-digit year. You can specify dates in the range from Jan 1, 1971 to December 31, 2037.

If you specify only a start date or only an end date, clear the check box for the date you do not specify.

For the past n months

Specify how many months before the current date to include in the search range. You can specify a number from 1 to 999. The default is 1 month. If you have searched by date in the past, the last value you specified is automatically entered in this area. If the number of months you specify makes the beginning of the search range earlier than January 1, 1971, the search range will be from January 1, 1971 to the current date.

For the past n days

Specify how many days before the current date to include in the search range. You can specify a number from 1 to 999. The default is 1 day. If you have searched by date in the past, the last value you specified is automatically entered in this area. If the number of days you specify makes the beginning of the search range earlier than January 1, 1971, the search range will be from January 1, 1971 to the current date.

Specify the search conditions, and then click Find.

The search process begins, and the search results appear in the Date-based Search Results area at the bottom of the window.

You can resize the Find dialog box to make the search results more visible by dragging its borders.

Select a destination in the Date-based Search Results area, and then click Jump. Alternatively, double-click the destination.

The System Configuration window becomes active and displays information about the host you selected.

6.1.3 Copying found hosts to the Destination window

After searching for hosts in the System Configuration window, you can copy them to the Destination window from the search results. This feature is useful when you want to search for newly added hosts and add them to a host group. To copy hosts from search results to the Destination window:

Display the Destination window.

Make the System Configuration window the active window, and from the Options menu, select Find.

The Find dialog box appears.

Search for hosts in the Find dialog box.

Right-click a host in the search results, and from the context menu, select Copy.

Right-click a host group in the Destination window, and from the context menu, select Paste.

The host is copied to the specified host group.

You can also copy a host by dragging it to the Destination window.

6.1.4 Deleting found hosts from system configuration information

You can delete hosts from the system configuration information after searching for them in the System Configuration window. Note that you cannot delete an agent from a computer that also functions as a relay system or management relay server.

When you delete an agent computer from the system configuration information, that agent is also deleted from any host groups and ID groups to which it belongs. However, the device information for the computer is not deleted.

If a relay system or management relay server performs operations to link system configuration information and ID group information, you can remove computers under the relay system or management relay server from the manager. In this case, these computers are also removed from the system configuration information, host groups, and ID groups that are managed by the relay system or management relay server. For details about the operation of systems in which system configuration information is linked with ID groups, see 5.4 Linking system configuration information with ID group information.

If you have removed a computer on a management relay server, execute a Get system configuration information job from the higher system of the management relay server to keep system configuration information consistent throughout the entire system.

Note on deleting large numbers of computers

Before you delete a large number of computers, back up the system configuration information, host groups, and ID groups. This will allow you to recover the original configuration if a problem occurs. For details about how to output this information to files, see 5.1.4 Updating system configuration information output to a file, 5.2.3 Creating host groups from a file, and 5.3.3(2)(c) Outputting ID groups to a file.

Note

If duplicate devices and idle devices that were detected as devices suggested for deletion during device maintenance are deleted automatically or manually, the system configuration information for those devices is also deleted automatically. The devices are also deleted automatically from the host group and ID group to which they belong. For details about device maintenance, see the description of automatic maintenance of devices in the JP1/IT Desktop Management 2 Overview and System Design Guide.

(1) Deleting computers

To delete a computer found in a search from the system configuration information:

In the Find dialog box, specify search conditions and search for hosts.

In the search results, right-click the computer you want to delete, and from the context menu, select Delete from System Configuration Information.

Click OK in the confirmation dialog box.

The specified computer is deleted from the system configuration information, host groups, and ID groups.

(2) Viewing information about deleted computers

The system outputs information about deleted computers to log files. A maximum of nine log files are stored in the directory JP1/IT Desktop Management 2 - Manager-installation-directory\mgr\rmtins\gui.

The name of the log file is rimfindn.log, where n is a numeral from 1 to 9. Each time you delete a computer, the number is incremented by one, giving the file names rimfind1, rimfind2, rimfind3, and so on. After the file rimfind9 is created, the existing log files are overwritten in order from the oldest.

The search conditions are output to the beginning of the log file. Then, information about the deleted computer is listed in the same format as in the system configuration information file. Refer to this information as needed.

The following figure shows an example of a log file:

Figure 6‒4: Log file output example

Note

If duplicate devices and idle devices that were detected as devices suggested for deletion during device maintenance are deleted automatically or manually, information about the deleted devices is output to a log file. The file name is JDNSTRCn.log (n is a number from 1 to 9).

6.1.5 Example of maintenance of system configuration information

This subsection provides example of maintenance of system configuration information, including examples of managing newly added computers.

(1) Examples of managing newly added computers

You can search for computers that were added within a particular time period by specifying the date when the hosts were registered on the management server as a search key. By searching for newly added computers on a regular basis, you can ensure that no hosts are overlooked in terms of job execution, registration into host groups, and other management tasks.

The following figure shows an example of managing new computers added within a specific time period:

Figure 6‒5: Example of managing computers added within a specific time period (1 of 2)

Figure 6‒6: Example of managing computers added within a specific time period (2 of 2)

The figures below show an example of managing newly added computers every 14 days (biweekly on a specific day of the week). To manage newly added computers at a specific interval, enter search conditions as shown in this example.

Figure 6‒7: Example of managing newly added computers every 14 days (biweekly) (1 of 2)

Figure 6‒8: Example of managing newly added computers every 14 days (biweekly) (2 of 2)

6.2 Automatic maintenance of destination group

JP1/IT Desktop Management 2 can automatically detect hosts that are new or have moved, and assign them to the appropriate host groups based on predefined grouping conditions (called a policy). This is called automatic maintenance of destination group Automatic maintenance applies to every computer in the system configuration information regardless of the value specified for Mode in the device information.

This section describes how to set a policy for a host group, and how to apply policies to host groups as a batch. It also provides examples of operating a system in which policies are assigned to host groups.

6.2.1 Assigning policies to host groups

The following describes how to assign a policy to a host group.

If you need to specify host group names when you assign a policy, refer to 5.2.2 Assigning group names.

In the Destination window, from the Options menu, select Auto Host Group/ID Maintenance.

The Policy Setup dialog box appears.

You can also display this dialog box by clicking Create Host Group in the File menu to display the Create Host Group dialog box, then clicking Create the policy for a host group.

Figure 6‒9: Policy Setup dialog box

The Policy Setup dialog box displays conditions using a maximum of 260 single-byte characters (or 130 double-byte characters). Although subsequent characters are not displayed on screen, they remain a valid part of the condition.

To set a new policy, click Add.

To change an existing policy, select the policy you want to change and then click Change. You can also change a policy by double-clicking the policy type.

To delete an existing policy, select the policy you want to delete and then click Delete. Deleting a policy does not delete the host group created by that policy, and hosts registered by the policy are not deleted from the host group.

Click Add.

The Selection of Maintenance Target dialog box appears.

Figure 6‒10: Selection of Maintenance Target dialog box

Select the Automatic maintenance of destination group option, and then click Next.

The Select Policy Type dialog box appears.

Figure 6‒11: Select Policy Type dialog box

Select the desired policy type and then click Next.

Set the policy in the displayed dialog box.

The dialog box that appears depends on the option you selected. For details about the settings in each dialog box, refer to subsections (1) to (6) indicated in the table below.

Selected option

Refer to

Group by IP address

6.2.1(1) Settings in Group by IP Address dialog box

Grouping by using new hosts

6.2.1(2) Settings in Grouping New Hosts dialog box

Group by OS type

6.2.1(3) Settings in Group by OS Type dialog box

Group by additional management items of hardware asset information

6.2.1(4) Settings in Group by Additional Management Item of Hardware Asset Information dialog box

Group by department information

6.2.1(5) Settings in Group by Department Information dialog box

Group by installation location information

6.2.1(6) Settings in Group by Installation Location Information dialog box

After setting the policy, click Next.

The Confirm Policies dialog box appears.

Figure 6‒12: Confirm Policies dialog box

The Confirm Policies dialog box displays conditions using a maximum of 260 single-byte characters (or 130 double-byte characters). Although subsequent characters are not displayed on screen, they remain a valid part of the condition.

Add the following types of hosts to the host group

Select the type of hosts you want the policy to add. If you select Agents only, agents on the same computer as a relay system or management relay server are not added to the host group. Select this option when you do not need to distribute jobs to relay systems or management relay servers.

Click Finish.

The policy is created, and the Apply Policies to All Hosts dialog box appears. Note that this dialog box does not appear for policies that apply to new hosts. Instead, you are returned to the Policy Setup dialog box.

Figure 6‒13: Apply Policies to All Hosts dialog box

In the Apply Policies to All Hosts dialog box, select whether to immediately apply the policies you added or changed.

If you click Apply Now, the policies are immediately applied to host groups. If you click Apply Later, you are returned to the Policy Setup dialog box.

Note that assigning multiple policies to the same host group does not result in an error.

(1) Settings in Group by IP Address dialog box

You can use this dialog box to group hosts by IP address range. You can add hosts by wildcard or by specifying a range.

Wildcard page

Figure 6‒14: Wildcard page

Specify the host group name and the IP addresses. Use an asterisk (*) as a wildcard when specifying the IP address range.

For example, you can add the IP addresses in the range from 172.20.20.0 to 172.20.20.255 to a group by specifying 172.20.20.* in the IP address field.

When you click Add, the condition is added to the list. You can set multiple conditions in the Group by IP Address dialog box. To delete an existing condition, select the condition and click Delete.

Range page

Figure 6‒15: Range page

On the Range page, you can specify a range of IP addresses. When you add a policy, IP address\IP address group is displayed in Host group name as the default path for the higher system. Although you can enter a host group name manually or select from existing host groups, IP address group will be used as the host group name if you leave it unchanged.

Browse and Browse Route buttons

You can display the Host Groups dialog box from either of these pages by clicking the Browse or Browse Route button.

Figure 6‒16: Host Groups dialog box

This dialog box displays a list of host groups in tree form. You can use this dialog box to specify a host group or the route to a host group.

By clicking Browse, you can specify the host group to which the policy applies.

By clicking Browse Route, you can specify the route of the registered policy.

The number of characters you can enter when specifying the host group or route depends on the type of policy. See the description in each dialog box.

When grouping hosts by IP address, you can enter a maximum of 32 bytes per hierarchical level in host group names and routes. The maximum length of the character string from the highest level to the host group name including the path delimiting character (single-byte backslash) must not exceed 164 bytes.

(2) Settings in Grouping New Hosts dialog box

You can use this dialog box to group hosts that are newly registered in the system configuration information. You can only set one host group using this policy.

Figure 6‒17: Group New Hosts dialog box

When adding this policy, New_hosts is displayed by default in the Host group name field. You can enter a host group name manually, or select from a list of existing host groups by clicking the Browse button.

You can enter a maximum of 32 bytes per hierarchical level in host group names. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 189 bytes.

If you click Browse, the Host Groups dialog box described in subsection (1) appears in which you can specify a host group.

(3) Settings in Group by OS Type dialog box

You can use this dialog box to group computers according to the value set for OS type in the system configuration.

Figure 6‒18: Group by OS type dialog box

Each OS type whose check box you select is subject to grouping. You can set any host group name you wish for a given OS type. You can also manage computers with different OS types in one host group by setting the same host group name for those OS types.

You can enter a maximum of 32 bytes per hierarchical level in a route. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 164 bytes.

When you add a policy, OS_type\ is displayed as the default path for the higher system.

If you click Browse Route, the Host Groups dialog box described in subsection (1) appears in which you can specify a route.

You can enter a maximum of 32 bytes per hierarchical level in routes. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 164 bytes.

Clicking Select All selects the check boxes for all OS types. Clicking Deselect All clears all the check boxes.

If you select the Group by separating 32-bit versions and 64-bit versions check box, computers are registered in sub-groups (named x84 for 32-bit operating systems and x64 for 64-bit operating systems) under the host groups.

If you select the Perform grouping to the OS sub-version level check box, you can group computers under the OS type host groups according to the OS sub-version, such as the Service Pack. If the value of OS sub-version is longer than 32 single-byte characters (or 16 double-byte characters), the corresponding host group will not be created.

The table below shows the group in which computers are registered when the system cannot acquire relevant information from the computer during automatic maintenance.

Settings

If CPU information cannot be acquired

If OS sub-version information cannot be acquired

The Group by separating 32-bit versions and 64-bit versions check box and Perform grouping to the OS sub-version level check box are both selected

Registered in a group corresponding to the OS sub-version created under the host group for the OS type

Registered in the host group for the CPU type

Only the Group by separating 32-bit versions and 64-bit versions check box is selected

Registered in the host group for the OS type

--

Only the Perform grouping to the OS sub-version level check box is selected

--

Registered in the host group for the OS type

Legend:

--: Registered in the specified host group

(4) Settings in Group by Additional Management Item of Hardware Asset Information dialog box

You can use this dialog box to create policies that group computers based on additional management items in hardware asset information whose data type is enumeration or text. You can create a maximum of 16 such policies.

Figure 6‒19: Group by Additional Management Item of Hardware Asset Information dialog box

In policies that relate to additional management items in hardware asset information, you can specify host groups on a maximum of six hierarchical levels.

By clicking the Set on nth layer buttons, you can add the selected additional management item to the hierarchical level indicated by the label on the button. When you add an item, the button label changes to Release nth Layer. You can remove a level by clicking the corresponding Release nth Layer button. Any subordinate items are also deleted.

You cannot specify the same additional management item of hardware asset information on different hierarchical levels in a given policy. Nor can you specify the same additional management item in more than one policy.

Note that a host group will not be created if the hardware asset information contains no values for the additional management items defined in the policy.

If you click Browse Route, the Host Groups dialog box described in subsection (1) appears in which you can specify a route. You can enter a maximum of 32 bytes per hierarchical level in a route. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 189 bytes.

(5) Settings in Group by Department Information dialog box

You can use this dialog box to group computers based on the department with which they are associated. You can create only one department policy.

Figure 6‒20: Group by Department Information dialog box

A policy that groups hosts by department can contain a maximum of six hierarchical levels. You can specify the number of levels in Target maintenance range. You can specify levels in which no departments are registered, allowing you to apply policies to departments you add later.

If you click Browse Route, the Host Groups dialog box described in subsection (1) appears in which you can specify a route. You can enter a maximum of 32 bytes per hierarchical level in a route. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 189 bytes.

Computers for which Unknown appears on the Department List page of the Inventory module of JP1/IT Desktop Management 2 are not added to the host group. If you want these computers to be added to the host group, use one of the following methods:

Have the system administrator select the appropriate department for the computer in the Edit Device Details dialog box

Select the computer under Unknown in Department List under Device Inventory in the menu area of the Inventory module. Then, from the Action menu, select Edit Device Details to display the Edit Device Details window, and select the appropriate department under Department. By selecting multiple computers in the Department List area, you can move them all to the selected department.

Instruct the user to fill in department information in the Enter User Information window.

You can use message notification to provide this instruction to the user. For details, see the description of sending messages to users in the JP1/IT Desktop Management 2 Administration Guide.

(6) Settings in Group by Installation Location Information dialog box

You can use this dialog box to group computers based on their location. You can create only one location policy.

Figure 6‒21: Settings in Group by Installation Location Information dialog box

A policy that groups hosts by location can contain a maximum of six hierarchical levels. You can specify the number of levels in Target maintenance range. You can specify levels in which no installation locations are registered, allowing you to apply policies to locations you add later.

If you click Browse Route, the Host Groups dialog box described in subsection (1) appears in which you can specify a route. You can enter a maximum of 32 bytes per hierarchical level in a route. The maximum length of the character string from the highest level of the hierarchy to the end of the host group name including the path delimiting character (single-byte backslash) must not exceed 189 bytes.

You cannot add computers for which Unknown appears in the Location List of the Inventory module of JP1/IT Desktop Management 2. If you want these computers to be added to the host group, use one of the following methods:

Have the system administrator select the appropriate location for the computer in the Edit Device Details dialog box

Select the computer under Unknown in Location List under Device Inventory in the menu area of the Inventory module. Then, from the Action menu, select Edit Device Details to display the Edit Device Details window, and select the appropriate location under Location. By selecting multiple computers in the Location List area, you can move them all to the selected location.

Instruct the user to fill in location information in the Enter User Information window.

You can use message notification to provide this instruction to the user. For details, see the description of sending messages to users in the JP1/IT Desktop Management 2 Administration Guide.

6.2.2 Applying policies to all host groups

This subsection describes how to apply existing policies to host groups as a batch. You can only use this method with hosts that are already registered in the system configuration information. You cannot use this method with newly created hosts.

The length of time taken to perform batch maintenance of host groups increases in proportion to the number of computers and the number of policies.

Note that the automatic maintenance of destination group function does not operate while batch maintenance is in progress. For this reason, we recommend that you perform batch maintenance of host groups during time frames in which device information is updated infrequently.

In the Destination window, from the Options menu, select Auto Host Group/ID Maintenance.

The Policy Setup dialog box appears.

You can also display this dialog box by selecting Create Host Group from the File menu to display the Create Host Group dialog box, and then clicking Create the policy for a host group.

Figure 6‒22: Policy Setup dialog box

Click Apply Policies to All Hosts.

The Apply Policies to All Hosts dialog box appears.

Figure 6‒23: Apply Policies to All Hosts

Use the following options to select the policy type to apply, and then click Execute.

All policies

Select this option to assign all policies listed in the Policy Setup dialog box to host groups. Note that this option does not apply policies that relate to newly added hosts.

Note that you cannot use batch application of ID group policies regardless of type.

Select the policy type to apply

Select the types of policy you want to assign as a batch. You can select multiple types.

- IP address

- OS type

- Additional management item of hardware asset information

- Department

- Installation location

After selecting the policy types, click Execute. The hosts registered in the system configuration information are allocated to the host groups according to the selected policies.

(1) Immediately adding new hosts to host groups

If you want to immediately add new hosts to host groups based on the policies you set, use the following method to update the host groups:

Group by IP address

Execute a Get system configuration information job for the relay system or management relay server. If the destination is an agent on the same computer as the management relay server, add a destination by selecting File and then Create Destination in the Destination window.

Group by using new hosts

In the System Configuration window, search for hosts by date by selecting Find from the Options menu, and then register the found hosts in the host group.

Group by OS type

Re-acquire device information from the JP1/IT Desktop Management 2 user interface.

Group by installation management items of hardware asset information

Re-acquire device information from the JP1/IT Desktop Management 2 user interface.

Group by department information

Re-acquire device information from the JP1/IT Desktop Management 2 user interface.

Group by installation location information

Re-acquire device information from the JP1/IT Desktop Management 2 user interface.

For details about how to re-acquire device information, see the description of the procedure for acquiring the latest device information in the JP1/IT Desktop Management 2 Administration Guide.

(2) Backing up host groups

To back up a host group, first rename the host group that you want to back up in the Destination window. When you rename a host group, the host group with the new name is excluded from automatic maintenance of destination group and can be saved as a backup. If you add or change hosts after renaming the host group, the host group is re-created with the original name according to the policy settings and then updated in the usual way.

6.2.3 Defining host groups with multiple hierarchical levels

If you define multiple hierarchical levels in the policy settings for host groups, the resulting host groups will consist of multiple hierarchical levels. This subsection describes how this hierarchy is configured, using department information as an example.

Figure 6‒24: Example of grouping by department information

The settings shown in this figure result in the following groupings:

Agt01 is added under Unit 1 according to the policy settings.

There is no division or unit information registered for Agt02. Therefore, Agt02 is added directly under the Development group without any intervening levels.

Because the Sales department reports directly to the Software division, there is no Head office information for Agt03. In this case, a new top-level host group Sales is created. Under this Sales group a hierarchy consisting of Sales Division A and Unit 1 is configured and Agt03 is added to Unit 1.

In this manner, host groups are configured even for hosts for which department information could not be acquired, by moving lower elements like divisions up through the hierarchy.

Agents that do not belong to any hierarchy in the Department List or Location List of the Inventory module are not added to host groups. You need to add the appropriate department and location to such agents in the Department List or Location List.

6.3 Automatic ID group maintenance

The process of setting conditions (policies) for ID groups and automatically registering computers based on these conditions is called automatic ID group maintenance. Automatic maintenance applies to all computers in the system configuration information regardless of the value specified for Mode in the device information.

This section describes how to set a policy for an ID group, and provides cautionary notes regarding automatic ID group maintenance.

6.3.1 Setting ID group policies

You can set ID group policies from the manager that manages the ID group or the management relay server specified as an ID-management relay computer. To set an ID group policy:

In the Destination window, from the Options menu, select Auto Host Group/ID Maintenance.

The Policy Setup dialog box appears.

Figure 6‒25: Policy Setup dialog box

Click Add.

To change an existing policy, select the policy you want to change and then click Change. To delete a policy, select the policy you want to delete and then click Delete.

When you click Add, the Selection of Maintenance Target dialog box appears.

Figure 6‒26: Selection of Maintenance Target dialog box

Select the Automatic maintenance of ID option.

Click Next.

The Select Policy Type dialog box appears.

Figure 6‒27: Select Policy Type dialog box

Select the policy type you want to set, and then click Next.

Set the policy in the displayed dialog box.

The dialog box that appears depends on the option you selected. For details about the settings in each dialog box, refer to subsections indicated in the table below.

Selected option

Refer to

Register an ID by using a new host

6.3.1(1) Settings in Register ID by Using New Host dialog box

Register an ID by using asset field definitions

6.3.1(2) Settings in Register ID by Using Asset Field Definitions dialog box

Register an ID by using device inventory

6.3.1(3) Settings in Register ID by Device Inventory dialog box

Click Next.

The Confirm Policies dialog box appears.

Figure 6‒28: Confirm Policies dialog box

Check the ID groups for which the policies are being set. To change an ID group, click Back and select the ID groups again.

Click Finish.

The policies are displayed in the Policy Setup dialog box.

(1) Settings in Register ID by Using New Host dialog box

This policy automatically adds new hosts registered in the system configuration to an ID group. You can only set one such policy.

Figure 6‒29: Register ID by Using New Host dialog box

When you click Browse, the ID List dialog box appears. Use this dialog box to select the ID group for which to set the policy.

To create a new ID group, in the ID List dialog box, click Create ID Group.

(2) Settings in Register ID by Using Asset Field Definitions dialog box

You can register computers in ID groups based on asset management items. You can specify the following asset management items:

Additional management items in hardware asset information whose data type is enumeration

Departments whose data type is enumeration or hierarchy

Installation locations whose data type is enumeration or hierarchy

There is no limit to the number of policies you can set.

However, the length of time taken to perform automatic ID group maintenance depends on the number of set policies.

Figure 6‒30: Register ID by Using Asset Field Definitions dialog box

To set a policy in the Register ID by Using Asset Management Item dialog box:

In the Asset management item area, select an item you want to set, and then click the > button.

The item you selected is added to the Condition area. The Item value column displays the first 259 characters of the item you selected. You can add a maximum of 10 items to the Condition area. You cannot specify the same asset management item more than once.

To remove an item from the Condition area, select the item you want to remove and then click the < button.

Click Browse.

The ID List dialog box appears. Select the ID group for which you want to set the policy.

To create a new ID group, in the ID List dialog box, click Create ID Group.

Click Add.

The policy you specified in the Conditions area is added to the Policies list.

To remove a policy, select the policy you want to remove and then click Delete.

(3) Settings in Register ID by Device Inventory dialog box

You can register computers in ID groups based on device information. You can specify the following device information items:

Computer details (model and manufacturer)

Network details (IP address)

Software details (software name, installation status, and version)

Asset field definition (user-defined text items that are additional management items of hardware asset information)

There is no limit to the number of policies you can set.

However, the length of time taken to perform automatic ID group maintenance depends on the number of set policies.

Figure 6‒31: Register ID by Device Inventory dialog box

To set a policy in the Register ID by Device Inventory dialog box:

Specify an ID policy name.

An ID policy name is required. The maximum length of an ID policy name is 64 bytes. You cannot specify an existing ID policy name.

In the Set Conditions area, select a type of information on which you want to set conditions, and click the Add condition button.

Depending on the selected type of information, an appropriate Add Condition dialog box appears.

Set conditions.

The following table lists conditions available in the Add Condition dialog box.

Type of information

Condition item

Value to be set

Comparison condition

Computer details

Model

Specify a model with a comparison condition.

is

begins with

contains of

Manufacturer

Specify a manufacturer with a comparison condition.

is

begins with

contains of

Network details

IP Address

Wildcard specification

Range specification

For Wildcard:

Specify an IP address. Asterisks (*) can be used as wildcard characters.

For Range:

Specify a range of IP addresses.

--

Software details

Software Name

Specify a software name with a comparison condition.

is

begins with

contains of

Software Installation Status

Specify the installation status.

Not installed

Installed

--

Version

Direct specification

Range specification

For Direct specification:

Specify a version with a comparison condition.

For Range specification:

Specify a range of versions.

is

is not

greater than

equal to or greater than

less than

less than or equal to

Asset field definition (Asset management items)

User-defined item

Direct specification

Range specification

For Direct specification:

Specify a value of the user-defined item with a comparison condition.

For Range specification:

Specify a range of values of the user-defined item.

is

is not

begins with

contains of

not contain of

Legend: --: Not applicable

Click OK.

Conditions that you set appear in Condition list in the Register ID by Device Inventory dialog box. A policy can have up to 10 conditions. Note that a device information ID policy cannot have more than one condition for the same type of information (condition for the same user-defined item in the case of an asset management item).

To change a condition, select the condition you want to change and click the Change button. The Change Condition dialog box appears so that you can change the condition.

To delete a condition, select the condition you want to delete and click the Delete button.

Click Browse.

The ID List dialog box appears. Select the ID group for which you want to set the policy.

To create a new ID group, in the ID List dialog box, click Create ID Group.

6.3.2 Notes on automatic ID group maintenance

The following cautionary notes apply when performing automatic ID group maintenance:

You cannot assign the same policy more than once.

Computers are automatically registered in ID groups during automatic ID group maintenance, regardless of whether the ID group is protected by a password.

Relay systems and management relay servers are not subject to automatic ID group maintenance. To register a relay system in an ID group, you need to do so manually.

ID group jobs are executed when the computer registered in the ID group next establishes a connection with the higher system. If automatic ID group maintenance takes place after you execute an ID group job, the computers will be automatically registered in the ID group. However, the timing with which the ID group job is executed will differ for each computer.

When you delete an ID group, the policies specified for that ID group are automatically deleted. However, if the ID group is deleted from another instance of Remote Install Manager while you are assigning a policy, that policy will not be automatically deleted. In this scenario, you need to delete the policy or change the ID group specified for the policy. Such policies are outside the scope of automatic maintenance because the specified ID group no longer exists.

When you delete a policy, computers that are already registered in the ID group are not automatically de-registered.

On a management relay server, you might specify the asset management items and ID groups created on a higher system as policies. In such a case, do not specify settings that use the same conditions as the higher system and a different ID group at the registration destination.

You might create a new ID group while assigning a policy, and use an ID-management relay computer to manage that ID group. In such a case, a relay system or management relay server must be set as an ID-management relay computer before you finish assigning the policy. Make sure that the relay system or management relay server has been set as the ID-management relay computer before you finish assigning the policy.

To ensure successful operation, the system administrator must use the Job Status window of Remote Install Manager to delete ID group jobs promptly when they are no longer necessary. Doing so can prevent automatic ID group maintenance from triggering unnecessary ID group jobs or increasing load on the system.

6.4 Creating a policy from a file

You can output information about the automatic maintenance policies for host groups and ID groups to an XML file. You can also set policies as a batch by creating multiple policy files and inputting the ones that are appropriate for the purpose of the system. By editing an XML file containing these policies, you can create new policies based on existing ones.

A file containing the policies for automatic maintenance of host groups and ID groups is called an automatic maintenance policy file.

This section describes how to input, output, and edit automatic maintenance policy files.

6.4.1 Inputting and outputting automatic maintenance policy files

You can input and output information to and from an automatic maintenance policy file by using the Add from File and Output File buttons in the Policy Setup dialog box.

Figure 6‒32: Policy Setup dialog box

Add from File button

When you click the Add from File button, the Add Automatic Maintenance Policy dialog box appears. Specify the automatic maintenance policy file that you want to input, and then click Open. Policies are added to the Policy Setup window based on the file contents.

No policies are added from the file if any of the following apply:

The file is not in valid XML format

The conditions defined for a policy are invalid

The file contains a policy with exactly the same settings as an existing policy

A message box will appear giving the reason why the policies cannot be added. Resolve the issue according to the contents of the message.

Note the following when inputting an automatic maintenance policy file:

Comments users have entered in the automatic maintenance policy file are erased when the file is input. No comments will be included when the file is output.

There is a limit to the number of policies that can be set. This limit depends on the policy type. If you use the Add button in the Policy Setup dialog box to create a policy and the maximum number of policies is reached for that policy type, the system will automatically restrict further policy creation. If the number of policies created in the automatic maintenance policy file exceeds the maximum, an error message will appears when you input the file, and the policies in the automatic maintenance policy file will not be applied. The following table shows the number of permitted policies by policy type:

Table 6‒1: Maximum number of policies by policy type

Automatic maintenance type

Policy type

Maximum number

Host group

IP address

--

New host

1

OS type

--

Additional management item of hardware asset information

16

Department

1

Installation location

1

ID group

New host

1

Asset field definition

--

Device inventory

--

Legend:

--: No maximum.

Output File button

When you click the Output File button, the Output Automatic Maintenance Policy dialog box appears. To output a file, specify the output directory for the file and then click Save.

If you specify an asset management item in a language other than the default in a policy condition, the condition definition is output with the item names and values in the default language.

6.4.2 Editing an automatic maintenance policy file

An automatic maintenance policy file collectively defines the automatic maintenance policies for several ID groups and several host groups.

If you want to use any of the single-byte symbols listed in the table below in the file, you need to replace them with a specific character string.

Table 6‒2: Single-byte symbols requiring replacement

Single-byte symbols requiring replacement

String that replaces symbol

<

&lt;

>

&gt;

&

&amp;

"

&quot;

'

&apos;

The following figure shows the structure of an automatic maintenance policy file:

Figure 6‒33: Structure of automatic maintenance policy file

The tag on the first line indicates that the file is an XML file. The file is read according to the character encoding specified for the encoding parameter in this tag. If you omit this tag, the system assumes the file is encoded in UTF-8.

You must include the tags that indicate the file is an automatic maintenance policy file.

The automatic maintenance policy file shown in Figure 6-33 includes the List of automatic maintenance policy definitions (ID groups) followed by the List of automatic maintenance policy definitions (for host groups). However, automatic maintenance policy files can be imported successfully regardless of the order of the two lists. When automatic maintenance policy definitions are exported to a file, firstly the list of host group policy definitions is written to the file.

The List of automatic maintenance policy definitions (ID groups) and the List of automatic maintenance policy definitions (host groups) are each described below.

(1) List of automatic maintenance policy definitions (ID groups)

Format

Each definition has the format shown below. The line indentation indicates the relationship between parent and child tags. You must define a child tag within the appropriate parent.

The tags must be written in the following order:

<IDPolicyList>
  <IDPolicy>
    <IDName>ID-group-name</IDName>
    <IDPolicyKind>policy-type</IDPolicyKind>
    [<CondAssetFieldDefinitionValue>
      <AssetFieldDefinitionValue assetItem="asset-management-item">
        <AssetFieldDefinitionName>asset-management-item-name</AssetFieldDefinitionName>
        <AssetFieldDefinitionValue>asset-management-item-value</AssetFieldDefinitionValue>
      </AssetFieldDefinitionValue>
    </CondAssetFieldDefinitionValue>]
    [<CondInventoryInfoValue>
      <CondInventoryInfoName>device-information-policy-name</CondInventoryInfoName>
      <CondInventoryInfoList>
        [<ComputerInfo>
          [<Model filterType="comparison condition">model</Model>]
          [<Manufacturer filterType="comparison condition">manufacturer</Manufacturer>]
        </ComputerInfo>]
        [<NetworkInfo>
          <FromIpAddress>lower-IP-address-limit</FromIpAddress>
          <ToIpAddress>upper-IP-address-limit</ToIpAddress>
        </NetworkInfo>]
        [<SoftwareInfo installStatus="installation-status">
          <SoftwareName filterType="comparison condition">software-name</SoftwareName>
          [<Version filterType="comparison condition">
            <VersionValue1>version</VersionValue1>
            [<VersionValue2>version</VersionValue2>]
          </Version>]
        </SoftwareInfo>]
        [<AssetFieldDefinitionInfo>
          <AssetFieldDefinitionName>asset-management-item-name
</AssetFieldDefinitionName>
          <FieldValue filterType="comparison condition">
            <FieldValue1>asset-management-item-value</FieldValue1>
            [<FieldValue2>asset-management-item-value</FieldValue2>]
          </FieldValue>
        </AssetFieldDefinitionInfo>]
      </CondInventoryInfoList>
    </CondInventoryInfoValue>]
  </IDPolicy>
</IDPolicyList>

Description

The following table describes each tag, the values you can specify, and the allowed number of occurrences of the tag. When the allowed number of occurrences is zero, you can omit the tag unless there is a child element.

Tag

Description

Specifiable values

Allowed number of occurrences of the tag

<IDPolicyList>

Indicates that the following information is a list of definitions for automatic ID group maintenance policies.

--

0 times or once

<IDPolicy>

Indicates that the following information is a definition of an automatic ID group maintenance policy.

--

More than once

<IDName>

Specifies the name of the ID group.

Any character string of up to 32 bytes (including single-byte and/or double-byte characters) excluding the following characters:

Exclamation marks (!), double-quotation marks ("), percent signs (%), quotation marks ('), asterisks (*), periods (.), forward slashes (/), colons (:), left angle brackets (<), right angle brackets (>), question marks (?), at marks (@), backslashes (\), vertical bars (|), single-byte spaces, and control characters

Once

<IDPolicyKind>

Specifies the policy type.

For ID group registration of new hosts:

newHost

For ID group registration based on asset management items:

assetFieldDefinition

For ID group registration of device information:

inventoryInfo

Once

<CondAssetFieldDefinitionValue>

Indicates that the following information defines ID group registration based on asset management items. Use this tag when assetFieldDefinition is specified in the <IDPolicyKind> tag.

--

0 times or once

<AssetFieldDefinitionValue assetItem="asset-management-item">

Indicates that the following information defines a condition on an asset management item. As the value of the assetItem parameter, specify one of the following values depending on the type of asset management item:

For additional management items in hardware asset information whose data type is enumeration:

true

For departments and installation locations:

false

You can specify a maximum of 10 sets of <AssetFieldDefinitionValue> tags per policy.

--

More than once

<AssetFieldDefinitionName>

Specifies the asset management item.#

Department

Installation location

Enumeration type additional management items in hardware asset information

Once

<AssetFieldDefinitionValue>

Specifies the value of the asset management item.#

The selection item of the asset management item specified in <AssetFieldDefinitionName>.

Once

<CondInventoryInfoValue>

Indicates that the following information defines ID group registration based on device information. Use this tag when inventoryInfo is specified in the <IDPolicyKind> tag.

--

0 times or once

<CondInventoryInfoName>

Specifies a device information policy name.

Any character string with a length of at least one character (up to 64 bytes)

Once

<CondInventoryInfoList>

Indicates that the following information is a list of device information conditions.

A policy has up to 10 device information conditions (that is, a <CondInventoryInfoList> node has up to 10 child nodes).

--

Once

<ComputerInfo>

Indicates that the following information defines a condition on computer details.

--

0 times or once

<Model filterType="comparison condition">

Specifies a model.

filterType specifies a comparison condition for the specified model.

Omitting this tag means that there is no model condition.

A model can be set to:

Any character string with a length of at least one character (up to 512 bytes)

filterType can be set to:

exactMatch: Equal to the specified value

startWith: Starts with the specified value

include: Includes the specified value

0 times or once

<Manufacturer filterType="comparison condition">

Specifies a manufacturer.

filterType specifies a comparison condition for the specified manufacturer.

Omitting this tag means that there is no manufacturer condition.

A manufacturer can be set to:

Any character string with a length of at least one character (up to 512 bytes)

filterType can be set to:

exactMatch: Equal to the specified value

startWith: Starts with the specified value

include: Includes the specified value

0 times or once

<NetworkInfo>

Indicates that the following information defines a condition on network details.

--

0 times or once

<FromIpAddress>

Specifies the start address of an IP address range.

An IP address in IPv4 format (xxx.xxx.xxx.xxx)

Once

<ToIpAddress>

Specifies the end address of an IP address range.

An IP address in IPv4 format (xxx.xxx.xxx.xxx)

Once

<SoftwareInfo installStatus="installation-status">

Indicates that the following information defines a condition on software details.

installStatus specifies whether the software program is installed.

installStatus can be set to:

true: Installed

false: Not installed

Omitting installStatus has the same effect as setting it to false.

0 times or once

<SoftwareName filterType="comparison condition">

Specifies a software name.

filterType specifies a comparison condition for the specified software name.

A software name can be set to:

Any character string with a length of at least one character (up to 1,024 bytes)

filterType can be set to:

exactMatch: Equal to the specified value

startWith: Starts with the specified value

include: Includes the specified value

Once

<Version filterType="comparison condition">

Indicates that the following information defines a condition on the version.

filterType specifies a comparison condition for the specified version.

Omitting this tag means that there is no version condition.

filterType can be set to:

equal: Equal to the specified value

notEqual: Not equal to the specified value

greater: Greater than the specified value

greaterEqual: Equal to or greater than the specified value

less: Less than the specified value

lessEqual: Equal to or less than the specified value

between: Between VersionValue1 and VersionValue2

0 times or once

<VersionValue1>

Specifies a specific version, or the start value of a range of versions.

Any character string with a length of at least one character (up to 256 bytes)

Once

<VersionValue2>

Specifies the end value of a range of versions.

This tag can be specified when a range is specified (that is, the filterType attribute of the Version tag is set to between).

Any character string with a length of at least one character (up to 256 bytes)

0 times or once

<AssetFieldDefinitionInfo>

Indicates that the following information defines a condition on an asset management item.

You can specify different conditions for different asset management items (that is, you cannot specify multiple conditions for the same asset management item).

--

More than 0 times or once

<AssetFieldDefinitionName>

Specifies the name of an asset management item.#

You can specify a user-defined text item that is an additional management item of hardware asset information.

--

Once

<FieldValue filterType="comparison condition">

Indicates that the following information defines a condition on the value of an asset management item.

filterType specifies a comparison condition for the asset management item value.

filterType can be set to:

exactMatch: Equal to the specified value

notMatch: Not equal to the specified value

startWith: Starts with the specified value

include: Includes the specified value

notInclude: Does not include the specified value

between: Between FieldValue1 and FieldValue2

Once

<FieldValue1>

Specifies a specific value of the asset management item, or the start value of a range of the asset management item values.

Any character string with a length of at least one character (up to 512 bytes)

Once

<FieldValue2>

Specifies the end value of a range of the asset management item values.

This can be specified when a range is specified (that is, the filterType attribute of the FieldValue tag is set to between).

Any character string with a length of at least one character (up to 512 bytes)

0 times or once

#

When specifying an asset management item that is defined in more than one language, specify the item names and values in the default language.

(2) List of automatic maintenance policy definitions (host groups)

Format

Each definition has the format shown below. The line indentation indicates the relationship between parent and child tags. You must define a child tag within the appropriate parent.

The tags must be written in the following order:

<DestGroupPolicyList>
  <DestGroupPolicy>
    <DestGroupPolicyKind>policy-type</DestGroupPolicyKind>
    [<CondIpAddress>
      <FromIpAddress>lower-IP-address-limit</FromIpAddress>
      <ToIpAddress>upper-IP-address-limit</ToIpAddress>
    </CondIpAddress>]
    [<CondOSKind>
      <OsKind>OS</OsKind>
    </CondOSKind>]
    [<CondOSKindOption>
      <CpuKind>CPU-type</CpuKind>
      <OsSubversion>OS-subversion</OsSubversion>
    </CondOSKindOption>]
    [<CondAssetCostumField>
      <AssetCostumFieldName>additional-management-item-of-hardware-asset-information</AssetCostumFieldName>
    </CondAssetCostumField>]
    [<CondDepartmentGroup>
      <TargetGroupRange>number-of-department-tiers</TargetGroupRange>
    </CondDepartmentGroup>]
    [<CondLocationGroup>
      <TargetGroupRange>number-of-installation-location--tiers</TargetGroupRange>
    </CondLocationGroup>]
    [<DestGroupPath>route-of-application-target-host-group</DestGroupPath>]
    [<DestGroupName>name-of-application-target-host-group</DestGroupName>]
    [<DestGroupTargetHostKind>management-type-of-target-computer</DestGroupTargetHostKind>]
  </DestGroupPolicy>
</DestGroupPolicyList>

Description

The following table describes each tag, the values you can specify, and the allowed number of occurrences of the tag. When the allowed number of occurrences is zero, you can omit the tag unless there is a child element.

Tag

Description

Specifiable values

Allowed number of occurrences of the tag

<DestGroupPolicyList>

Indicates that the following information is a list of definitions for automatic maintenance of destination group policies.

--

0 times or once

<DestGroupPolicy>

Indicates that the following information is a definition of an automatic maintenance of destination group policy.

--

More than once

<DestGroupPolicyKind>

Specifies the policy type.

To group by IP address:

ipAddress

To group by OS type:

osType

To group new hosts:

newHost

To group based on additional management items of hardware asset information:

assetCostumField

To group based on department information:

departmentGroup

To group based on installation location information:

locationGroup

Once

<CondIpAddress>

Indicates that the following information is the definition of an IP address group. Use this tag when ipAddress is specified in the <DestGroupPolicyKind> tag.

--

0 times or once

<FromIpAddress>

Specifies the start address of the IP address range.

An IP address in IPv4 format.

Once

<ToIpAddress>

Specifies the end address of the IP address range.

An IP address in IPv4 format.

Once

<CondOSKind>

Indicates that the following information defines conditions for grouping by OS type. Use this tag when osType is specified in the <DestGroupPolicyKind> tag.

--

0 times or once

<OsKind>

Specifies the OS type.

WindowsXP

WindowsServer2003

HP_UX

Solaris

AIX

WindowsVista

WindowsServer2008

Windows7

WindowsServer2008R2

Windows8

WindowsServer2012

Windows8_1

WindowsServer2012R2

Windows10

WindowsServer2016

WindowsServer2019

WindowsServer2022

Windows11

RedHatEnterpriseLinux

CentOS

Once

<CondAssetCostumField>

Indicates that the following information defines conditions for grouping based on additional management items of hardware asset information. Use this tag when assetCostumField is specified in the <DestGroupPolicyKind> tag.

--

0 times or once

<AssetCostumFieldName>

Specifies an additional management item of hardware asset information. You can specify a maximum of 6 sets of <AssetCostumFieldName> tags per policy.#

An additional management item in hardware asset information whose data type is enumeration or text

More than once

<CondDepartmentGroup>

Indicates that the following information defines conditions for grouping based on department information. Use this tag when departmentGroup is specified in the <DestGroupPolicyKind> tag.#

--

0 times or once

<CondLocationGroup>

Indicates that the following information defines conditions for grouping based on installation location. Use this tag when locationGroup is specified in the <DestGroupPolicyKind> tag.

--

0 times or once

<TargetGroupRange>

Specifies the tiers to be grouped by department or installation location.

1 to 6

Once

<DestGroupPath>

Specifies the route to the host group that is to be subject to automatic maintenance. If you omit this tag, the policy is assigned to all destinations. You can specify this tag when the following values are specified in the <DestGroupPolicyKind> tag:

ipAddress

osType

assetCostumField

departmentGroup

locationGroup

newHost

Any character string of up to 32 bytes (including single-byte and/or double-byte characters) excluding the following characters:

Exclamation marks (!), double-quotation marks ("), percent signs (%), quotation marks ('), asterisks (*), periods (.), forward slashes (/), colons (:), left angle brackets (<), right angle brackets (>), question marks (?), at marks (@), backslashes (\), vertical bars (|), single-byte spaces, and control characters

0 times or once

<DestGroupName>

Specifies the host group that is to be subject to automatic maintenance. You can specify this tag when the following values are specified in the <DestGroupPolicyKind> tag:

ipAddress

osType

newHost

Any character string of up to 32 bytes (including single-byte and/or double-byte characters) excluding the following characters:

Exclamation marks (!), double-quotation marks ("), percent signs (%), quotation marks ('), asterisks (*), periods (.), forward slashes (/), colons (:), left angle brackets (<), right angle brackets (>), question marks (?), at marks (@), backslashes (\), vertical bars (|), single-byte spaces, and control characters

0 times or once

<DestGroupTargetHostKind>

Specifies the type of host to subject to automatic maintenance. If you omit this tag, the policy applies to all hosts.

To apply the policy to all hosts (relay systems and agents):

all

To apply the policy to agents only:

agentOnly

0 times or once

<CondOSKindOption>

Indicates that the following information defines optional detailed conditions for grouping hosts by OS type. Use this tag when osType is specified in the <DestGroupPolicyKind> tag.

--

0 times or once

<CpuKind>

Specifies whether to separate 32-bit and 64-bit hosts into different groups. If you omit this tag, 32 and 64-bit hosts are placed in the same group.

To separate hosts:

true

To not separate hosts:

false

0 times or once

<OsSubversion>

Specifies whether to further group hosts based on their OS sub-version. If you omit this tag, hosts are not grouped by sub-version.

To group by sub-version:

true

To not group by sub-version:

false

0 times or once

#

When specifying an asset management item that is defined in more than one language, specify the item names and values in the default language.

6.4.3 Example of policy creation

The following is an example of an automatic maintenance policy file.

<?xml version="1.0" encoding="utf-8" ?>
<AutoMaintenancePolicy>
  <MaintenancePolicyList>
    <DestGroupPolicyList>
      <DestGroupPolicy>
        <DestGroupPolicyKind>ipAddress</DestGroupPolicyKind>
        <CondIpAddress>
          <FromIpAddress>10.210.177.150</FromIpAddress>
          <ToIpAddress>10.210.177.160</ToIpAddress>
        </CondIpAddress>
        <DestGroupPath>IP-address</DestGroupPath>
        <DestGroupName>IP-address-group</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>ipAddress</DestGroupPolicyKind>
        <CondIpAddress>
          <FromIpAddress>192.168.111.0</FromIpAddress>
          <ToIpAddress>192.168.111.255</ToIpAddress>
        </CondIpAddress>
        <DestGroupPath>IP-address</DestGroupPath>
        <DestGroupName>IP-address-group</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>newHost</DestGroupPolicyKind>
        <DestGroupName>New-PCs</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>osType</DestGroupPolicyKind>
        <CondOSKind>
          <OsKind>Windows7</OsKind>
        </CondOSKind>
        <CondOSKindOption>
          <OsSubversion>true</OsSubversion>
          <CpuKind>true</CpuKind>
        </CondOSKindOption>
        <DestGroupPath>OS-type</DestGroupPath>
        <DestGroupName>Windows7</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>osType</DestGroupPolicyKind>
        <CondOSKind>
          <OsKind>Windows8_1</OsKind>
        </CondOSKind>
        <CondOSKindOption>
          <OsSubversion>true</OsSubversion>
          <CpuKind>true</CpuKind>
        </CondOSKindOption>
        <DestGroupPath>OS-type</DestGroupPath>
        <DestGroupName>Windows8_1</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>osType</DestGroupPolicyKind>
        <CondOSKind>
          <OsKind>WindowsServer2012R2</OsKind>
        </CondOSKind>
        <CondOSKindOption>
          <OsSubversion>true</OsSubversion>
          <CpuKind>true</CpuKind>
        </CondOSKindOption>
        <DestGroupPath>OS-type\Server</DestGroupPath>
        <DestGroupName>WindowsServer2012R2</DestGroupName>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>departmentGroup</DestGroupPolicyKind>
        <CondDepartmentGroup>
          <TargetGroupRange>4</TargetGroupRange>
        </CondDepartmentGroup>
        <DestGroupPath>Department</DestGroupPath>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>locationGroup</DestGroupPolicyKind>
        <CondLocationGroup>
          <TargetGroupRange>5</TargetGroupRange>
        </CondLocationGroup>
        <DestGroupPath>Location</DestGroupPath>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
      <DestGroupPolicy>
        <DestGroupPolicyKind>assetCostumField</DestGroupPolicyKind>
        <CondAssetCostumField>
          <AssetCostumFieldName>Server-Client</AssetCostumFieldName>
          <AssetCostumFieldName>PC-type</AssetCostumFieldName>
        </CondAssetCostumField>
        <DestGroupPath>Asset-management-item</DestGroupPath>
        <DestGroupTargetHostKind>all</DestGroupTargetHostKind>
      </DestGroupPolicy>
    </DestGroupPolicyList>
    <IDPolicyList>
      <IDPolicy>
        <IDName>ID_NewHosts</IDName>
        <IDPolicyKind>newHost</IDPolicyKind>
      </IDPolicy>
      <IDPolicy>
        <IDName>ID_notebookPCs</IDName>
        <IDPolicyKind>assetFieldDefinition</IDPolicyKind>
        <CondAssetFieldDefinitionValue>
          <AssetFieldDefinitionValue assetItem="true">
            <AssetFieldDefinitionName>PC-type</AssetFieldDefinitionName>
            <AssetFieldDefinitionValue>notebook</AssetFieldDefinitionValue>
          </AssetFieldDefinitionValue>
          <AssetFieldDefinitionValue assetItem="true">
            <AssetFieldDefinitionName>Server-Client</AssetFieldDefinitionName>
            <AssetFieldDefinitionValue>ClientPC</AssetFieldDefinitionValue>
          </AssetFieldDefinitionValue>
        </CondAssetFieldDefinitionValue>
      </IDPolicy>
      <IDPolicy>
        <IDName>ID_NotebookPC</IDName>
        <IDPolicyKind>assetFieldDefinition</IDPolicyKind>
        <CondAssetFieldDefinitionValue>
          <AssetFieldDefinitionValue assetItem="true">
            <AssetFieldDefinitionName>PC-type</AssetFieldDefinitionName>
            <AssetFieldDefinitionValue>Notebook</AssetFieldDefinitionValue>
          </AssetFieldDefinitionValue>
          <AssetFieldDefinitionValue assetItem="true">
            <AssetFieldDefinitionName>Server-Client</AssetFieldDefinitionName>
            <AssetFieldDefinitionValue>Other</AssetFieldDefinitionValue>
          </AssetFieldDefinitionValue>
        </CondAssetFieldDefinitionValue>
      </IDPolicy>
      <IDPolicy>
        <IDName>ID_NewYork_Control</IDName>
        <IDPolicyKind>assetFieldDefinition</IDPolicyKind>
        <CondAssetFieldDefinitionValue>
          <AssetFieldDefinitionValue assetItem="false">
            <AssetFieldDefinitionName>Installation-location</AssetFieldDefinitionName>
            <AssetFieldDefinitionValue>/National/EastCoast/NewYork/</AssetFieldDefinitionValue>
          </AssetFieldDefinitionValue>
        </CondAssetFieldDefinitionValue>
      </IDPolicy>
      <IDPolicy>
        <IDName>ID1150A</IDName>
        <IDPolicyKind>inventoryInfo</IDPolicyKind>
        <CondInventoryInfoValue>
          <CondInventoryInfoName>PolicyName001</CondInventoryInfoName>
          <CondInventoryInfoList>
            <ComputerInfo>
              <Model filterType="exactMatch">Modelname123</Model>
              <Manufacturer filterType="include">makername123</Manufacturer>
            </ComputerInfo>
            <SoftwareInfo installStatus="true">
              <SoftwareName filterType="startWith">Adobe Flash Player</SoftwareName>
              <Version filterType="less">
                <VersionValue1>26.0.0.137</VersionValue1>
              </Version>
            </SoftwareInfo>
            <AssetFieldDefinitionInfo>
              <AssetFieldDefinitionName>PersonalNumber</AssetFieldDefinitionName>
              <FieldValue filterType="startWith">
                <FieldValue1>USR2010</FieldValue1>
              </FieldValue>
            </AssetFieldDefinitionInfo>
            <AssetFieldDefinitionInfo>
              <AssetFieldDefinitionName>AAARequestDate</AssetFieldDefinitionName>
              <FieldValue filterType="between">
                <FieldValue1>20171001</FieldValue1>
                <FieldValue2>20171130</FieldValue2>
              </FieldValue>
            </AssetFieldDefinitionInfo>
          </CondInventoryInfoList>
        </CondInventoryInfoValue>
      </IDPolicy>
      <IDPolicy>
        <IDName>ID1150B</IDName>
        <IDPolicyKind>inventoryInfo</IDPolicyKind>
        <CondInventoryInfoValue>
          <CondInventoryInfoName>PolicyName002</CondInventoryInfoName>
          <CondInventoryInfoList>
            <NetworkInfo>
              <FromIpAddress>192.168.10.20</FromIpAddress>
              <ToIpAddress>192.168.10.255</ToIpAddress>
            </NetworkInfo>
            <SoftwareInfo installStatus="false">
              <SoftwareName filterType="startWith">ABC Software</SoftwareName>
            </SoftwareInfo>
            <AssetFieldDefinitionInfo>
              <AssetFieldDefinitionName>AAACurrentVersion</AssetFieldDefinitionName>
              <FieldValue filterType="exactMatch">
                <FieldValue1>1.8</FieldValue1>
              </FieldValue>
            </AssetFieldDefinitionInfo>
            <AssetFieldDefinitionInfo>
              <AssetFieldDefinitionName>SeatCode</AssetFieldDefinitionName>
              <FieldValue filterType="between">
                <FieldValue1>DP-A-501</FieldValue1>
                <FieldValue2>DP-B-299</FieldValue2>
              </FieldValue>
            </AssetFieldDefinitionInfo>
          </CondInventoryInfoList>
        </CondInventoryInfoValue>
      </IDPolicy>
    </IDPolicyList>
  </MaintenancePolicyList>
</AutoMaintenancePolicy>

This example defines automatic maintenance policies with the following characteristics:

Host groups

Computers with IP addresses in the ranges from 10.210.177.150 to 10.210.177.160 and 192.168.111.0 to 192.168.111.255 are registered in the host group IP-address-group at the route IP-address.

Newly created hosts are registered in the host group New-PCs.

Computers whose OS type is Windows 7 are registered in the Windows7 host group under the OS-type route, separated into 32-bit and 64-bit hosts. These hosts are further grouped by OS sub-version.

Computers whose OS type is Windows 8.1 are registered in the Windows 8.1 host group under the OS-type route, separated into 32-bit and 64-bit hosts. These hosts are further grouped by OS sub-version.

Computers whose OS type is Windows Server 2012 R2 are registered in the WindowsServer2012R2 host group under the OS-type\Server route, separated into 32-bit and 64-bit hosts. These hosts are further grouped by OS sub-version.

Computers positioned in a hierarchy based on department information are registered in a maximum of four levels under the Department route.

Computers positioned in a hierarchy based on installation location are registered in a maximum of five levels under the Location route.

Computers positioned in a hierarchy based on the Server-Client and PC-type additional management items of hardware asset information are registered under the Asset-management-item route.

ID groups

Newly added hosts are registered in the ID group ID_NewHosts.

Computers for which the value of the PC type additional management item is Notebook and the value of Server-Client is ClientPC or Other are registered in the ID group ID_notebookPCs.

Computers whose installation location is /National/EastCoast/NewYork/ are registered in the ID group ID_NewYork_Control.

Computers that meet all of the following conditions are registered in the ID group ID1150A. (The evaluations are case insensitive.)

- The model name is equal to Modelname123.

- The manufacturer name contains makername123.

- A software program whose name starts with Adobe Flash Player and whose version is earlier than 26.0.0.137 is installed.

- The value of the PersonalNumber additional management item starts with USR2010.

- The value of the AAARequestDate additional management item is between 20171001 and 20171130.

Computers that meet all of the following conditions are registered in the ID group ID1150B. (The evaluations are case insensitive.)

- The IP address is between 192.168.10.20 and 192.168.10.255.

- A software program whose name starts with ABC Software is not installed.

- The value of the AAACurrentVersion additional management item is 1.8.

- The value of the SeatCode additional management item is between DP-A-501 and DP-B-299.

You can create a new automatic maintenance policy by copying this policy and changing attributes such as the IP address ranges and host group names. You can efficiently create multiple automatic maintenance policies by copying and editing an existing policy in this way.

6.5 Managing the deletion history of system configuration information

JP1/IT Desktop Management 2 - Manager can manage information that describes when and how systems were removed from the system configuration information.

To manage the deletion history of system configuration information, you need to enable the Save deletion history option when setting up JP1/IT Desktop Management 2 - Manager. The check box for this option can be found on the Related to System Configurations tab of the Setup for Distribution by Using Remote Install Manager window during JP1/IT Desktop Management 2 - Manager configuration.

6.5.1 Displaying deletion history

The deletion history of system configuration information is displayed in the Deletion History of System Configuration Information dialog box. To display this dialog box, from the File menu, select Deletion History of System Configuration Information. You can also display the dialog box from any Remote Install Manager window.

Figure 6‒34: Deletion History of System Configuration Information dialog box

In addition to Destination, Subkey, and Route, the Deletion History of System Configuration Information dialog box displays the following information for each deleted host:

Deletion cause

This column shows what caused the host to be deleted from the system configuration information.

Deletion cause

Meaning

Delete by uninstallation result

Uninstallation was reported by a managed computer, relay system, or management relay server.

The host was deleted by a Get system configuration information job.

Delete by administrator

The managed computer, relay system, or management relay server was deleted manually from the System Configuration window.

The managed computer was deleted manually from the Search dialog box.

The host detected as a device suggested for deletion during device maintenance was deleted.

Delete by instruction from higher manager

When a lower system changed its connection destination, a management relay server received a deletion notification of system configuration information for a lower system remaining on an old route from the higher manager.

A management relay server received a deletion notification from the higher manager due to operation of Delete from System Configuration Information in the menu opened from the Search dialog box.

Deletion time

The date and time when the host was deleted from the system configuration information.

You can also display the following items in the Deletion History of System Configuration Information dialog box:

Host ID, MAC address, Comment, Creation date/time, Update date/time

To add these items, from the right-click menu, select Select Information, and then select the items you want to display.

You can resize the Deletion History of System Configuration Information dialog box by dragging its borders. You can also sort the table in ascending or descending order of a particular column by clicking the column header.

6.5.2 Outputting deletion history to a CSV file

You can output the deletion history of system configuration information to a CSV file. The following information is output for each host:

host-name, IP-address, host-ID, MAC-address, type, route, comment, deletion-cause, deletion-date/time, creation-date/time, and update-date/time

To output the deletion history to a CSV file:

From the File menu, select Deletion History of System Configuration Information.

The Deletion History of System Configuration Information dialog box appears.

Click Output to CSV File.

The Output Deletion History to CSV File dialog box appears.

Specify a name and location for the file, and then click Save.

The deletion history is saved to the specified file in CSV format.

You can cancel output to the CSV file while it is in progress by clicking Cancel.

6.5.3 Restoring deleted hosts to system configuration information

You can restore a deleted host to the system configuration information based on the deletion history recorded for the host. Note that the host group, ID group, and device information for the deleted host will not be restored.

You cannot restore a host if the same host is registered in the system configuration information, or if the route of the host at the time of its deletion no longer exists. Also, in managing server systems in a hierarchical structure, relay systems and managed computers under management relay servers cannot be restored from the higher manager.

When you restore a deleted host to the system configuration information, the deletion history for the host remains in the Deletion History of System Configuration Information dialog box. You can delete this information as needed.

To restore a deleted host to the system configuration information:

From the File menu, select Deletion History of System Configuration Information.

The Deletion History of System Configuration Information dialog box appears.

Select the host you want to restore, and then click Restore.

The host is restored to the system configuration information.

You can also select multiple hosts and restore them as a batch.

6.5.4 Deleting deletion history

When you use the deletion history of a host to restore it to the system configuration, the deletion history for the host remains in the Deletion History of System Configuration Information dialog box. If deletion history information is allowed to accumulate in the system, the database might run out of disk space. For this reason, we recommend that you periodically delete history information that is no longer required.

To delete deletion history information, select the hosts whose deletion history you no longer want to keep in the Deletion History of System Configuration Information dialog box, and then click Delete. You can also delete the deletion history for all hosts by clicking Delete All.

7 Distributing Software

This chapter explains how to distribute (and remotely install) software.

7.1 Packaging method

This section explains how to package software.

7.1.1 Starting the Packager

Package software by using the Packager (the JP1/ITDM2 Packager window). To output audit logs, start the Packager as a user who has the necessary permissions to update the HKEY_LOCAL_MACHINE registry.

To open the JP1/ITDM2 Packager window:

From the Windows Start menu, select JP1_IT Desktop Management 2 - Agent and then Packager.

The Login (Packager) dialog box appears.

Figure 7‒1: Login (Packager) dialog box

Management Server

Specify the host name or IP address of the management server. If the Packager was previously started by a user who has the necessary permissions to update the HKEY_LOCAL_MACHINE registry, the name of the server to which that user previously connected is displayed by default.

Connection port number

Specify the port number of the management server.

User ID

Specify the user ID of a JP1/IT Desktop Management 2 user account that has both system administration permissions and distribution management permissions.

Password

Specify the password corresponding to the user ID specified in the User ID field.

After specifying the necessary information, click the OK button.

Connection to the managing server is established, and the JP1/ITDM2 Packager window appears.

Figure 7‒2: JP1/ITDM2 Packager window

The JP1/ITDM2 Packager window displays the following sub-windows:

File window

This window is used to select the files to be packaged.

Package window

This window displays the packages stored in a cabinet. You can use this window to delete packages or edit the cabinet.

7.1.2 Packaging procedure

This subsection explains the packaging procedure.

The packaging procedure varies depending on whether you are packaging Hitachi program products from Hitachi Integrated Installer or packaging software that includes software or programs by other companies.

The packaging procedure is explained separately for each of the above scenarios, in the sections that follow.

(1) Procedure for packaging Hitachi program products from Hitachi Integrated Installer

To package Hitachi program products from Hitachi Integrated Installer:

In the File window, select the root directory of the drive where Hitachi Integrated Installer is mounted.

You must select the root directory in the left pane of the File window. If you select a directory other than the root directory, files cannot be packaged.

Select Run and then Packaging.

The Program Product List dialog box appears.

Figure 7‒3: Program Product List dialog box

Select the Hitachi program product (or products) to be packaged, and then click the Package button.

The JP1/ITDM2 Packaging dialog box appears.

Figure 7‒4: JP1/ITDM2 Packaging dialog box

In this dialog box, specify the package details. For details about how to specify settings in the JP1/ITDM2 Packaging dialog box, see 7.2 Specifying package details.

If you selected multiple program products in the Program Product List dialog box, from the Package name drop-down list box, select the program product to be displayed on the Packaging Information page, and specify all package details.

After specifying all of the necessary settings, click the Execute Packaging button.

Packaging starts.

When packaging finishes, a dialog box appears, indicating that packaging is finished.

In the Package window, check that the package has been created.

Figure 7‒5: Package window

The following icon represents a package:

: Package

For details about how to check packages, see 7.1.3 Checking the stored packages.

(2) Procedure for packaging other software programs

To package other (non-Hitachi) software programs:

In the File window, select the files or directories to be packaged.

Multiple files can be selected.

Select Run and then Packaging.

The JP1/ITDM2 Packaging dialog box appears.

The subsequent steps are the same as steps 4 and 5 in (1) above.

You can delete any packages that were created by mistake. To delete a package from the Packager, in the Package window, select the package to be deleted, and then select Edit and then Delete.

You can use the Customize Default Settings dialog box to change the environment (such as the working directory) to be used during packaging, or the default values to be used in the JP1/ITDM2 Packaging dialog box. For details, see 7.2.14 Customizing the packaging environment.

7.1.3 Checking the stored packages

You can check the contents of the stored packages by using the Package window of the Packager.

To check the contents of a package, from the View menu of the Package window, select Items to View and then Package Attribute. The contents of the package you selected are displayed in the right pane of the Package window.

You can check the properties of a package by using the Packager. You can also check the information specified during packaging by using the Details of Attributes dialog box, which can be displayed from the Properties dialog box.

(1) Checking the package properties

Use the following procedure to check the properties of a package that is stored in a cabinet. Note that you cannot view the properties of multiple packages at the same time.

In the Package window, select the package whose properties you want to check.

From the File menu, select Properties.

The xxx Properties dialog box appears (where xxx is the package name).

Click the Details button in the xxx Properties dialog box.

The Details of Attributes dialog box appears, as shown below, and you can view the information specified during packaging.

Figure 7‒6: Details of Attributes dialog box

(2) Notes on checking the package details

If a package is deleted while its properties are being displayed, the attribute details cannot be displayed.

7.1.4 Notes on packaging

Note the following rules when packaging software:

You can create a maximum of 1,296 cabinets. You can register a maximum of 256 packages for each cabinet.

You can package a maximum of 65,531 files or directories at one time. However, if the files or directories to be packaged contain files with short file names, these short file names are also included in the count. For details, see the Note for the KDSF0123-E message in the message list in the manual JP1/IT Desktop Management 2 Messages.

After a package is stored in a cabinet, you cannot rename that package or move it to another cabinet.

The maximum allowable package size is 2 gigabytes. You must package files so that the package size does not exceed 2 gigabytes. If it exceeds 2 gigabytes, you can distribute the package to managed computers by using commands provided by JP1/IT Desktop Management 2. For details, see 7.6.14 Distributing a file larger than 2 gigabytes.

You can only package files whose update date/time or access date/time is from 1970 to 2037.

If some of the files or directories to be packaged are being used by another application, packaging might fail.

You cannot package files in multiple directories at the same time.

When you package another company's software that consists of compressed files (or files in a different format), create a directory, copy the files to be packaged into the directory, and then package the files by specifying the directory.

If you package user data stored on multiple CD-ROMs, copy the data to a hard disk, and then package the data by specifying its directories or files.

If you package a software program (such as another company's software) that must be installed from CD-ROMs in a particular order, post-distribution installation processing fails if the CD-ROMs are inserted in the wrong order.

For another company's software that asks you to enter a CD key during installation, enter the CD key in the Serial number field on the AIT File page.

If cabinets of the same cabinet name have different cabinet IDs, it is difficult to manage each cabinet. To prevent this problem, specify each cabinet name and cabinet ID so that they have a one-to-one correspondence. Note also that there must be a one-to-one correspondence between each package name and package ID within the same cabinet.

Note the following when creating a package for use in UNIX:

For the installation directory, specify no more than 64 single-byte characters (including a drive name and colons).

If you specify more than 64 single-byte characters, the distributed package will be installed directly under the root directory.

Do not specify a generation number, or specify a four-digit generation number. Specifying a generation number of less than four digits causes the distribution of registered packages to fail due to an invalid generation number error.

The names of the files to be packaged and their directories cannot contain spaces, strings enclosed in parentheses (), square brackets [], or curly brackets {}, or the following single-byte symbols: $ ! * ? ; & " ' ' ^ \ | < >.

You cannot perform packaging from the UNIX-version Packager via a relay system. If you do this, the -h option (host name) specified in the packaging command will be disabled, causing packaging to take place on the relay system.

In the Package window, you cannot delete any cabinets or packages registered with the UNIX-version Packager.

When you perform packaging directly from Hitachi Integrated Installer, use the File window of the JP1/ITDM2 Packager window to specify the root directory on the drive where the CD-ROM is mounted. If you do this, a list of products that can be remotely installed is displayed when you select Packaging from the Run menu. From this list, you can select the product to be remotely installed before packaging. If you specify a directory other than the root directory of Hitachi Integrated Installer before packaging, remote installation fails.

Before packaging, decide on package naming rules to ensure that all cabinet IDs, package IDs, versions, and generation numbers are unique within the managing server, relay systems, and management relay servers.

When transferring packages to a relay system or management relay server

You cannot transfer a package of the same cabinet ID, package ID, version, and generation number as another package existing in the relay system or management relay server even if they are different software packages. In this case, the package to be transferred is regarded as already stored.

When performing a remote installation of packages on a managed computer

You cannot install a package of the same package ID, version, and generation number as another package existing in a managed computer (even if they are different software packages), because the package to install is regarded as already installed.

To transfer or install a package in either of the above situations, select the Replace existing package check box in the Change Installation Conditions dialog box.

If JP1/IT Desktop Management 2 has been upgraded from a version earlier than 11-10 and multiple package conditions or software conditions had been set for a package that was registered before version upgrading, the method for judging multiple conditions is Meets one of the conditions. If you want to change the method for judging multiple conditions to Meets all of the conditions, change the method in the Change Installation Conditions dialog box during remote installation (job creation), or register the package again.

When you use packager to package files in a CD-R, if the filenames are not 8.3 filename format, those files that are not 8.3 filename format and some other files might not be included in a package. In this case, copy the files in the CD-R into a hard disk drive, and then package the files in the hard disk drive. Or change the file names (MS-DOS file names) to 8.3 filename format and then package the files again.

The connected network drives might not be displayed when selecting a disk drive in a packager. To display target network drives, from Disk menu, select Drive then Network, and then reallocate the network drive.

When you package Hitachi bundled-product CD-ROMs by using a packager, the product name displayed in a progress bar or a package execution status window during packaging will be the name of the Hitachi program product specified in the program product list. This name might be different from the actual package name that you specified in the JP1/ITDM2 packaging dialog box.

7.2 Specifying package details

You can specify packaging details (such as installation conditions and installation date/time), by using the JP1/ITDM2 Packaging dialog box.

This section explains how to specify settings in the JP1/ITDM2 Packaging dialog box.

7.2.1 Settings in the JP1/ITDM2 Packaging dialog box

The JP1/ITDM2 Packaging dialog box contains the pages shown in Table 7-1 (which pages are displayed differs according to the package type). If you perform packaging without specifying any of the necessary items, an error message appears.

Use either of the following methods to package another company's software:

Using both AIT files and program product ID files

Omitting AIT files

The following explanations are based on method 1. For details about packaging based on method 2, see 7.2.13 Packaging another company's software.

Table 7‒1: Pages in the JP1/ITDM2 Packaging dialog box

Page name

Package type

Hitachi program product

Other companies' software

User program and data

Packaging Information

Y

Y

Y

System Conditions

Y

Y

Y

Software Conditions

Y

Y

Y

Package Conditions

Y

Y

Y

File Properties

N

Y

Y

Schedule

Y

Y

Y

Installation Method

Y

Y

Y

Options

Y

Y

Y

External Program

Y

Y

Y

AIT File Settings

N

Y#1

N

Select Components

Y#2

N

N

Legend:

Y: Displayed, N: Not displayed

#1

This page is displayed when you use AIT files.

#2

This page is displayed when you package JP1/IT Desktop Management 2 - Agent by using the Packager.

7.2.2 Packaging Information page

On this page, specify basic information about packages, such as package names, and the cabinets for saving packages.

Figure 7‒7: Packaging Information page

(1) Package information

In this area, set up the information for identifying a package. Specify a package with a package ID, version, and generation number that are different from those of any existing packages.

Tip

We recommend that you name packages so that they are easy to identify and avoid using the same name for different packages.

If you select Hitachi program products or Other companies' software for Package type, particular values are automatically displayed in the Package name, Package ID, Version/revision, and Generation drop-down lists, and basically you cannot change these values. If no values are displayed in these drop-down lists, it is assumed that you have selected User programs and data.

Package name (mandatory)

If you select User programs and data for Package type, specify the package name of the user program or data to be packaged. For package names, you can specify a maximum of 50 single-byte characters (or 25 double-byte characters). You cannot use the \ character.

If you select Hitachi program products for Package type, you can change the package name that is displayed. You can change the package name to any name that is easy for end users to understand or is otherwise convenient.

The term package name corresponds to program name in the UNIX version of JP1/IT Desktop Management 2 - Agent.

Package ID (mandatory)

If you select User programs and data for Package type, specify the ID of the package. Specify from 1 to 44 single-byte alphanumeric characters, hyphens (-), or underscores (_). Alphabetic characters must be in uppercase.

The term package ID corresponds to package ID in the UNIX version of JP1/IT Desktop Management 2 - Agent.

Do not specify the following strings at the beginning of a package ID:

DPT-

SPC-

Version/revision (mandatory)

If you select User programs and data for Package type, specify the version of the package by using a maximum of six alphanumeric characters or forward slashes (/). Alphabetic characters must be in uppercase.

Generation

If you select User programs and data for Package type, you can also assign a generation number in addition to a version. Specify a maximum of four alphanumeric characters (alphabetic characters must be in uppercase). Packages with the same version can be classified by specifying a generation number.

(2) Package type (mandatory)

Select the type of software to be packaged. If the software to be packaged is a Hitachi program product or another company's software, the corresponding option (Hitachi program products or Other companies' software) is automatically selected. In other cases, it is assumed that you have selected User programs and data.

(3) Cabinet for saving packages

In this area, specify a cabinet for saving packages. You cannot delete your created packages from the Packager.

Cabinet name

In this drop-down list, specify a unique cabinet name. You can specify a maximum of 32 single-byte characters (or 16 double-byte characters) for a cabinet name. You cannot use the following characters: \, /, *, ", :, ; and space.

You can also select an existing cabinet name from the drop-down list.

Cabinet ID (mandatory)

In this drop-down list, specify a unique ID for each cabinet by using two single-byte alphanumeric characters (alphabetic characters must be in uppercase). You must specify a cabinet ID when setting a new cabinet name. If you select an existing cabinet name, the corresponding cabinet ID automatically appears.

JP1/IT Desktop Management 2 identifies each cabinet according to the cabinet ID.

The term cabinet ID corresponds to cabinet ID in the UNIX version of JP1/IT Desktop Management 2 - Agent. You can specify the same cabinet ID for Windows and UNIX. In this case, these cabinets are regarded as different cabinets even though their cabinet IDs are identical.

7.2.3 System Conditions page

On this page, you can specify the installation target directory to be used during remote installation, and the hardware requirements for a computer where remote installation is to be performed.

Figure 7‒8: System Conditions page

(1) Installation target directory (mandatory)

In this area, specify the directory where the package is to be remotely installed.

Drive

The default target drive for remote installation is displayed in this drop-down list. You can select any drive, but must not specify a network drive in background installation mode.

For the drive, you can specify from A: to Z:, from 1: to 9:, or None. The number indicates the sequential number of the hard disk drive in a PC when drives are arranged in alphabetical order. For example, if the A drive of a PC is a DVD-ROM drive, and the C drive is a hard disk drive, 1: means the C drive. Likewise, if the A drive of another PC is a hard disk drive, 1: means the A drive. Therefore, if you specify 1: for the target drive, it means the C drive in the case of the first PC above, or the A drive in the case of the second PC above. Specify None if you want to specify a directory as a UNC path name.

Specify a value other than None for the drive in the following case:

When the distribution destination is a UNIX system#

When the package type is Hitachi program products or other companies' software

#: When the package is distributed, the specified drive is ignored and distribution takes place according to the directory specification.

Directory

The default target directory for remote installation is displayed in this drop-down list. Specify the path to a desired directory by using a string starting with the \ character. When the distribution destination is a Windows system, you can specify up to 128 single-byte characters including a drive name. When the distribution destination is a UNIX system, you can specify up to 64 single-byte characters.

If you want to specify a UNC path name in the Directory drop-down list, specify None in the Drive drop-down list. For example, if you perform a remote installation in the \APP\PROG directory that is declared as a shared directory on the SRV010 server, specify None in the Drive drop-down list, and \\SRV010\APP\PROG in the Directory drop-down list.

When specifying a directory, note the following rules:

The path to an installation target directory 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. General users cannot specify this string.

If you package a Hitachi program product, do not use semicolons (;), double quotation marks ("), or whitespaces in the path to a directory.

In background installation mode, if you do not have access permissions and try to perform a remote installation in a directory, installation will fail.

If you specify a path to a non-existent directory, a directory is created on the PC where remote installation is performed.

Note

When you perform packaging with the UNIX-version Packager, you can specify only directories.

(2) System conditions

In this area, specify the hardware requirements for a computer where remote installation is to be performed.

Creating system conditions

Specify the desired system conditions in this area. If you specify appropriate values in the Item, Comparison, and Value boxes, and then click the Add button, a conditional expression based on the specified values appears in the lower frame. A package is remotely installed on systems that meet the conditions specified in this area. You can specify multiple conditional expressions. If you specify multiple conditional expressions, a package is installed only when all the conditions are met.

Item

You can select an item (Free hard disk space, Installed RAM, or OS version).

Comparison

Comparison values that can be selected vary with the selected item. You can select a comparison value (such as =, >=, or <>) from the list. You can use only one comparison value in a single conditional expression.

Values (Drive, Size, and OS)

Values that can be specified vary according to the selected item. You can select a value from the list, or enter a value directly into the text box.

If you select Free hard disk space or Installed RAM for Item, the upper limit value in Size is 32,767.

If you select OS version for Item, the OSs to be compared are determined according to the values specified in Comparison and OS. The table below lists the numbers that represent each OS, and the OSs that can be specified. The smaller the number, the older the OS version.

Numbers that represents each OS

OS that can be specified

15

Windows11

14

WindowsServer2022

13

WindowsServer2019

12

WindowsServer2016

11

Windows10

10

WindowsServer2012R2

9

Windows8.1

8

WindowsServer2012

7

Windows8

6

WindowsServer2008R2

5

Windows7

4

WindowsServer2008

3

WindowsVista

2

WindowsServer2003

1

WindowsXP

For example, if you specify WindowsServer2003 for OS and < for Comparison, the only OS that meets the specified conditions is Windows XP, which is older than Windows Server 2003.

7.2.4 Software Conditions page

On this page, specify conditions for the target software or update program for remote installation. You can specify a maximum of 100 conditions. You can also select a judging method when multiple conditions are specified.

You can specify the following two items for conditions:

Target

In this area, specify the software or update program to be used as criteria.

Conditions

In this area, specify the installation status of the specified software or update program.

Figure 7‒9: Software Conditions page

(1) Target

In this area, enter the software name or the document number of the update program to be used as a condition.

Remote installation targets software that exactly matches the specified software name. You can enter a maximum of 2,048 bytes of characters for Software name.

You can also specify a version as part of the document number of an update program. For example, if remote installation targets an update program with document number KB2536276 and version v2, enter KB2536276-v2.

(2) Conditions

In this area, specify whether the target software or update program has already been installed, as well as version conditions.

Uninstalled

Performs a remote installation only if the target software or update program does not exist on the installation target computer.

Installed

Performs a remote installation only if the target software or update program already exists on the installation target computer. Specify the conditions for the target software by entering appropriate values for Comparison and Version.

Comparison

In this drop-down list, select an appropriate operator according to the specified version.

For example, if you select <, any software or update programs whose version is older than the specified version are remotely installed on the installation target computer.

Version

Enter the version to be compared.

The following explains how the specified version is compared when a software name is specified for Target:

If you specify a software name for Target, the value specified for Version is evaluated by splitting it into a major version, minor version, revision, and build. You can use a period (.), comma (,), or hyphen (-) to separate each version component. For example, if you enter 12.0.6.100 for Version, it means that the major version is 12, the minor version is 0, the revision is 6, and the build is 100. The value specified for Version is compared with the version of each software program installed on the target computer, according to each component of the specified version.

Note also that versions are compared by using a string where the number of digits is adjusted with zeros (0). For example, the specified conditions are regarded as met in the following situation:

Operator specified in the Comparison drop-down list: =

Value specified for Version: 0100

Version of the software installed on the target computer: 100

Note

If the specified software is a JP1 product and the specified version is in Hitachi PP format, the software version is a character comparison from the beginning without supplementing the number obtained with "0".

Specifiable characters (being compared) are prioritized as follows: single-byte alphabetic characters (A to Z) > single-byte numbers (0 to 9) > forward slashes (/) > single-byte spaces.

The JP1 product are those described as follows:

The beginning of the software name is one of "JP1/ (excluding JP1/TELstaff)", "Performance Management - ", "Network Node Manager i", "Navigation Platform - ", "SNMP System Observer", or "Extensible SNMP Agent".

While the Hitachi PP format version are described as follows:

A 4- to 6-character string in the VVRRSS format.

VVRR is a half-width number.

SS is single-byte alphanumeric characters. (Slashes only allowed at the beginning of SS)

For example, if "1200", "120003", "1100/A", "1050A", "1200SA", "1200A", etc. are specified, it is classified as Hitachi PP format.

(3) Judgment of multiple conditions

Select a judging method when multiple conditions are specified. The default is Meets one of the conditions.

Meets one of the conditions

The package is installed if any one of the specified conditions is satisfied.

Meets all of the conditions

The package is installed only if all the conditions are satisfied.

7.2.5 Package Conditions page

On this page, specify conditions for the target package for remote installation. You can specify multiple conditions. You can also select a judging method when multiple conditions are specified.

You can specify either of the following conditions:

Install if the version and generation number of the specified package match the specified conditions.

Install if the specified package has not been installed.

Because the specified conditions are evaluated immediately before installation, the package is downloaded to the managed computers, regardless of whether the specified conditions are met.

Figure 7‒10: Package Conditions page

(1) Package conditions

In this area, create a conditional expression for the target package for remote installation. If you specify conditions, and then click the Add button, a conditional expression is displayed and enabled in the list.

(a) Package name/package ID

In this area, select whether to specify the target package as a package name or package ID. The default is Package name.

Then, specify a package name or package ID in the lower text box. You can also select a package name or package ID from the list. You can only specify a package name (or package ID) of a package remotely installed with JP1/IT Desktop Management 2 or a software package collected by a Get software information from computer (UNIX) job. You cannot use wildcard characters.

(b) Conditions

In this area, specify conditions such as the version, and whether the package has been installed.

Uninstalled

Performs a remote installation only if the specified package does not exist on the installation target computer.

Installed

Performs a remote installation only if the specified package exists on the installation target computer. Specify the conditions for the target package by entering appropriate values for Comparison, Version, and Generation.

Comparison

In this drop-down list, select an appropriate operator according to the version and generation number to be specified next. For example, if you select <, remote installation is performed if any package whose version is older than the version to be specified next exists on the installation target computer.

Version

Select or enter the version to be compared.

Generation

Select or enter the generation number to be compared. If there is no generation number, no setting is required.

For example, if you specify the condition PROGRAM<0200, remote installation is performed on computers that contain any PROGRAM whose version is older than 0200.

When you specify a version and generation number as conditions in the Package Conditions page, each specified string is compared sequentially, starting from the beginning of each string. Specifiable characters (being compared) are prioritized as follows: single-byte alphabetic characters (A to Z) > single-byte numbers (0 to 9) > forward slashes (/) > single-byte spaces. If you select <, <=, >, or >= as a comparison value, specify a version and generation number so that the number of digits is the same as the version and generation number of the package to be compared. For example, if you perform a remote installation in an environment where the package PROGRAM with version 0300 and generation number 0000 exists, specify PROGRAM>0300 0000 (rather than PROGRAM>3 0) to align the number of digits.

(2) Judgment of multiple conditions

Select a judging method when multiple conditions are specified. The default is Meets one of the conditions.

Meets one of the conditions

The package is installed if any one of the specified conditions is satisfied.

Meets all of the conditions

The package is installed only if all the conditions are satisfied.

7.2.6 File Properties page

On this page, select how to determine the access permissions and owner of files after remote installation. The default is Use the permissions and owner of the installation directory. This page appears only when the Package type is set to Other companies' software or User programs and data.

Figure 7‒11: File Properties page

Use the permissions and owner of the installation directory

Creates new files according to the access permissions of the remote installation target directory for a package. Moreover, if a directory to be packaged already exists in the remote installation target directory, it inherits the access permissions and owner of the existing directory.

To enable this setting when the remote installation target is an agent for UNIX, you must create a file for enabling file attributes on the agent for UNIX. For details about how to create files for enabling file attributes, see the JP1/IT Desktop Management 2 - Agent Description and User's Guide (For UNIX Systems).

If you do not create a file for enabling file attributes, the system will set the same file attributes as when you select Same as the JP1/ITDM2 standard values (access permission/owner).

Same as the JP1/ITDM2 standard values (access permission/owner)

Sets the standard access permissions and owner of JP1/IT Desktop Management 2. Values are set as below.

When the remote installation target is Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Server 2012, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP:

Folder and file access permissions

Administrators: Full control

SYSTEM: Full control

Everyone: Read and execution

Folder and file owner: Administrators

When the remote installation target is UNIX:

File mode: 700 (only users with superuser privileges can read and write)

Owner: root

Group: sys

Use the permissions and owner of the directory on the packager

Restores the access permissions and owner of the packaging source to the installation target.

When the remote installation target is an agent for UNIX, this setting is disabled. If you specify this setting, the system will set the same file attributes as when you select Same as the JP1/ITDM2 standard values (access permission/owner).

Important

If you want to set the Use the permissions and owner of the directory on the packager option at the installation target, the owner of the files and directories to be packaged must be Administrators. Even for Windows Server 2019, Windows Server 2016, Windows Server 2012, Windows Server 2008, and Windows Server 2003, make sure that the owner of files and directories is Administrators before packaging.

7.2.7 Schedule page

On this page, specify how long a remotely installed package can be stored on a relay system. You must also specify the date/time and execution timing of a remote installation to be performed on a managed computer.

When you are using the Send package, allow client users to choose job, an installation date/time and execution timing are ignored on a managed computer even if you specify them.

Figure 7‒12: Schedule page

(1) Expiration of package storage at the relay computer

If you specify a time limit for package storage on a relay system or management relay server, select the Expiration of package storage at the relay computer check box, and specify a date. For the year, specify the last two digits (if you specify a number from 95 to 99, the year is regarded as the 1900s). The upper limit for the package storage period is December 31, 2094. When the specified time limit is reached, the package stored in the relay system or management relay server is automatically deleted. If you distribute a package that has already expired (or expires on the current day), it is deleted on the following day.

If you clear the check box, the package is stored for 90 days by default. You can change the default storage period by using the Customize Default Settings dialog box. For details, see 7.2.14 Customizing the packaging environment.

In actual operation, a relay system or management relay server needs to store a package until the package finishes being installed on all the computers under the relay system or management relay server. For example, if three weeks are required to distribute and install the package, specify a date at least three weeks in advance.

(2) Installation date/time

If you specify the date and time that you will install a package on a managed computer, select the Installation date/time check box, and specify the date and time. For the year, specify the last two digits.

If you use background installation mode (in which just copying files finishes installing them), installation processing is automatically performed if the target PC for remote installation is running.

(3) Execution timing

In this drop-down list, select the timing of installing the package on the managed computer.

If the same software is already installed on the managed computer (such as when upgrading a software version), remote installation fails if that software is running when remote installation is executed. To prevent such a problem, we recommend that you select Install when the system starts for the installation timing. This also reduces the impact of remote installation on user jobs.

Note that if you select Install when the system starts or Install now (without an installation date/time specified), there is a risk that users might need to hold their jobs. If you want to prevent users from holding their jobs, select Install now, and specify the installation date/time. Specify a date and time when users are less affected by remote installation (while considering the possibility that user jobs might need to be temporarily stopped during installation processing).

Install when the system starts

Installs the package when the system on the computer starts. If you specify an installation date and time, the package is installed when the system starts for the first time after the specified date and time.

Note that the timing of distribution and installation differs according to the settings of the polling-related items in agent configurations. For details about the relationship between polling settings and the timing of distribution and installation, see the description of agent configurations in the JP1/IT Desktop Management 2 Configuration Guide.

If you perform a remote installation of software that starts at system startup, remote installation and the software might start at the same time, thereby causing the installation to fail. To prevent this problem, move the shortcut of the software registered for the Startup group on the managed computer to the ITDM2_Startup folder. You can use agent configurations to create an ITDM2_Startup folder and automatically move a shortcut. For details about how to move a shortcut to the ITDM2_Startup folder, see the description of agent configurations in the JP1/IT Desktop Management 2 Configuration Guide.

Install now

Installs the package at system startup on the computer. If you specify an installation date and time, the package is installed at the specified date and time. However, if the computer is not running at the specified date and time, the package is installed next time the system starts.

When System Stops

Installs the package when the system on the computer stops. If you specify an installation date and time, the package is installed when the system terminates for the first time after the specified date and time.

You can specify this item in the Change Installation Conditions dialog box of the Remote Install Manager when you install a package on an agent for UNIX. If you specify this item for a package to be installed on a Windows agent, the job will result in an error.

7.2.8 Installation Method page

On this page, specify an installation method that matches the installer type of the software to be installed. If you install a Hitachi program product, select a new installation, or an installation upgrade.

Figure 7‒13: Installation Method page

(1) Installation mode

For the installation mode, select GUI installation mode or Background installation mode.

If you select Hitachi program products or Other companies' software for Package type, GUI installation mode is always selected.

GUI installation mode

This installation mode uses a particular installer (such as an interactive installer). Use this mode if the installer uses a Graphics Device Interface (GDI) as an API, even though it does not have a GUI.

If you use the GUI installation mode to perform remote installation of software that requires user intervention on the screen, disable password protection on the installation target PC before installation. If the installation target PC is password-protected (for example, a dialog box is displayed asking you to simultaneously press the Ctrl+Alt+Delete key), installation of the software is not possible because you cannot interact with the screen. However, if you perform remote installation of a Hitachi program product that supports remote installation, such software does not require user intervention and can be installed even if the PC is password-protected.

Background installation mode

This installation mode does not use a particular installer. Use this mode to install files simply by copying them. Remote installation can be performed only if Windows is running, even if the user who installed JP1/IT Desktop Management 2 - Agent is not currently logged on.

(2) Hitachi program product installation

In this area, select whether to perform a new installation or an installation upgrade if you have selected Hitachi program products for Package type. If you select Reinstallation, you cannot change the installation target drive or directory.

New installation

Select this option when newly installing a program product.

Reinstallation

Select this option when upgrading a program product that has already been installed.

7.2.9 Options page

On this page, specify remote installation options.

Figure 7‒14: Options page

Compress package data

Select this check box to compress software before packaging. Compressed packages are automatically decompressed during remote installation. By default, this check box is not selected.

If you compress packages, file transfers become faster, and the amount of space required for storing the packages in a cabinet can be saved. However, it takes some time to compress and decompress packages during packaging and remote installation.

When you compress a package, you can select either of the following compression methods. The default is For Windows.

For Windows

For Windows can compress package data more than UNIX Shared. However, this method cannot compress package data to be distributed to agents for UNIX.

UNIX Shared

UNIX Shared does not compress package data as efficiently as For Windows, but can compress package data to be distributed to agents for UNIX.

Compression rates differ according to the package data. The following table lists examples of approximate compression (%) for a given size of uncompressed data:

Compression method

100 megabytes of text data

145 megabytes of program data

For Windows

Approx. 1%

Approx. 47%

UNIX Shared

Approx. 45%

Approx. 71%

Restore old version when upgrade failed

You can use this check box only if you select User programs and data for Package type. If you select this check box, the previous version of the software at the remote installation target is backed up when the software is upgraded. If remote installation fails, the previous version of the software is restored from the backup. By default, this check box is not selected.

If you specify an external program to be started immediately before remote installation, the software is backed up after the external program is started. Similarly, if you specify an external program to be started if an installation error occurs, the software is restored after the external program is started.

A backup file storage period is specified for software that is packaged from the UNIX-version Packager. Even if remote installation fails and then restoration also fails, you can retry restoration processing from the managed computer. For details about how to check backup files and retry restoration processing, see 12.5 Managing backup files.

This check box is equivalent to Restore old version when upgrade failed in the Change Installation Conditions dialog box.

Restart computer after installation

With this check box, specify whether to restart the managed computer automatically after a package is installed. By default, this check box is not selected. If you select this check box, a confirmation dialog box asking whether to restart the system is displayed on the managed computer after installation, and the system is restarted after the specified time has elapsed. The display time period of the confirmation dialog box is specified in the User notification settings option in agent configuration.

You can also specify Follow the response of the user in the dialog box that instructs the user to shut down or restart the computer for the display time period of the confirmation dialog box. In this case, the system is not restarted until a user responds.

Only managed computers (except agents for UNIX) can be restarted automatically. Relay systems and management relay servers cannot be restarted automatically even if you install a package that specifies a restart after installation.

When restarting the computer automatically, note the following:

Do not select the Restart computer after installation check box when performing a remote installation of JP1/IT Desktop Management 2 - Agent. Doing so might fail to complete the remote installation successfully.

If you use a single job to install multiple packages that specify a restart of the computer after installation, the computer is restarted automatically after all the packages are installed.

If computer shutdown by the Client Control facility is specified in a job that distributes a package that specifies a restart after installation, the computer is shut down after the job has finished.

Multiple jobs (including a job that distributes a package that specifies a restart after installation and a job that specifies shutdown by the Client Control facility) might be successively executed on the managed computer. In such a case, the computer is shut down after all the jobs have finished.

If a package that specifies a restart after installation is installed by the Package Setup Manager on the agent, the computer is not restarted until a user responds. (The behavior is the same as when Follow the response of the user in the dialog box that instructs the user to shut down or restart the computer is specified.) This is true even if the display time period of the confirmation dialog box is specified in agent configurations.

If a Windows computer is password-protected and a screen-saver is enabled, the computer cannot be restarted automatically.

If a file is being edited when a package that specifies a restart after installation is installed, the computer cannot be restarted automatically.

If remote installation of a package that specifies a restart after installation is performed from the host system, the specified behavior cannot be performed in the following logon status:

Before logon

In this situation, if you select Automatically start if no response is received from the user within the specified period in agent configurations, the computer is restarted without displaying a confirmation dialog box. If you select Follow the response of the user in the dialog box that instructs the user to shut down or restart the computer, the computer cannot be restarted.

Here, a remote installation of a package from the host system refers to any cases other than installing a package from an agent by using the Package Setup Manager.

Display processing message

Specify whether to display processing message dialog boxes on the managed computer during package installation. (Processing message dialog boxes are dialog boxes displayed during downloading and during installation.) You can select one of the following options:

According to the agent settings

Determines the behavior of download processing message dialog boxes and installation processing message dialog boxes according to the settings in Display settings for dialog boxes indicating that a job is being progressed under Job settings in the agent configurations. Whether the standard dialog boxes for the program or the dialog boxes specified in user-created programs are displayed as processing message dialog boxes also follows the settings in Display settings for dialog boxes indicating that a job is being progressed.

Show

Displays download processing message dialog boxes and installation processing message dialog boxes, regardless of the settings in Display settings for dialog boxes indicating that a job is being progressed under Job settings in the agent configurations.

Whether the standard dialog boxes for the program or the dialog boxes specified in user-created programs are displayed as processing message dialog boxes also follows the settings in Display settings for dialog boxes indicating that a job is being progressed.

Hide

Hides download processing message dialog boxes and installation processing message dialog boxes, regardless of the settings in Display settings for dialog boxes indicating that a job is being progressed under Job settings in the agent configurations.

The following table describes whether processing message dialog boxes are displayed when Display settings for dialog boxes indicating that a job is being progressed and Display processing message are specified:

Display settings for dialog boxes indicating that a job is being progressed

Display processing message (package settings)

According to the agent settings

Show

Hide

Show

Y

Y

N

Hide

N

Y

N

Legend:

Y: Display an applicable dialog box

N: Do not display an applicable dialog box

If you specify Show for Display processing message, whether the installation processing message dialog box is displayed on top of other windows follows the settings in Display settings for dialog boxes indicating that a job is being progressed.

Download priority

Select the package priority from the drop-down list. The default is 5.

For details about package priority, see 7.6.16 Priority distribution of packages.

Message displayed at the target client before starting installation

In this area, enter a description to be attached to the package, in either of the following ways:

Enter a description directly in the Message text text box.

For a description, enter a maximum of 30,000 single-byte characters (or 15,000 double-byte characters).

Click the Copy from File button and load a text file.

The maximum size of a text file is 30,000 bytes.

This description is useful when you distribute a package by using the Send package, allow client users to choose job. You can view this description from the managed computer when you use the Package Setup Manager to select the package to be installed. Write a description of any information you want users to know before installation, such as package contents and installation methods.

This item is equivalent to Message displayed at the target client before starting installation in the Change Installation Conditions dialog box.

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

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

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 the GUI in Windows Server 2019, Windows Server 2016, Windows 10, 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 the 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 agent job, the Windows Interactive Services Detection dialog box appears on the task bar.

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.

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

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 7‒17: The External Program Options dialog box displayed by clicking the Details button to the right of "At installation error"

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.

(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

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

Do not use characters that have special meanings in shell programs, such as <, >, |, &, and $.

External programs cannot be started when an installation error occurs.

The path specification method used to start external programs immediately before and after installation differs depending on whether Installation date/time is specified on the Schedule page. If the path specification method is incorrect, packaging and jobs can be executed, but external programs will not be started on the destination agents for UNIX. In this case, note that jobs do not produce an error but terminate normally.

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

Start immediately before installation

Start immediately 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 postprocessing 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 the external program to be started immediately before installation, specify no more than 60 single-byte characters for a path to this program.

If you specify only the external program to be started immediately after installation, specify no more than 64 single-byte characters for a path to this program.

If you specify two external programs to be started immediately before and after installation, specify no more than 60 single-byte characters for a path to both 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.

7.2.11 AIT File Settings page

Set up this page when using AIT files during remote installation. This page is displayed only when the package type is Other companies' software and AIT files are used.

Figure 7‒18: AIT File Settings page

Wait for the completion of AIT file processing

With this check box, specify whether to monitor responses from installation processing that uses AIT files.

If the user responds to the dialog boxes or operates the keyboard or mouse during installation, the installer windows are not displayed as expected by the AIT file, thereby preventing remote installation based on the AIT file from proceeding. In such cases, to prevent installation from being left halfway, the installation can be suspended if there is no response within a certain period of time.

Time-out

If you have selected the Wait for the completion of AIT file processing check box, in this field, specify the upper limit for the time to monitor responses from the AIT file. Specify from 1 to 21,600 seconds (360 minutes or 6 hours). Normally, specify a value that is approximately three times the time required to install the software to be distributed. The default is 5 minutes.

Organization

This text box is optional. Enter the company name of the user that owns the software by using a maximum of 80 single-byte characters (or a maximum of 40 double-byte characters).

User name

This text box is optional. Enter the user name of the user that owns the software by using a maximum of 40 single-byte characters (or a maximum of 20 double-byte characters).

Serial number

Enter the serial number of the software. If you package another company's software that requires a CD key during installation, enter the CD key in this text box.

Icon group

Specify a folder name to be registered in the Windows Start menu on the user's computer.

7.2.12 Select Components page

This page is displayed when you package JP1/IT Desktop Management 2 - Agent. If you clear the check boxes for components not to be installed, these components are not included in the package. This way, you can reduce the size of the package.

Figure 7‒19: Select Components page

The following components of JP1/IT Desktop Management 2 - Agent can be subject to remote installation:

Agent

Relay System

Packager

Remote Control Agent

Automatic Installation Tool

If you perform a remote installation of your created package by selecting components, existing components are overwrite-installed regardless of which components are packaged.

7.2.13 Packaging another company's software

You can package another company's software by the following methods:

Using AIT files and program product ID files

Omitting AIT files

In an earlier part of this chapter, the method for setting up the JP1/ITDM2 Packaging dialog box is explained based on method 1 above, and so this subsection explains only method 2.

(1) Omitting AIT files

For the distribution of software with an installer, JP1/IT Desktop Management 2 normally distributes a package provided with an AIT file that defines an installer operation procedure. This enables a remote installation to be performed on the managed computer without interfering with the user.

On the other hand, there are some cases where the user prefers to install a package manually on the computer rather than performing a remote installation automatically. This operation method does not require AIT files, as described below.

(a) Packaging another company's software without using AIT files

To package another company's software without using AIT files:

If necessary, create an installation definition file.

Start the Packager to package and register another company's software.

Start the Remote Install Manager on the manager side, execute the package (registered in Step 2, above) as the Send package, allow client users to choose job on the computer where the package is to be installed.

Start the Package Setup Manager on the managed computer, select the target package from the Package Setup Manager window, and perform an installation.

Because only Manual is enabled for Installation method, the user must install the package by operating the installer.

(b) Note

If you distribute a package that does not use AIT files, you must run the Send package, allow client users to choose job and install the package from the Package Setup Manager. Specifying the Install package job results in an error.

(2) Installation definition file

The installation definition file contains information defining the selectable setup modes and the order in which floppy disks are to be inserted into the floppy drive.

In the Packager's machine, create the installation definition file (INSTABL.DEF) in the following directory:

Packager-installation-directory\DMPRM\INSTABL.DEF

(a) Format

The installation definition file must be in the following format. You must place one or more spaces or Tab code entries on the left and right of the equal sign (=).

[Package]
PackageID = package-ID
Maker = maker-name
Version = version
Product = package-name
InstallerName = installer-name
InstallKind = number.setup-mode
InstallDrive = installation-drive
InstallDirectory = installation-directory
EUser = owner-user-name
ECompany = owner-company-name
SetFdNumber = floppy-disk-insertion-sequence
RecordFileDirectory = recorder-file-directory
RecordFileVersion = Visual-Test-version
[Package]
:
:

In the installation definition file, you must begin definitions of each software product with Package entry. When there is more than one software program, you must repeat the Package entry as many times as necessary to cover all the software products.

The items under Package must be defined in attribute name = attribute value format.

You do not have to define all the items. Remember, however, that some of them must always be defined. The attribute name entries are described below.

PackageID = package-ID (Required)

Specify the package ID. The specifiable characters are A to Z , -, and 0 to 9.

You can specify a package ID length of 1 to 44 characters.

Maker = maker-name

Specify the software manufacturer's name. You can use any characters.

The length of the name can be from 1 to 30 characters.

Version = version (Required)

Specify the software version. The acceptable characters are A to Z, 0 to 9, and slashes (/). Make a version number entry consisting of 1 to 6 characters.

Note that the generation number is fixed to 0000.

Product = package-name (Required)

Specify the package name. You can use any characters.

The length of the name can be from 1 to 50 characters.

InstallerName = installer-name (Required)

Specify the name of the installation program (installer) that you will use to install the software. You can use any characters.

The length of the name can be from 1 to 256 characters.

When the software is distributed on a CD-ROM, attach a number sign (#) to the beginning of the installation program name.

Example:

-When using floppy disks

InstallerName = INSTALL.EXE

-When using a CD-ROM

InstallerName = #INSTALL.EXE

InstallKind = number.setup-mode

Specify the selectable setup modes (installation modes) and their numbers in the following format. This designation entry cannot exceed 256 characters in length.

1.setup-mode-1, [2.setup-mode-2, ... n.setup-mode-n]

In the n position, enter numerals, in ascending order, or beginning with 1.

Example:

InstallKind = 1.full installation, 2.minimum installation

InstallDrive = installation-drive (Required)

Specify the name of the drive on which the software is to be installed.

The acceptable characters are A to Z, a to z, and 1 to 9. If you enter 1, it denotes the first hard disk drive. The name can be only one character in length.

InstallDirectory = installation-directory (Required)

Enter a pathname beginning with a backslash (\) to specify the directory into which the software is to be installed. You can use any characters. The acceptable pathname length is from 1 to 256 characters.

EUser = owner-user-name

Specify the name of the user who owns the software. You can use any alphanumeric characters. The name can be 1 to 40 characters in length.

ECompany = owner-company-name

Specify the name of the organization that owns the software. You can use any alphanumeric characters. The name can be 1 to 40 characters in length.

SetFdNumber = floppy-disk-insertion-sequence (Required)

Use the following format to specify the order in which floppy disks are to be inserted into the floppy drive.

The character string to be specified can have up to 256 characters.

If the software is distributed on CD-ROM, ensure that SetFdNumber = 0.

SetFdNumber = number [,number, ...]

Example:

If the first, second, and fifth floppy disks are to be inserted in the stated order, make the following entry.

SetFdNumber = 1,2,5

Example:

If the InstallKind item is defined, attach the setup mode number to the end of SetFdNumber in _number format.

SetFdNumber_1 = 1,2,3,4,5

SetFdNumber_2 = 1,2,5

RecordFileDirectory = recorder-file-directory

Specify the directory in which the recorder file exists. This entry must contain the drive name. You can use any characters. The entry can be from 1 to 256 characters in length. When you omit this attribute name, you must specify a Send package, allow client to choose job when executing the job and then install from the Package Setup Manager window on the client. If you specify an Install package job, the job will end with an error.

RecordFileVersion = Visual-Test-version (Required)

Specify the version of Visual Test you are using to create the recorder files as follows:

RecordFileVersion = 6

(b) Installation definition file example

The following shows an example of an installation definition file.

[Package]
PackageID = ACROBATREADER405
Version = 0405
Product = Acrobat Reader 4.0
InstallerName = #Ar405jpn.exe
SetFdNumber = 0
RecordFileDirectory = c:\recod\ar40
RecordFileVersion = 6

7.2.14 Customizing the packaging environment

You can specify the following packaging environment settings according to user operations:

Displaying or hiding processing message dialog boxes

Default values for the settings in the JP1/ITDM2 Packaging dialog box

Working directory

Audit log output

You can specify this setting only when the Packager and JP1/IT Desktop Management 2 - Manager are located on different computers.

You can specify these packaging environment settings in the Customize Default Settings dialog box, which is displayed by selecting Customize default settings from the Options menu in the JP1/ITDM2 Packager window.

To customize the packaging environment, you need permissions to access the registry HKEY_LOCAL_MACHINE.

(1) Processing Message page

On this page, you can specify whether to display processing message dialog boxes during packaging processing. You can separately specify whether to display a dialog box indicating connection with the host system and whether to display a dialog box indicating packaging in progress. By default, both processing message dialog boxes are displayed.

Figure 7‒20: Processing Message page

(2) Package Attributes page

On this page, you can specify the default values for each item in the JP1/ITDM2 Packaging dialog box.

Setting item on the Package Attributes page displays the items corresponding to the page names in the JP1/ITDM2 Packaging dialog box. Select a desired item for Setting item, and then specify the default values to be used in the JP1/ITDM2 Packaging dialog box on the right side of the page.

(a) Packaging information

You can specify the default values for the Package name, Package ID, Version/revision, and Generation drop-down lists in the JP1/ITDM2 Packaging dialog box. These settings are valid only when you select User programs and data for Package type. By default, none of the check boxes are selected.

Figure 7‒21: Package Attributes page (Packaging information)

Package name/ID

Specify the default values for the Package name and Package ID drop-down list.

Acquire from file/folder name

If you select this option, the folder or file name you selected during packaging is used as the default value in the Package name and Package ID drop-down lists. All the alphabetic characters in the package ID are changed to uppercase letters.

If you selected a file name during packaging, the file name excluding the period and extension is used as the default package name and package ID. If you selected multiple folders or files during packaging, the first folder or file name is used. Any characters that exceed the maximum allowable number of characters are deleted. Any prohibited characters and spaces are deleted. If the file or folder name consists of only prohibited characters, the default package name and package ID are left blank.

Acquire from date when packaging is done

If you select this option, the date and time of packaging is used as the default value in the Package name and Package ID drop-down lists. This means that the default package name and package ID are identical.

You can select a desired date/time format from the Format drop-down list. YYYY (or YY), MM, DD, HH, MM, and SS represent the year, month, day, hour, minute, and second, respectively. If any value of the year, month, day, hour, minute, and second is a single-digit number, 0 is added in front of the value to make it a two-digit number.

Version

Specify the default value to be used in the Version/revision drop-down list.

Counter

If you select this option, the value specified in the Current value drop-down list is used as the default value in the Version/revision drop-down list. When packaging succeeds, the current value is updated by adding the value specified in the Increment value drop-down list. However, if you change the value in the Version/revision drop-down list during packaging, the current value is not updated. Note also that the current value returns to 0 when it exceeds 999,999. You can specify a value from 0 to 999,999 in the Current value drop-down list, and a value from 0 to 10 in the Increment value drop-down list.

If you want to set a fixed value in the Version/revision drop-down list, specify 0 in the Increment value drop-down list. This prevents the current value from being updated and leaves the default value in the Version/revision drop-down list unchanged.

Acquire from date when packaging is done

If you select this option, the date and time of packaging is used as the default value in the Version/revision drop-down list. You can select a desired date/time format from the Format drop-down list. YYMMDD, MMDDYY, DDMMYY, MMDDHH, and HHMMSS represent the year/month/day, month/day/year, day/month/year, month/day/hour, and hour/minute/second, respectively. If any value of the year, month, day, hour, minute, and second is a single-digit number, 0 is added in front of the value to make it a two-digit number.

Generation

Specify the default value to be used in the Generation drop-down list.

Counter

If you select this option, the value specified in the Current value drop-down list is used as the default value in the Generation drop-down list. When packaging succeeds, the current value is updated by adding the value specified in the Increment value drop-down list. However, if you change the value in the Generation drop-down list during packaging, the current value is not updated. Note also that the current value returns to 0 when it exceeds 9,999. You can specify a value from 0 to 9,999 in the Current value drop-down list, and a value from 0 to 10 in the Increment value drop-down list.

If you want to set a fixed value in the Generation drop-down list, specify 0 in the Increment value drop-down list. This prevents the current value from being updated, and leaves the default value in the Generation drop-down list unchanged.

Acquire from date when packaging is done

If you select this option, the date and time of packaging is used as the default value in the Generation drop-down list. You can select a desired date/time format from the Format drop-down list. MMDD, DDMM, HHMM, MMSS, YYMM, and MMYY represent the month/day, day/month, hour/minute, minute/second, year/month, and month/year, respectively. If any value of the year, month, day, hour, minute, and second is a single-digit number, 0 is added in front of the value to make it a two-digit number.

Note

When you want to specify a value in the Increment value drop-down list under the Version or Generation check box, specify a starting value as follows:

Starting value for Version: A six-digit value no less than 100,000

Starting value for Generation: A four-digit value no less than 1,000

If you specify a value other than the above values, correct judgments might not be made even if you specify package conditions during packaging.

(b) Software conditions

You can specify the default value for software conditions during remote installation.

Figure 7‒22: Package Attributes page ("Software conditions")

Conditions

In this area, you can select whether the specified software is to be installed on the condition that it already exists on the agent, or that it does not. By default, Installed is selected.

Judgment of multiple conditions

If you have specified multiple conditions, you can select whether the package is to be installed if any one of the specified conditions is satisfied or only if all of the conditions are satisfied. The default is Meets one of the conditions.

(c) Package conditions

You can specify the default values for package conditions during remote installation.

Figure 7‒23: Package Attributes page (Package conditions)

Package name/package ID

You can specify whether to identify the package as a package name, or package ID. By default, Package name is selected.

Conditions

You can specify whether the specified package is to be installed if it already exists on the managed computer, or if it does not. By default, Installed is selected.

Judgment of multiple conditions

If you have specified multiple conditions, you can select whether the package is to be installed if any one of the specified conditions is satisfied or only if all of the conditions are satisfied. The default is Meets one of the conditions.

(d) File properties

You can specify the default values for the file properties after remote installation. However, if you select Use the permissions and owner of the directory on the packager and the files or directories to be packaged are in a FAT file system, the following is selected in the JP1/ITDM2 Packaging dialog box: Use the permissions and owner of the installation directory

Figure 7‒24: Package Attributes page (File properties)

By default, Use the permissions and owner of the installation directory is selected. This setting is only valid for the following types of packaging:

When you select User programs and data for Package type

When you select Other companies' software for Package type and use AIT files

(e) Schedule

You can specify the default values to be used in Expiration of package storage at the relay computer and the Execution timing drop-down list in the JP1/ITDM2 Packaging dialog box.

Figure 7‒25: Package Attributes page (Schedule)

The relay computer holds relayed packages for

If you specify a number (days) in this field, this number is added to the date of packaging to determine the default value for the package storage time limit at the relay system. Specify a value from 1 to 32,000 (days). The default is 90 days. You can specify a maximum of 32,000 days (equivalent to approx. 88 years). However, if the date displayed in Expiration of package storage at the relay computer in the JP1/ITDM2 Packaging dialog box is January 1, 2095 or later, it is automatically changed to December 31, 2094.

Package maintenance period of relay system is enabled (On)

Select this check box to enable the default value for Expiration of package storage at the relay computer in the JP1/ITDM2 Packaging dialog box. By default, this check box is not selected.

Execution timing

Specify the timing of package installation. The default is Install now. If you want to leave the default value blank in the Execution timing drop-down list in the JP1/ITDM2 Packaging dialog box, select No default. You can select any one of the following items:

Install when the system starts

Install now

When System Stops

This item is only valid for agents for UNIX.

No default

(f) Installation method

You can specify the default value for Installation mode in the JP1/ITDM2 Packaging dialog box. The default is Background installation mode. This setting is valid only when you select User programs and data for Package type.

Figure 7‒26: Package Attributes page ("Installation method")

(g) Options

You can specify the default values for the optional items to be used during remote installation.

Figure 7‒27: Package Attributes page (Options)

Compression of package data

With this check box, you can specify the default value regarding whether to compress the software during packaging. By default, this check box is not selected.

Restore old version when upgrade failed

With this check box, you can specify the default value regarding whether to back up the previous version of the software at the remote installation target during a version upgrade. This setting is valid only when you select User programs and data for Package type. By default, this check box is not selected.

Restart computer after installation

With this check box, you can specify the default value regarding whether to automatically restart the managed computer after the package is installed. By default, this check box is not selected.

Display processing message

With this drop-down list, you can specify the default value regarding whether to display processing message dialog boxes on the managed computer during package installation. The default is According to the agent settings. You can select any one of the following items:

According to the agent settings

Show

Hide

(h) External program

If you select this item, you can specify the default values for the external programs to be started immediately before and after installation, and if an installation error occurs. You can also specify the default value for the external program monitoring time (Time-out). The default value for the Time-out field is 1 second, and the default values for all other items are blank.

Figure 7‒28: Package Attributes page ("External program")

If you select any of the following setting items, you can specify the default values for external program details: Detailed settings of the external program to start before installation, Detailed settings of the external program to start after installation, or Detailed settings of the external program to start at installation error. The following table lists the items for which you can specify default values, and the default value for each item:

Item for which default can be set

Default

Monitor the time of the external program

Not selected

End status is notified by

Exit code

When an external program error occurs, the job#

Finishes unsuccessfully

#

You cannot set this item if you select Detailed settings of the external program to start at installation error.

(i) AIT file

If you select this item, you can specify the default value regarding whether to monitor responses from installation processing that uses AIT files. This setting is valid only if you select Other companies' software for Package type, and AIT files are used in packaging.

Figure 7‒29: Package Attributes page ("AIT file")

If you monitor responses from installation processing that uses AIT files, select the Wait for the completion of AIT file processing check box, and specify the upper limit for the monitoring time in Time-out. By default, this check box is not selected.

(3) Directory page

On this page, you can specify a working directory to be used when the Packager packages software. This directory requires the amount of space that is more than the maximum size of the software to be packaged. The default directory is JP1/IT-Desktop-Management-2 - Agent-installation-directory\PKG\WORK.

Figure 7‒30: Directory page

(4) Audit Log page

On this page, specify settings related to audit log output during packaging.

Note that this page is displayed only when the Packager and JP1/IT Desktop Management 2 - Manager are located on different computers.

Figure 7‒31: Audit Log page

Output audit logs

Select this check box to output audit logs. By default, this check box is not selected. When you select this check box, the setting items related to audit log output are enabled.

Output directory for audit logs

Specify an audit log output directory by using from 4 to 127 bytes of double-byte or single-byte characters and the following symbols: _ \ . : ( ) .

By default, no output directory is specified. For the output directory you specify, assign write permissions to JP1/IT Desktop Management 2 users beforehand.

Audit logs are output to a NETMAuditManager.LOG file that is created in the specified directory.

Note that if you specify the JP1/IT Desktop Management 2 - Agent installation directory as the audit log output directory, audit logs are also deleted when JP1/IT Desktop Management 2 - Agent is uninstalled. Specify the output directory according to how audit logs are used.

7.3 Performing remote installation

Perform remote installation from the Remote Install Manager on the managing server.

This section explains how to create and execute a job specifying remote installation, and how to check execution results.

The methods for creating and executing a job are almost the same as those for operations other than remote installation. For details about operations common to all jobs, see 10. Managing Jobs.

7.3.1 Remote installation procedure

This subsection explains the basic remote installation procedure, focusing on screen transitions. For details about the setup method, see each reference shown in the procedure.

To perform remote installation:

In the Package window of the Remote Install Manager, select the package to be remotely installed.

Select Execute and then Execute Job.

The Define New Job dialog box appears.

Figure 7‒32: Define New Job dialog box

Select Install package, and then click the OK button.

The Create Job dialog box appears.

Figure 7‒33: Create Job dialog box

By default, the Job page is displayed. On this page, you can specify a job name. For details about how to set up the Job page, see 10.2.3 Setting up the Job page.

Click the Destination tab.

On the Destination page, specify a remote installation destination. You must specify at least one destination.

In a multi-server configuration, you can also specify a destination across relay systems and management relay servers.

Figure 7‒34: Destination page

For details about how to set up the Destination page, see 10.2.4 Setting up the Destination page.

Click the Package tab.

On the Package page, specify the package to be remotely installed.

Figure 7‒35: Package page

If you have created a job after selecting a package in the Package window, the selected package appears.

For details about how to set up the Package page, see 7.3.2 Setting up the Package page.

For other tabs (pages), specify appropriate settings according to the remote installation method.

Job Distribution Attributes page

On this page, you can specify multicast distribution and split distribution. However, you can specify multicast distribution only when using the Install package job. For details about how to set up the Job Distribution Attributes page, see 7.3.3 Setting up the Job Distribution Attributes page.

Schedule page

On this page, specify a registration date/time, execution date/time, and execution time limit for a job. For details about how to set up the Schedule page, see 10.2.5 Setting up the Schedule page.

Client Control page

On this page, you can specify whether to use the Client Control facility. For details about how to set up the Client Control page, see 10.2.6 Setting up the Client Control page.

After finishing all the settings, click the Execute button.

The remote installation job is executed.

Check the job status.

From the File menu of the Remote Install Manager, select New and then Job Status to display the Job Status window.

Figure 7‒36: Job Status window

For remote installation jobs, if you select View and then All Job Details in the Job Status window, the following icons are displayed in front of each job name:

: Install package job

: Transfer package to relay computer job

: Send package, allow client users to choose job

If you select an executed job, the execution status is displayed in the right pane of the window. For details about how to check the job status, see 10.4 Checking the job status.

If you save a job before executing it, you can re-execute it in case of failure, or when creating a new job, you can also save time by editing an existing job. We recommend that you use the Save or Save and Execute button to save a job before executing it.

To save a job in a folder, you need to create a storage folder in the Job Definition window beforehand. For details about how to create a folder, see 10.3.2 Managing saved jobs and folders.

Notes:

When you edit a remote installation job or transfer package to relay system job, if you delete all destinations without opening the package panel even once, the package panel cannot be opened afterward.

One or more destinations need to be specified to open the package panel.

When you create a new job definition from the remote install manager and save the job as the default job name provided by the remote install manager, if a dialog box which says such as "The same name already exists" is displayed, cancel the operation and create a new job definition again. Do not change the name of the job and save the job.

If the user who initiates the Remote install manager does not have administrator permission for the operating system, elevate the user to administrator level before proceeding.

7.3.2 Setting up the Package page

When creating a remote installation job, use the Package page of the Create Job dialog box to specify a package to be remotely installed.

Figure 7‒37: Package page

On the Package page, you can perform the following operations:

Adding packages

You can add packages to the Package frame.

Deleting packages

You can delete packages from the Package frame.

Changing the installation conditions

You can change the installation conditions specified during packaging, separately for each package.

Batch specifying schedule information

You can specify schedule information (one of the installation conditions) for all packages at one time.

If you specify multiple packages to be remotely installed, see 1.3.7 Job execution sequence.

(1) Adding packages

Clicking the Add button on the Package page displays the Add Package dialog box. You can resize the Add Package dialog box to make it easy to see. If you resize the dialog box, it retains that size the next time it is opened.

Figure 7‒38: Add Package dialog box

In this dialog box, specify a package to be added. Select a package to be added from the Cabinet or Package frame, and move it to the Selected package frame by clicking the -> or ->> button, and then click the OK button. The selected package is added to the Package page.

(2) Deleting packages

Select a package to be deleted on the Package page, and then click the Delete button.

(3) Changing the installation conditions

Clicking the Change button on the Package page displays the Change Installation Conditions dialog box, where you can view or change the installation conditions for the package specified during packaging.

Figure 7‒39: Change Installation Conditions dialog box

The pages displayed in the Change Installation Conditions dialog box are the same as those in the JP1/ITDM2 Packaging dialog box of the Packager. For details about the settings, see 7.2 Specifying package details. Note, however, that depending on the package type (for UNIX only, for Windows only, or package shared by UNIX and Windows), some items can only be viewed and cannot be edited.

The items that only appear in the Change Installation Conditions dialog box are as follows:

Settings in the Replace existing package check box

If you select this check box, the package is overwrite-installed on the managed computer if software program with the same name as that package already exists on the computer.

However, if you select the Replace existing package check box, the package is sent, regardless of whether the same package already exists on the destination computer. To avoid unnecessary increase in network traffic, select this check box only in the following cases:

When you need to overwrite any existing packages

When you want to distribute a package again because you accidentally deleted the same package by uninstallation or some other processing

In this case, you cannot install the package unless you select this check box.

Note also that if you select the Replace existing package check box, any software programs of the same version can be overwrite-installed even if their contents are different. This means that JP1/IT Desktop Management 2 can no longer manage versions based on installed package information.

(4) Batch specifying schedule information

Clicking the Options button on the Package page displays the Batch Setting for Installation Conditions dialog box, where you can specify schedule-related information in the package installation conditions for all packages at one time.

Figure 7‒40: Batch Setting for Installation Conditions dialog box

This dialog box also appears when you click the Schedule tab in the Change Installation Conditions dialog box.

7.3.3 Setting up the Job Distribution Attributes page

On the Job Distribution Attributes page, specify the following settings:

Settings for distribution to suspended destinations

Settings for job distribution methods

Settings for package split distribution

Figure 7‒41: Job Distribution Attributes page

This page is displayed only for the following job types:

Install package

Transfer package to relay computer

Send package, allow client users to choose (Split distribution range is up to the system to which the managed computer is connected)

Note, however, that you can select a job distribution method only for the Install package job. For the Transfer package to relay computer and Send package, allow client users to choose jobs, the Unicast distribution option is always selected and cannot be changed.

(1) Distribution to suspended destination

In this area, select whether to distribute a job to suspended destinations. By default, Do not distribute is selected.

If the managing server or any system on the route to the destination is suspended, file transfers are suspended for jobs for which Do not distribute is selected. However, file transfers are not suspended for jobs for which Distribute is selected, even if the system is suspended. In this case, other jobs are distributed ahead of the job that is being suspended.

If you select Distribute, you cannot perform split distribution. Note also that because jobs for which Multicast distribution is selected cannot be suspended, the settings for Distribution to suspended destination take effect only if you select Unicast distribution.

(2) Distribution methods

For the Install package job, you can select either Unicast distribution or Multicast distribution. By default, Unicast distribution is selected.

If you select Unicast distribution, the host system sends a single packet to a managed computer at one time. This means that the number of packets sent from the host system increases as the number of computers increases. However, if you select Multicast distribution, the host system can distribute jobs to any number of computers by only sending the packets required for a single job. Accordingly, if you distribute the following kinds of jobs by using multicast distribution, you can reduce the amount of transmission compared to unicast distribution:

Jobs that are distributed to numerous destinations

Jobs that distribute large packages

When jobs are distributed to relatively few destinations, or the package size is small, using multicast distribution makes file transfer less efficient. In such cases, select Unicast distribution.

Note that if you perform multicast distribution, you need to specify settings on the relay system and host system.

Note also that if you use multicast distribution, you cannot perform split distribution of packages. This means that if you select Multicast distribution, you cannot specify settings for Split distribution settings, which is described below.

If the destination is an agent for UNIX, you can select only Unicast distribution.

(3) Split distribution settings

In this area, specify whether to perform split distribution of packages. If you select Split package and then distribute, the package is split into the specified size before transfer. You can also specify the interval (Distribution interval) between transfers. These settings enable you to distribute even a large package without imposing a load on the network.

Split size

Specify the split size of a package. The package is split into the specified size. Specify a value in kilobytes or megabytes. The maximum specifiable size is 2,097,151 kilobytes. The default value is 1 megabyte.

The system compares the split size specified on the distribution-destination agent and the split size that you specify here. The system then splits the package by using the smaller split size. The split size is applied to each package to be distributed. When you distribute multiple packages, any packages smaller than the split size are distributed without splitting.

Distribution interval

You can specify the interval at which each split package is transferred during split distribution. Specify a value from 1 minute to 24 hours. The default value is 1 hour.

Note that the system actually uses the distribution interval specified on the side where the specified split size is used. If the specified split size is the same on both sides, the system uses the value specified on the subordinate system, and also uses the distribution interval specified on the side where the specified split size is used.

Note

If you select Split package and then distribute, you cannot perform multicast distribution.

7.3.4 Offline installation

This subsection explains offline installation operations.

Note that this function is not supported on the Citrix XenApp and Microsoft RDS server.

(1) Offline installation procedure

The following figure illustrates the offline installation procedure.

Figure 7‒42: Offline installation procedure

Package the software to be installed.

Use the Packager to package the software to be installed.

Note, however, that some items in the JP1/ITDM2 Packaging dialog box are disabled. For details about these items, see 7.3.4(6) Notes on performing offline installation.

Prepare installation media.

On the managing server, create a package information file that contains information about the package to be installed. Creating a package information file outputs an installation execution program at the same time.

For details about how to prepare installation media, see 7.3.4(2) Preparing installation media.

Carry the installation media to an offline machine.

Store the package information file and installation execution program on a portable medium such as a USB memory stick, and carry it to an offline machine.

Perform installation.

Execute the installation execution program on the offline machine to install the package specified in the package information file.

For details about how to perform installation, see 7.3.4(3) Performing installation on an offline machine.

Carry an installation result file to the managing server.

Retrieve an installation result file that is output during installation, store it on a portable medium such as a USB memory stick, and then carry it to the managing server. If the offline machine and the managing server are connected over a network, you can also send this file as an email attachment.

Check the installation results.

Open the installation result file in a text editor, and check the results.

For details about how to check installation results, see 7.3.4(4) Checking the results of installation on an offline machine.

(2) Preparing installation media

Prepare installation media by using the Remote Install Manager on the managing server where the package is managed. Store the following files on the installation media:

Package information file (file name: ITDM2LINST.BIN)

Installation execution program (file name: ITDM2LINST.EXE)

Use the following procedure to create a package information file. Creating a package information file also creates an installation execution program at the same time.

Use the Package window to select the package to be installed.

You can select multiple packages in the same cabinet.

From the File menu, select Offline Machine Management, and then Creation of Installation Media.

The Creation of Installation Media dialog box appears.

Figure 7‒43: Creation of Installation Media dialog box

The List of the Installed Packages table displays the packages that you selected in the Package window.

If necessary, change the package installation order.

Each package is installed sequentially starting from the top of the List of the Installed Packages table. To change the installation order, select a desired package, and then click the ↑ or ↓ button.

If necessary, change the package installation conditions.

If you want to change the package installation conditions such as the installation target directory and software conditions, select a desired package, and then click the Change button. The Change Installation Conditions dialog box appears, where you can change the installation conditions.

This dialog box is the same as the Change Installation Conditions dialog box that you use during remote installation.

Note, however, that all the functions on the Schedule page in the dialog box are disabled (left blank), and cannot be changed. For details about other settings in the Change Installation Conditions dialog box, see 7.3.2(3) Changing the installation conditions.

Click the Create button.

The Browse for Folder dialog box appears.

Select the folder that contains the package information file and installation execution program, and then click the OK button.

A dialog box appears indicating that an installation medium is currently being created, and a package information file and installation execution program are created in the selected folder.

(3) Performing installation on an offline machine

Carry the prepared installation media to the offline machine where you want to install the packages. Install the packages on the offline machine as described below.

Note that several settings on the managed computer are disabled during offline installation. For details, see 7.3.4(6) Notes on performing offline installation.

Make sure that none of the JP1/IT Desktop Management 2 functions are being used on the offline machine.

You cannot perform offline installation while other JP1/IT Desktop Management 2 functions are being used. Wait until these functions finish.

Make sure that the package information file and installation execution program are stored in the same folder, and then execute the installation execution program.

The Install package dialog box is displayed while the installation is in progress, so that you can check the installation execution status.

You can also execute the installation execution program by using a command. For details about the installation execution command, see 7.3.4(5) Offline installation execution command (ITDM2LINST).

If you cannot output an installation result file, in the Save Installation Result File dialog box that appears, select the output destination, and then click the OK button.

Click the Cancel button if you do not want to output an installation result file.

When the installation finishes, an installation result file (file name: ITDM2linst.txt) is output to the same folder as the installation execution program. If an installation result file already exists in the output destination folder, installation results are appended to the end of the file.

(4) Checking the results of installation on an offline machine

Retrieve an installation result file that is output during installation, and carry it to the managing server. Open the installation result file in a text editor, and check the installation results.

The output format of installation result files is shown in the following figure and explained as below.

Figure 7‒44: Output format of installation result files

Installation results are output as a single line of data for each package. Each item is separated by a tab character. Details of each item are explained as follows:

Date

The date that the package was installed is output in the YYYY/MM/DD format.

Time

The time that the package was installed is output in the hh:mm:ss format.

Result

The installation result is output as either of the following values:

OK: Succeeded

NG: Failed

Host name

The host name of the computer where the installation was performed is output. If the computer does not have a host name, the host ID with the first # character deleted is output.

IP address

The IP address of the computer where the installation was performed is output. If the computer does not have an IP address, 127.0.0.1 is output.

Package name

The name of the installed package is output.

Package information

Information about the installed package is output in the following format:

d.cc.pppppp.vvvv.ssss

d: Package type

(d is output as C, which indicates UNIX, or D, which indicates Windows.)

cc: Cabinet ID

pppppp: Package ID

vvvv: Version

ssss: Generation number

Maintenance code

A maintenance code indicating the installation result is output.

Host ID

The host ID of the computer where the installation was performed is output.

(5) Offline installation execution command (ITDM2LINST)

This subsection explains the ITDM2LINST command, which is executed on offline machines.

Function

This command installs the package specified in the package information file (ITDM2LINST.BIN) on an offline machine. Installation results are output to an installation result file (ITDM2linst.txt).

Format

ITDM2LINST.exe [/I directory-containing-package-information-file]
            [/O directory-to-which-installation-result-file-is-output]
            [/S]

Options

/I

Specify the full path to the directory that contains the package information file (ITDM2LINST.BIN).

If you omit this option, the system loads the package information file in the same directory as the installation execution program (ITDM2LINST.EXE).

/O

Specify the full path to the directory to which an installation result file (ITDM2linst.txt) is to be output. If an installation result file already exists in the output destination folder, installation results are appended to the end of the file.

If you omit this option, the system outputs an installation result file to the same directory as the installation execution program (ITDM2LINST.EXE).

/S

Specify this option if you do not display the following dialog boxes during offline installation:

- Install package dialog box

- Save Installation Result File dialog box

- Dialog boxes displaying installation results

- Error dialog boxes specific to offline installation

Execution example

When the package information file is stored in C:\Program Files\Hitachi\JP1ITDMM\MGR\BIN\DMPRM and an installation result file is output to A:\, specify the command as follows:

ITDM2LINST.exe /I "C:\Program Files\Hitachi\JP1ITDMM\MGR\BIN\DMPRM" /O "A:\"

(6) Notes on performing offline installation

When performing offline installation on a managed computer, note the following:

If an error message such as ITDM2LINST.BIN is not found appears when you perform offline installation by storing data from the installation media into a network drive, an attempt to access the network drive might have failed. Check whether you have permissions to access the network drive.

The amount of disk space required for offline installation on a managed computer is the same as for remote installation on a managed computer.

Some items in the following are disabled: Job settings dialog box for the agent configurations, the JP1/ITDM2 Packaging dialog box, and the Change Installation Conditions dialog box.

The following table shows the setting items that require attention, including those that are disabled during offline installation.

Table 7‒2: Setting items that require attention during offline installation

Dialog box name

Category or page name

Setting item

Description

Job settings

Installation waiting time settings

InstallShield time-out

Disabled

Settings to permit job holds

Permit users to hold jobs

Settings to suppress notifications

Suppress notifications on jobs waiting to be installed and collected#

JP1/ITDM2 Packaging

Schedule

Package expiration at the relay system

Disabled

Installation date/time

Execution timing

Options

Restart computer after installation

Change Installation Conditions dialog box

Options

Restart computer after installation

Disabled

#: This option does not notify any jobs awaiting remote installation or collection, regardless of the settings.

If you use JP1/IT Desktop Management 2 - Manager in a cluster system environment, you must enter a value in the Management Server text box in the Login (Remote Install Manager) dialog box when starting the Remote Install Manager. To do this, start the Remote Install Manager on the active server node where cluster resources are operating, and then specify localhost, a physical host name, or a physical IP address. If you specify a logical host name or logical IP address, Creation of Installation Media becomes disabled.

7.3.5 Notes on performing remote installation

This subsection provides notes on performing remote installation.

(1) Notes on split distribution

Notes on split distribution are shown below.

When executing multiple jobs specifying split distribution

Even if you execute multiple jobs specifying split distribution at the same time, the packages for each job are not simultaneously transferred between the transfer source and the transfer destination. Each job is executed sequentially one at a time. This means that any jobs other than the job that is currently transferring packages are in a package download waiting state (job running rate: 20%).

Notes on specifying destinations

If you execute an Install package job specifying split distribution on a relay system or management relay server, do not specify the destination as the icon of a relay system or management relay server in the system configuration. You must specify the destination as the icon of a managed computer under a relay system or management relay server in the system configuration. If you specify the destination as the icon of a relay system or management relay server in the system configuration, normal distribution is performed instead of split distribution.

If ID group jobs are used, you must register the ID group of the management relay server itself on the local host.

For an Install package job destined for a relay system or management relay server, you must specify the destination as the icon of a managed computer under the relay system or management relay server in the system configuration. In this case, split distribution is not performed between the relay system or management relay server and the managed computer.

If you execute multiple jobs specifying split distribution at the same time, normally, these jobs are executed sequentially on each transfer source node and transfer destination node. However, if jobs for which destinations are specified manually during job registration coexist with jobs for which destinations are specified according to the system configuration or destination information, multiple jobs might transfer packages in parallel.

Circumstances under which package installation sequence cannot be guaranteed

If multiple packages are specified for the Install package job, these packages are installed on the distribution destination system in the following priority order: cabinet ID, package ID, version, and generation number of the package specified for the job. Note, however, that jobs specifying split distribution might be unable to guarantee proper installation sequence under the following circumstance:

When the package to be distributed is already stored on a management relay server on the route to the destination

When a job specifying split distribution is forcibly terminated during execution

Download progress display during split distribution

If the package size of split distribution is too small, the download progress dialog box on the managed computer might indicate 0%. If you perform split distribution jobs successively, the download progress dialog box on the managed computer might indicate 0% for jobs awaiting split distribution.

Forcibly enabling the split distribution settings specified during job registration

If you set the package split distribution settings in the agent configurations to the default values, you can forcibly transfer packages to the distribution destination system by using the split distribution settings specified during job registration. The default values in the agent configurations are as follows:

Split package and then distribute check box: Selected

Split size: 2,097,151 kilobytes

Distribution interval: 1 hour

Relationship between package split distribution and Client Control

If you execute the Install package job with both package split distribution and Client Control specified, the system behaves as below.

If you select Start the target computer if it is not running and Shut down the client after the job execution:

The computer turns on.

The first split package is transferred.

The computer turns off.

Steps 1, 2, and 3 are repeated.

If the destination is an agent for UNIX, Shut down the client after the job execution is disabled. The computer does not turn off automatically.

If you select Start the target computer if it is not running:

The computer turns on.

The first split package is transferred.

Package transfer continues, and the computer remains on.

Notes on JP1/IT Desktop Management 2 - Agent (relay system)

The split size and distribution interval specified during job creation are compared with the specified values in the agent configurations on the subordinate system, and split distribution is performed by using the smaller values. However, the split size and distribution interval (displayed by selecting Display Job Detailed Information from the View menu of the Job Status window) might be displayed as the values specified during job creation, depending on the timing of display. This behavior is normal and does not indicate any operational problems.

(2) Notes on suspending and restarting jobs

When suspending and restarting jobs, note the following:

If you select Suspend/Resume File Transfer and then Resume from the Execute menu of the Remote Install Manager (to instruct the manager itself to restart transferring files), the execution status display might change. For example, if a suspended distribution job from the Packager enters a running state, the execution status display changes back to a lower running rate (for example, from 50% to 20%).

(3) Notes on distribution during job suspension

It is not effective if you execute a job with the Distribute option selected in an environment where job suspension functions are not used. Because a job with the Distribute option selected behaves in the same way as a job with the Distribute option unselected, the distribution order does not change.

(4) Notes on distributing jobs to UNIX computers

Note the following when distributing jobs to managed UNIX computers:

Postprocessing programs are executed in the following cases:

If Remote Install Manager is used to cancel the specification of a postprocessing program for packages that are created by specifying an installation date/time and a postprocessing program with the Windows-version Packager or the dcmpack command

If Remote Install Manager is used to cancel the specification of a postprocessing program for packages that are created in UNIX by specifying NETM_DM_GF as the generator type and a postprocessing program

Postprocessing programs are not executed in the following cases:

If Remote Install Manager is used to specify a postprocessing program for packages that are created in UNIX by specifying NETM_DM_GF as the generator type without an installation date/time and postprocessing program specified

Jobs result in an error in the following case:

If Remote Install Manager is used to cancel the specification of an installation date/time for packages that are created in UNIX by specifying NETM_DM_GF as the generator type and an installation date/time

(5) Notes on using the function for automatic registration into the system configuration

On the remote install manager, when operations related to system configuration information are performed (example: add or delete the relay managing the ID), even if the nodes for operation targets are displayed, an instruction such as "Designated ID name or the relay managing the ID does not exist on the system. Double click the network and obtain the latest information and confirm the status" might be displayed. In such a case, follow the instruction because the message is associated with the update of the management information of the target nodes performed by this function.

(6) Notes on using the priority distribution function

When using the priority distribution function, do not use multicast distribution.

When splitting and distributing files that exceed 2 gigabytes, ensure that the priority of the split files is the same. If the priority differs, an error may occur when the files are combined.

(7) Other cautionary notes

A job might fail when you remotely install a Hitachi program product into a folder which contains a space character in its folder name.

Files and Folders on OneDrive are not accessible from the software distribution and file collection functionality in Remote Install Manager.

If package transfer is interrupted due to network disconnection, package transfer is resumed after recovery.

7.4 Managing cabinets and packages

This section explains how to manage cabinets and packages.

7.4.1 Creating cabinets

You can create a maximum of 1,296 cabinets by using the Remote Install Manager as follows:

In the Package window, select File and then Create Cabinet.

The Create Cabinet dialog box appears. You must specify each item.

Figure 7‒45: Create Cabinet dialog box

Cabinet name (mandatory)

Assign a unique name to each cabinet by using no more than 32 single-byte characters (or 16 double-byte characters). You cannot use the following characters: \, /, *, ", :, ;, and whitespace

Cabinet ID (mandatory)

Assign a unique ID to each cabinet by using two alphanumeric characters (alphabetic letters must be in uppercase).

Cabinet type (mandatory)

Select Windows or UNIX, depending on whether the package to be stored was created in Windows or UNIX.

After setting these items, click the Exit button.

Save the settings, and then close the Create Cabinet dialog box.

If you click the Add button (instead of the Exit button), you can continue creating cabinets.

Note that you can also create cabinets when packaging software from the Packager. If you assigned the same cabinet name to different cabinet IDs by mistake, invalid packages might be displayed in the cabinets. In such a case, change either of the duplicate cabinet names by selecting File and then Rename.

7.4.2 Checking the cabinets and packages

Check the information about cabinets and packages in the right pane of the Package window. The right pane has three tabs. Selecting these tabs displays the following information:

List tab

This tab displays a list of information about the cabinets or packages one level below the item selected in the left pane.

Attributes tab

This tab displays cabinet and package attribute information such as cabinet names, package names, and conditions specified during packaging.

Figure 7‒46: Package window (Attributes) (1/2)

Figure 7‒47: Package window (Attributes) (2/2)

Package Contents tab

If you select User programs and data for Package type, you can view the names, sizes, and last update dates/times of the files included in the package. For a compressed package, this information is displayed after you decompress the package.

Figure 7‒48: Package window (Package Contents)

This window does not display information about a package that is currently being deleted.

Similarly, if you refresh the display of package contents while the package contents are being output to a CSV file, display processing might fail.

The Remote Install Manager of JP1/IT Desktop Management 2 - Manager enables you to view more detailed attribute information for packages, as described below. Note that you cannot view detailed information for multiple packages at the same time.

In the left pane of the Package window, right-click the package whose contents you want to view, and select Properties.

The XXX Properties dialog box appears (XXX: package name).

In the XXX Properties dialog box, click the Details button.

The Details of Attribute dialog box appears, allowing you to check the settings specified during packaging. For details about displayed items, see 7.1.3 Checking the stored packages.

Note that attribute details cannot be displayed for the following packages:

Packages that are currently being created

Packages that have been deleted while properties are being displayed

Note that you cannot rename, copy, or move packages. To do so, you need to package the software again from the Packager, and then delete any packages that are no longer necessary.

7.4.3 Renaming the cabinets

To rename a cabinet:

In the Package window, select a cabinet to be renamed, and select File and then Rename.

The Rename Cabinet dialog box appears.

Figure 7‒49: Rename Cabinet dialog box

Enter a new name, and then click the OK button.

The cabinet name is changed.

Tip

Changing the cabinet name does not affect the behavior of the product.

7.4.4 Transferring packages to relay systems or managing relay servers

To transfer a package to a relay system or management relay server, execute a Transfer package to relay computer job. For details about operations and settings, see 10.2 Creating a job.

7.4.5 Deleting cabinets and packages

Use the following procedure to delete cabinets or packages. Note that you cannot restore any cabinets or packages that you have deleted.

In the Package window, select a cabinet or package to be deleted, and select Edit and then Delete.

A dialog box appears, asking you to confirm the deletion.

Click the OK button.

A dialog box appears, asking you to reconfirm the deletion.

Click the OK button.

The selected cabinet or package is deleted.

If you have accidentally started deletion processing for a package that is currently being created, the deletion processing enters a waiting status until the packaging finishes, and the Remote Install Manager enters a silent state. In this case, close the Remote Install Manager.

7.4.6 Deleting packages on relay systems and management relay servers

You can use the Delete Packages from Relay Computer dialog box of the Remote Install Manager on the managing server to select and delete each package file while checking the file size, as follows:

Open the System Configuration window or Package window, and select Edit and then Delete Packages from Relay Computer.

The Delete Packages from Relay Computer dialog box appears.

Specify a desired connection destination, and then click the Connect button.

The package list appears.

Select a package to be deleted.

The selected package is highlighted, and package information (version, package ID, generation number, size, and expiration date) is displayed.

Click the Delete button.

A dialog box appears, asking you to confirm the deletion.

Click the OK button.

The selected package is deleted.

7.5 Deleting installed package information

To delete installed package information:

In the left pane of the System Configuration window or Destination window, select the host for which installed package information is to be displayed.

In the right pane, select the Installed Packages tab.

Information about the installed packages is displayed.

Select a package whose information is to be deleted.

If you want to delete information for all installed packages, there is no need to select packages.

Select Edit and then Delete Installed Package Information.

The Delete Installed Package Information dialog box appears.

Figure 7‒50: Delete Installed Package Information dialog box

Select the information to be deleted.

Installed package information

Displays the selected package information as the deletion target.

To delete all information, select the Delete the information of all packages check box.

Host

Displays the host from which installed package information is to be deleted. If there is no applicable host, the Delete the information of all hosts check box is automatically selected.

Not to be Deleted button

Clicking this button removes the displayed installed package or host from the deletion target.

To be Deleted button

Clicking this button returns the installed package or host (that has been removed from the deletion target) to the deletion target.

Click the OK button.

The selected information is deleted according to the settings.

7.6 Remote installation operation examples

This section presents remote installation operation examples that meet various purposes.

7.6.1 Checking free disk space and other requirements before installation

You can specify the amount of free space on the hard disk or the status of RAM as remote installation conditions.

Even if you do not specify particular settings, when the amount of free space on the hard disk becomes insufficient during remote installation processing, this fact is notified from the managed computer to the server. Then, all the working files and other temporary files used during installation are deleted. However, because margins are not specified for this check of free disk space, sufficient free disk space after installation might not be provided. If necessary, specify disk space requirements, such as at least 10 to 20 megabytes of free disk space required after installation.

If you also specify RAM requirements, you can prevent problems such as operation failure after installation.

These conditions are called system conditions. You can specify system conditions on the System Conditions page in the JP1/ITDM2 Packaging dialog box of the Packager or on the System Conditions page in the Change Installation Conditions dialog box of the Remote Install Manager.

The following figure illustrates an example of checking the amount of free space on the hard disk before installation.

Figure 7‒51: Example of checking the amount of free disk space before installation

7.6.2 Checking the software installed on a managed computer before installation

Some commercial software products require particular versions of particular software products for normal operations. In such cases, you can specify a particular version to check whether particular software has been installed on a managed computer. Conversely, you can also specify such conditions as performing remote installation only if particular software products do not exist on the managed computer.

These conditions are called software conditions. You can specify software conditions on the Software Conditions page in the JP1/ITDM2 Packaging dialog box of the Packager or on the Software Conditions page in the Change Installation Conditions dialog box of the Remote Install Manager.

The following figure illustrates an example of checking the software installed on a managed computer before installation.

Figure 7‒52: Example of checking the software installed on a managed computer before installation

7.6.3 Checking installation applicability according to user-specific conditions

JP1/IT Desktop Management 2 enables you to check remote installation applicability by specifying various conditions, such as the amount of free disk space (system conditions) and the installation status of particular software products (software conditions). Installation applicability checking based on the standard functions of JP1/IT Desktop Management 2 is sufficient for normal operations, but user-specific checking might be required for user program installation. For example, if you assign business terminal IDs to each computer beforehand, you can perform remote installation on only the computers that match the specified IDs.

To cope with the above kind of situation, JP1/IT Desktop Management 2 provides a function for starting an external program immediately before installation. For exceptional operations such as above, you can start an external program immediately before installation in order to check whether user-specific installation conditions are met.

You can specify an external program (to be started immediately before installation) by using the External Program page in the JP1/ITDM2 Packaging dialog box of the Packager. Alternatively, you can also use the External Program page in the Change Installation Conditions dialog box of the Remote Install Manager.

The following figure illustrates an example of checking installation applicability according to user-specific conditions.

Figure 7‒53: Example of checking installation applicability according to user-specific conditions

7.6.4 Changing the settings for installed software

If you install software programs for which the settings can be changed by using INI files, you can change the settings for these software programs by remote installation, even after they are initially installed.

For example, to change the settings for Software A:

Stop the service of Software A by using the net stop command.

Perform remote installation to distribute the INI file where you changed the settings.

Start the service of Software A by using the net start command.

7.6.5 Installing software at a specified time

Because remote installation transfers and installs software to each computer over a network, installation times might vary between computers, according to the network congestion status or other reasons.

JP1/IT Desktop Management 2 enables you to specify an installation date and time first, transfer packages to managed computers, and then install all the packages on the managed computers simultaneously at the specified time.

You can specify an installation date and time on the Schedule page in the JP1/ITDM2 Packaging dialog box of the Packager or on the Schedule page in the Change Installation Conditions dialog box of the Remote Install Manager.

The following figure illustrates an example of installing software at a specified time.

Figure 7‒54: Example of installing software at the specified time

7.6.6 Setting a distribution date and time in two stages

You might attempt to transfer packages from the managing server to a relay system or management relay server and then from the relay system or management relay server to managed computers when the relevant network is not congested. In such a case, you can sometimes transfer packages efficiently by specifying package transfer dates and times separately for each network. To do this, first execute a Transfer package to relay computer job to transfer packages to the relay system or management relay server, and then execute an Install package job. The execution date and time of the first job corresponds to the date and time of package transfers from the managing server to the relay system or management relay server. The execution date and time of the second job corresponds to the date and time of package transfers from the relay system or management relay server to the managed computers.

Specify a job execution date and time on the Schedule page of the Create Job dialog box during job creation.

The following figure illustrates an example of setting a distribution date and time in two stages.

Figure 7‒55: Example of setting a distribution date and time in two stages

Furthermore, you can also specify an installation date and time separately for each package, which makes it possible to specify a distribution date and time in three stages.

7.6.7 Preventing damage to the old version due to remote installation failure

When you use remote installation to upgrade software, the old version of the software might be damaged if remote installation fails. If the old version of software becomes damaged, that software cannot be used until it is remotely installed again.

To prevent this problem, JP1/IT Desktop Management 2 provides a package backup/restore function. If you use the backup/restore function, the old version of software is backed up on the managed computer during remote installation, so that the old version can be restored from the backup if remote installation fails. This function is available only if you select User programs and data in the Package type section.

You can specify the backup/restore function by selecting Restore old version when upgrade failed on the Options page in the JP1/ITDM2 Packaging dialog box of the Packager. Alternatively, you can also select Restore old version when upgrade failed on the Options page in the Change Installation Conditions dialog box of the Remote Install Manager.

The following figure illustrates an example of preventing damage to the old version due to remote installation failure.

Figure 7‒56: Example of preventing damage to the old version due to remote installation failure

7.6.8 Performing remote installation by bypassing a faulty relay system

If a relay system fails, you can perform remote installation on the managed computers connected to this relay system by connecting to another relay system.

To perform remote installation by changing a route, use the Create Job dialog box to create a job that specifies a changed route. To do this, click the Change Route button on the Destination page, and then specify a changed route in the Change Transmission Route dialog box that appears.

The following figure illustrates an example of performing remote installation by bypassing a faulty relay system.

Figure 7‒57: Example of performing remote installation by bypassing a faulty relay system

7.6.9 Multicast distribution performing installation by reducing the amount of packets sent by a job

If you want to use the Install package job to install large packages on a large number of computers, you can reduce the amount of packet transmissions by distributing jobs based on multicast distribution.

For normal job distribution (unicast distribution), the number of packets sent from the host server increases according to the number of managed computers. However, if you distribute jobs based on multicast distribution, you can distribute jobs to a specified (large) number of computers just by sending the packets for a single job from the host system connected to those computers. This reduces the amount of packet transmissions, thereby reducing the load on the network. Job distribution times can also be reduced.

With multicast distribution, the host system sends packets to a conceptual group called a multicast group. These packets are sent to each computer that belongs to that group. A multicast group has a group-specific IP address called a multicast address. For the host system and each computer participating in the multicast group, set the same multicast address in the agent configurations.

The following figure illustrates the differences between multicast distribution and unicast distribution.

Figure 7‒58: Differences between multicast distribution and unicast distribution

When a job is distributed to relatively few destinations, or when the package size is small, using multicast distribution makes the package transfers less efficient. In such cases, use unicast distribution.

To use multicast distribution, specify a desired distribution method on the Job Distribution Attributes page of the Create Job dialog box during job creation. For details about the system configuration and settings for multicast distribution, see 3.2 Settings for multicast distribution.

7.6.10 Splitting packages before distribution (Split distribution)

Split distribution balances network load by splitting large packages before distribution. Split distribution also allows you to specify an interval between the transfers of split packages (Distribution interval), thereby further reducing network load. If you split packages before distribution, select the Split package and then distribute option on the Job Distribution Attributes page during job creation.

If there is a relay system or management relay server on the route to the package transfer destination, the split size and transfer interval of packages change according to the following criteria:

The split size specified in the transfer source system during job creation is compared with the split size specified in the agent configurations in the transfer destination system. Then, the smaller split size and the corresponding distribution interval become effective.

If the split size specified in the transfer source system during job creation equals the split size specified in the agent configurations in the transfer destination system, the distribution interval specified in the transfer destination system becomes effective.

The following figure illustrates an example of distributing split packages.

Figure 7‒59: Example of distributing split packages

If there is a relay system or management relay server on the route to the package transfer destination, the relay system or management relay server must be always running.

You can stop split distribution halfway through, and transfer all the unsent packages at one time to complete the distribution as normal distribution. This operation is called forced completion of split distribution. A job that has been forcibly completed transfers all unsplit packages from the system immediately under the system to the destination systems at the same time (by using normal distribution). However, forced completion of split distribution is effective for all the systems under the system (where forced completion is performed) only during split distribution. Note also that you cannot forcibly complete jobs that are currently suspended or being restarted.

To forcibly complete split distribution, select a split distribution job in the Job Status window of the Remote Install Manager. Then select Execute, and then Forcibly Complete Split Distribution.

You might wish to forcibly complete split distribution only to the relay system or management relay server under the system where forced completion is performed, and continue split distribution to destination systems under the relay system or management relay server. In this case, transfer the same package by executing a Transfer package to relay computer job. Accordingly, split distribution to the relay system or management relay server is forcibly completed (and changed to normal distribution), and split distribution to the destination systems under the relay system or management relay server is continued.

7.6.11 Performing installation on computers that are not running

When you want to distribute packages late at night or on a weekend or holiday, remote installation fails or a job cannot be executed if the destination computer is not running. If a destination computer is not running, JP1/IT Desktop Management 2 enables you to start the computer by using the Client Control facility before executing a job. You can also specify settings to shut down the computer that you started.

To use the Client Control facility to start the destination computer, during job creation, select Start the target computer if it is not running on the Client Control page of the Create Job dialog box. If you want to shut down the computer that you will have started, select the Shut down the client after the job execution option. If the destination computer is an agent for UNIX, Shut down the client after the job execution is disabled.

The following figure illustrates an example of performing installation on a computer that is not running.

Figure 7‒60: Example of performing installation on a computer that is not running

For details about the settings on the Client Control page of the Create Job dialog box, see 10.2.6 Setting up the Client Control page.

7.6.12 Suspending and restarting a running job

When you want to complete package distribution during a time frame of light network load, distribution processing might not finish within the time frame. In such a case, you can temporarily suspend a running job to control the time frame during which the job is executed. Later, the suspended job can be restarted from the point where it was suspended.

Use the following methods to suspend and restart jobs:

Issuing a suspension or restart instruction from the managing server to the relay system or management relay server

Execute Suspend file transfer and Resume file transfer jobs on the managing server to instruct the relay system or management relay server to suspend and restart the job. If you specify a schedule to execute these jobs beforehand, you can perform operations, such as suspending package distribution just before business hours and restarting package distribution just after business hours.

Issuing a suspension or restart instruction to the managing server itself

You can issue a suspension or restart instruction to the managing server itself to which the Remote Install Manager is connected. To do this, from the Execute menu of the Remote Install Manager, select Suspend/Resume File Transfer and then Suspend or Resume.

Executing the dcmsusp command on the managing server

You can use the dcmsusp command to automatically suspend and restart package distribution. You can specify both the relay system (or management relay server) and the local system as the target of a suspension instruction.

You can use these methods all together. For example, you can execute the Suspend file transfer job on the relay system to suspend file transfer, and then execute the dcmsusp command to restart the file transfer.

For details about the scope of job suspension and restarting, see 3.1.6(6)(c) Scope of suspension and resumption of job distribution.

(1) Relationships between job suspension/restarting and other operations

The relationships between job suspension/restarting and other operations are described below.

Relationship with multicast distribution

You cannot suspend jobs specifying multicast distribution. Even if you execute job suspension on the relay system, the job continues running. However, a job specifying multicast distribution is suspended if you execute job suspension on a computer that contains at least one Install package job that is already being suspended.

Relationship with split distribution

You can suspend jobs specifying split distribution in the same way as normal jobs. If you suspend such a job while split packages are being transferred, package transfer restarts from the point where it was suspended. When package transfer is suspended, the packages are further split, and the transfer is not restarted until the specified distribution interval has passed.

Relationship with the Client Control facility

You can suspend jobs specifying Client Control in the same way as normal jobs. When you suspend or restart such jobs, the system behaves as below. If the target computer is an agent for UNIX, Shut down the client after the job execution is disabled.

If you specify Start the target computer if it is not running and Shut down the client after the job execution:

The computer turns on.

<An instruction to suspend the job is issued.>

The computer turns off.

<An instruction to restart the job is issued.>

The computer turns on.

The job finishes.

The computer turns off.

If you specify Start the target computer if it is not running:

The computer turns on.

<An instruction to suspend the job is issued.>

The computer remains on.

<An instruction to restart the job is issued.>

The job finishes.

The computer remains on.

If you specify Shut down the client after the job execution:

The job is running.

<An instruction to suspend the job is issued.>

The computer turns off.

<An instruction to restart the job is issued.>

The computer remains off, and the job does not restart.

(2) System behavior when you change the route to a computer during job suspension

If you change the route to a computer during job suspension, the system behaves as follows:

If you change the route to the relay system or management relay server where a job is being suspended, the suspension status is not released, and the job remains suspended. The job processing results are posted to the host system through the previous (pre-change) route.

If you change the route to a suspended job on a computer, any files that have been transferred to the computer are deleted (the suspended job is deleted).

7.6.13 Distributing jobs during suspension

Even if you want to urgently distribute packages, you cannot do so if another job is waiting for execution or is currently running. In such a case, you can distribute packages ahead of other jobs by suspending other jobs and assigning top priority to a job that distributes the packages you want to distribute urgently. Note that when there are no suspended jobs, the distribution order is the same as for normal jobs.

To distribute packages even during job suspension, select Distribute on the Job Distribution Attributes page during job creation. The Remote Install Manager displays jobs (for which Distribute is selected) with different icons from those of jobs for which this option is not selected. If you want to use a command to automatically execute a job that distributes packages even during job suspension, use the following methods:

Execute the dcminst command by using a parameter file or command arguments to specify that packages be distributed even during job suspension.

First use the Remote Install Manager to create and save a job for which Distribute is selected, and then execute this job by using the dcmjexe command.

The relationships between job distribution during suspension and other operations are described below.

Relationship with multicast distribution

You cannot suspend jobs specifying multicast distribution. For such jobs, it is not meaningful to specify whether to distribute packages even during job suspension.

Relationship with split distribution

For jobs specifying split distribution, you cannot specify that packages be distributed even during suspension.

7.6.14 Distributing a file larger than 2 gigabytes

If you distribute a file larger than 2 gigabytes to managed computers, split the file on the administrator's computer to create a package. The following procedure shows how to do it in a Windows agent.

Create a cabinet for package registration.

On the administrator's computer, use Remote Install Manager or the dcmpack command to create a new cabinet for package registration of the file to be split. For details about how to run Remote Install Manager, see 7.4 Managing cabinets and packages.

Split the file and package files.

Use the dcmpack command to split the file to be distributed.

When the command ends normally, the file is split into the package based on the information in the specified parameter file and registered in the managing server.

For details about the dcmpack command, see 14.9 dcmpack.exe (executing packaging). In the parameter file specified as a command argument, use the catAndValidatePackagingFile command as an external program that runs after installation.

Note that when the command ends normally, the folder for the temporary file area is deleted automatically.

Execute a remote installation job.

Use Remote Install Manager or the dcminst command to distribute the file packaged in step 1 to distribution-destination computers. For details about how to run Remote Install Manager, see 7.3 Performing remote installation.

After a file packaged according to the above procedure is distributed to the distribution-destination computers, the split files are combined by the catAndValidatePackagingFile command. For details about the command, see 14.18 catAndValidatePackagingFile.exe (combining split files).

(1) When JP1/IT Desktop Management 2 - Agent on distribution-destination computers is version 11-50 or earlier versions

When JP1/IT Desktop Management 2 - Agent on the distribution-destination computer is version 11-50 or earlier versions, distribute the combine-file command to the distribution-destination computer in advance. The following procedure shows how to distribute the command.

Package the combine-file command.

Using the agent of JP1/IT Desktop Management 2 version 11-51, package the combine-file command and register it.

The combine-file command to be packaged is in:

JP1/IT-Desktop-Management-2-Agent-installation-folder\tools\distribute\catAndValidatePackagingFile

Specify the following attributes for the package:

Package attribute

Value

Packaging information

Any

System conditions

For the installation destination, specify a folder other than the folder where the agent is installed.

Software conditions

The version of the software name JP1/IT Desktop Management 2 - Agent is smaller than 11.5.1.0000.

Package conditions

This package is not installed.

File properties

Any

Schedule

Any

Installation method

Any

Options

Any

External program

Any

Execute a remote installation job.

Using Remote Install Manager or the dcminst command, distribute the packaged combine-file command to distribution-destination computers.

(2) Example of distributing a large Windows 10 update

As an example, the procedure of distributing a large Windows 10 update is described below.

Get the Windows 10 update.

For details about how to get the update, see the OS manual.

Extract computers to which the update is applied.

Extract and group computers to which the update is applied (PCs that the Windows 10 update has not been applied to).

Deploy the update.

On the administrator's computer, mount the Windows 10 update file (ISO image) as a drive. For details about how to mount an ISO image file as a drive, see the OS manual.

Create a cabinet for package registration.

Create a new cabinet for package registration of the file to be split.

Split the file and package files.

Execute the dcmpack command to split the file to be distributed. The following shows an example in which the ISO file for the update is mounted to E:\ and the parameter file is C:\para.txt.

dcmpack /k password /i C:\para.txt /split /tempdir C:\temp

What is contained in the parameter file (C:\para.txt)

PACKAGING_SOURCE{
base_fullpath= E:
}
PACKAGING_INFORMATION
{
package_name=Windows10FCU
package_id=FD200304
version_revision=000001
generation=0000
cabinet_name=FCAB01
cabinet_id=F1
package_code=P
}
SYSTEM_CONDITIONS{
condition=H:c>=3072
directory=C:\Temp\windows
}

Note: Specify a value larger than the file size of the distributed file for condition.

When you execute the dcmpack command, the split files are registered as a package in the managing server.

Create a setup script and package it.

After distributing the update to the distribution-destination computers, create a script for executing the Windows 10 setup program and package the script.

The following shows an example of the setup script:

@echo off
"C:\Program Files\HITACHI\jp1itdma\bin\catAndValidatePackagingFile" /d "C:\Temp\Windows"
if not exist C:\Temp\Windows\setup.exe (
  echo setup.exe not found.
  exit /b 10
)
C:\Temp\Windows\setup.exe /auto upgrade /quiet /showoobe none

If you create the C:\temp\setupfcu.bat setup script, register it as a package in the managing server, with the settings shown in the following table:

Package attribute

Item

Value

Packaging information

Package name

Any

Package ID

FD200304_255#

Version/Revision

000001

Generation number

0000

Package type

User program, data

Cabinet name

FCAB01

Cabinet ID

F1

System conditions

Installation folder

C:\temp

External program

External program to be started after installation

C:\temp\setupfcu.bat

#: Check the package ID registered in step 5 and specify a value larger than the ID.

Perform remote installation.

Using Remote Install Manager or the dcminst command, distribute both packages created in steps 5 and 6 to the distribution-destination computers.

When the files packaged in steps 5 and 6 are distributed to the distribution-destination computers, the catAndValidatePackagingFile command is executed according to the setup script created in step 6. The Windows 10 update is then executed.

7.6.15 Enabling automatic switching from one higher distribution system to another for file distribution

A higher system (relay system) used to distribute data and software to computers might become unavailable in the event of a failure. In this case, you can configure a multi-polling environment and switch the connection destination to another relay system or a management relay server located at a higher level. At this time, you can configure the computer information registered in the original relay system in the form of an ID group to be automatically registered in the new connection destination (another relay system or a management relay server).

When the original relay system (the higher distribution system) recovers from the failure and becomes available again, the connection destination is switched back to the original relay system, and the registered ID group is also moved back to the original relay system.

To use this functionality, you have to first set higher distribution systems in the Settings to Perform Polling for Multiple Higher Systems area of the Communication Settings page during agent setup. In addition, you have to specify the following settings:

For Type of Polling for Multiple Higher Systems, select Hot Standby.

Select Poll higher systems according to their priority when the system starts.

Select the Perform a switchover of the higher system for distribution if polling fails for a specified period of time check box.

For n hours, specify the number of hours to wait before switching from one higher distribution system to another.

Check the Take over downloaded packages when switching higher-level systems if you want to continue downloading from a file that is being downloaded from a higher-level system for the original distribution.

Important

Keep the following in mind when enabling automatic switching from one higher distribution system to another for file distribution:

You cannot switch from one higher relay system (management server) to another.

You can only switch to another relay system (connection destination) under the same management relay server. In other words, you cannot switch to a relay system (connection destination) located under a different management relay server.

Even when the connection destination is automatically switched, the following information remains unchanged: Information specified in the file for connection destinations (itdmhost.conf) and the file for higher connection destinations (dmhost.txt) or the setting specified in the Higher Systems to Be Polled area under Settings to Perform Polling for Multiple Higher Systems on the Communication Settings page of the agent configurations.

If the version of the installed agent is earlier than JP1/IT Desktop Management 2 - Agent 12-00, even when you have enabled automatic switching from one higher distribution system to another, automatic switching does not occur.

If switching from one higher distribution system to another occurs while files are being distributed by an ID group job, the distribution of files are started all over again from the higher system that took over the file distribution process if Take over downloaded packages when switching higher-level systems is not checked. When the original higher distribution system becomes available again, the downloading is discontinued and the remaining files get deleted.

If the original higher distribution system is faulty or has been replaced with a new one and there are some remaining downloaded files on the agent, delete these files by creating a relay system having the same host name as the original higher distribution system.

The changes made to the agent configurations are applied at the following timings:

- If you change the n hours setting and 1 is set as the priority of the higher distribution system, the time setting becomes enabled when the policies are applied. If 2 or lower level of priority is set for the higher distribution system, the setting becomes enabled when the priority of the higher distribution system goes back to 1.

Note that the reference time to switching remains the same.

- If priorities are changed for Higher Systems to Be Polled, or if a higher system is replaced or deleted, the setting specified for the higher systems becomes enabled when the policies are applied. The original higher distribution system, however, is retained. Due to this, switchover after the specified hours (n hours) is not enabled until the priority of the higher distribution system goes back to 1.

- If you clear the Perform a switchover of the higher system for distribution if polling fails for a specified period of time check box, the system configuration is applied to the manager when agent computers restart after access to a higher distribution system whose priority is 1 becomes available.

Note

Automatic switching from one higher distribution system to another for file distribution requires the use of the functions described in the table below. For more details, see the relevant section or subsection, which is shown in the Refer to column beside each function.

Table 7‒3: Functions used to enable automatic switching from one higher distribution system to another for file distribution

Function name

Refer to

Multi-polling environment on an agent

3.4.2

Automatic changing of the agent connection destination

3.4.3

Distribution by using ID groups

5.3

Linkage of system configuration information with ID group information

5.4

The following figure shows an example of how automatic switching from one higher distribution system to another occurs for file distribution.

In this example, the multi-polling environment for the managed computer (Clt01) is configured to poll higher systems based on the following order of priority:

Relay system (Sub01)

Management relay server (Man01)

The following provides a detailed description of each step (represented by numbers (1) to (6)) illustrated in the above figure:

(1)

Polling fails because a relay system (Sub01) located at a higher level than the managed computer (Clt01) is down.

(2)

If the polling does not succeed within a specific period of time#, the managed computer (Clt01) starts polling the management relay server (Man01) located at a yet higher level. When the polling succeeds, the higher system is switched to the management relay server (Man01).

#

This is the time specified in the n hours area under Settings to Perform Polling for Multiple Higher Systems on the Communication Settings page of the agent configurations.

(3)

Because the higher system of managed computer (Clt01) is now switched, information regarding the managed computer (Clt01) is added to the system configuration information of the management relay server (Man01). This causes the ID group information to be changed as well.

Data and software can now be distributed from the management relay server (Man01) to the managed computer (Clt01).

(4)

When the relay system (Sub01) becomes available again, the managed computer (Clt01) switches the higher system to the relay system (Sub01).

(5)

Because the higher system of managed computer (Clt01) is now switched, information regarding the managed computer (Clt01) is added to the system configuration information of the relay system (Sub01). This causes the ID group information to be changed as well.

(6)

System configuration information on the management relay server (Man01) changes after the management relay server (Man01) detects the change of system configuration information on the relay system (Sub01). This causes the ID group information to be changed as well.

Data and software can now be distributed to the managed computer (Clt01) via the relay system (Sub01).

7.6.16 Priority distribution of packages

When packages such as highly urgent security patches are to be distributed, they can be distributed on a priority basis.

An overview of priority distribution is shown in the table below.

Table 7‒4: Overview of priority distribution

Function

Content

Priority setting

Specifies priority of packages when packaging.

Download sort

Agent that receives distribution job automatically changes order of download according to package priority.

The priority distribution and suspended distribution functions differ as described below.

Priority distribution function

When various packages are being distributed, the priority of the packages to be distributed can be defined. This function is used when it is desirable to increase the priority of important packages to be distributed.

Suspended distribution function

This function is used when it is desirable to distribute important packages despite distribution being suspended due to network loading.

With the priority distribution function, the order of packages to be distributed can be rearranged according to priority during distribution job execution.

(1) Definition of priority

With a priority distribution function, the priority will be expressed by a numeral from 1 to 9, indicating the level. The larger the number, the higher the priority.

The priority is a relative number that compares the order of priority between packages. The number itself has no meaning. For example, when an ordinary package with priority 7 is being distributed, packages with priority 6 will be distributed at a lower priority.

(2) Processing flow during distribution job execution when using or not using priority distribution function

The following explains the distribution job execution process that is followed when either using or not using the priority distribution function.

(a) Processing flow during distribution job execution when not using priority distribution function

The figure below shows the distribution job execution process that is followed when not using the priority distribution function.

Figure 7‒61: Processing flow during distribution job execution when not using priority distribution function

During job execution, a higher system will request an agent to perform distribution processing. The agent receiving the request will accept the job and perform downloading and installation. Also, the agent will periodically check with the higher system to see if the job has been executed. Other jobs will not be accepted during job execution but will be processed one at a time.

(b) Processing flow during distribution job execution when using priority distribution function

The figure below shows the processing flow when higher-priority distribution job 2 is executed during the execution of normal-priority distribution job 1 from a higher system, with the priority distribution function enabled.

Figure 7‒62: Processing flow during distribution job execution when using priority distribution function

When job 1 is being downloaded, the agent pauses downloading to confirm the job with the higher system. It is detected that job 2 is being executed, and job 2 is accepted. Since the job 2 package has higher priority than the job 1 package, downloading of job 1 is suspended and job 2 is downloaded and installed.

(3) Priority specification and operation examples

The priority can be determined and applied as follows:

Normally, priority 1 is used for distribution. If a package needs to be urgently distributed, priority 2 is used. Later, if a package needs to be distributed with even greater urgency, the priority is raised to 3 or higher.

Normal packages are distributed with the default priority of 5. If a package can be put off until later due to its large size or other reason, it is given a lower priority value, such as 4.

If a package was created with a previous version of Packager or has no priority, such as a UNIX agent or Mac agent package, the priority will be handled with the default value of 5.

When a stored package is distributed from Remote Install Manager with a priority of other than 1 to 9, it will be handled by the agent as default 5.

8 Managing Updates

This chapter describes how to package Windows updates for distribution by using the Remote Install Manager.

8.1 Acquiring the updates to be applied to clients

This section describes how to acquire Windows updates with JP1/IT Desktop Management 2.

It also describes how to enable automatic packaging of the acquired updates.

8.1.1 Acquiring updates

You can acquire Windows updates from the Windows Update Management dialog box. The Windows Update Management dialog box, which displays a list of updates provided by Microsoft Corporation, allows you to acquire any update (or updates) that you want.

Note:

To install a feature update to Windows 10, you have to manually download the ISO file from Microsoft's website.

You can display the Windows Update Management dialog box as follows:

Start the Remote Install Manager.

Select Options, and then Windows Update Management.

The Windows Update Management dialog box appears.

Figure 8‒1: The Windows Update Management dialog box

List of windows updates

Available updates and acquired updates are displayed in list format. By default, updates are displayed in the descending order of the released date, language, and the update program ID combination. By clicking the label, you can sort the displayed updates in ascending or descending order.

Display Settings button

Use this button to display the Display Settings dialog box from which you can set the items to be displayed in List of windows updates.

Package button

Use this button to package the updates selected in List of windows updates.

Description tab

This tab displays descriptions of the updates selected in List of windows updates.

Details tab

This tab displays details of the updates selected in List of windows updates.

Setup button

Click this button when you want to set the connection destinations that will be acquiring the updates, enable automatic acquisition of updates, and specify packaging settings.

Close button

Use this button to close the dialog box.

The rest of this subsection describes how to specify the settings necessary to acquire updates, how to acquire updates, and how to delete them.

(1) Specifying network settings for acquiring updates

To acquire updates, you have first to set an Internet connection method and other network information.

You can set network information for acquiring updates by using the Network Settings panel that you can display from the Windows Update Management dialog box. You can display the Network Settings panel as follows:

Click the Setup button.

The Setup dialog box appears.

Select the Network Settings tab.

The Network Settings panel appears.

Figure 8‒2: The Network Settings panel

By using the Network Settings panel, you can specify the settings described below.

(a) Connection settings

Specify the connection settings used for connecting to the Internet as well as for acquiring updates.

Connect to the Internet via a proxy server

To connect to the Internet by using the proxy server, select this check box.

By default, this check box is cleared.

Use the connection settings in Internet Options

To acquire updates by using the settings specified in the Internet Options of Internet Explorer, select this radio button. By default, this radio button is selected.

Specify a proxy server

To acquire updates by specifying a proxy server, select this radio button. If you select this radio button, you also have to specify the IP address and port number of the proxy server.

Authentication information

Specify the username and password to be used for authentication with the proxy server you have designated in Address. The username and password must not exceed 260 characters and 30 characters, respectively. You do not have to specify authentication information if authentication with a proxy server is not enabled.

(b) Communication settings

The following settings are available to deal with communication errors:

Retry interval to be used when a communication error occurs

Specify the retry interval in the range from 1 to 7,200 seconds, which is to be applied after the occurrence of an error during data transfer. By default, 5 seconds is set as the retry interval.

Maximum number of retries to be used when a communication error occurs

Specify the number of retries in the range from 0 to 999 times, which is to be applied after the occurrence of an error during data transfer. By default, 5 times is set as the number of retries. When 0 is specified, no retry is executed.

Retries are executed as many times as specified at the interval specified in Retry interval to be used when a communication error occurs.

Timeout period for a communication server

Specify the time-out period in the range from 0 to 60 seconds, which is to be applied upon the occurrence of an error during data transfer. By default, 20 seconds is set as the timeout period. When 0 is specified, the time-out period set by the OS is applied.

(2) Updating the list of updates

To update the updates displayed in List of windows updates, acquire the updates information from the support service site. For details, see the description of Setting information for connecting to the support service on the manual JP1/IT Desktop Management 2 Administration Guide.

When the updates information is successfully acquired, the updates displayed in List of windows updates become updated.

You can find the version of the acquired updates information in Version of the windows update information.

8.1.2 Packaging updates

By using the Windows Update Management dialog box, you can package the acquired updates. To package updates, you have to first set the information that will be set during packaging.

This subsection describes how to set up packaging and how to package updates.

Note:

Feature update program packaging can be operated with Windows 10 or Windows Server 2012 or later.

(1) Setting up packaging

You have to set package information that will be set during the packaging of updates.

When you package updates from the Windows Update Management dialog box, one package is created for each patch.

When you package updates, the name and ID of each package are automatically set.

For security updates:

Package name

If the security update is for except Windows 10 or earlier than Windows 10 1511, DPT-file-name-except-extension is set as the package name.

If the security update is for Windows 10 1511 or later, DPT-file-name-except-extension-version is set as the package name.

When the file name not including the extension exceeds 47 characters, the file name is truncated at 47 characters.

Periods (.) in the file name, if any, will be converted to underscores (_).

Package ID

The package name converted to uppercase is specified as the package ID. If, however, the package name exceeds 45 characters, it is truncated at 45 characters.

For a feature update to Windows 10:

Package name

DPT-Windows10-FU-version-CPU-architecture-language_sequential-number is set as the package name.

Package ID

The package name converted to uppercase is specified as the package ID. If, however, the package name exceeds 45 characters, it is truncated at 45 characters.

You can set package information by using the Packaging Settings panel that can be displayed from the Windows Update Management dialog box. You can display the Packaging Settings panel as follows:

Click the Setup button.

The Setup dialog box appears.

Select the Packaging Settings tab.

The Packaging Settings panel appears.

Figure 8‒3: The Packaging Settings panel

You can specify the following settings by using the Packaging Settings panel.

(a) Cabinet name

Select the method used to set the name of the cabinet in which to store the package.

Set automatically from the release date of the windows update

The year and month in which the update was provided by Microsoft Corporation is set as the cabinet name. For example, if the update was provided in September 2019, 201909 is set as the cabinet name. This radio button is selected by default.

Specify a value

Select this radio button when you want to set a cabinet name of your choice.

You can set a 1 to 16 characters long cabinet name. The following symbols and spaces, however, cannot be specified:

Backslash (\), slash (/), asterisk (*), double quotation mark ("), colon (:), and semicolon (;)

(b) Cabinet ID

Select how to set an ID of the cabinet to which to store the package.

Set automatically from the release date of the windows update

Select this radio button when you want a cabinet ID to be automatically set.

The set cabinet ID consists of the last digit of the year in which the update was provided by Microsoft Corporation and an uppercase alphabet in the range from A to L denoting the month of the year. For example, if the update was provided in September 2019, 9I is set as the cabinet ID. This radio button is selected by default.

Specify a value

Select this radio button when you want to set a cabinet ID of your choice.

Use 2 characters alphanumeric characters to specify a cabinet ID.

If there is an existing cabinet having the same ID that you have just set, the generated package is stored in the existing cabinet. In that case, the cabinet name that you have set on the Packaging Settings panel is displayed in the Windows Update Management window as the cabinet to which the package is stored.

(c) Package version/revision

Specify a version and revision of the package.

Version/revision

You can use 1 to 6 characters alphanumeric characters and a slash (/) to specify a version and revision. By default, 0000 is set.

(d) Package generation

Specify a package generation number.

Generation

Specify 1 to 4 characters alphanumeric characters as the package generation number. By default, 0000 is set.

(e) Installation target directory

Specify the directory in which to install the package.

Directory

Specify the directory in which to install the package, which must not exceed 32 characters. By default, C:\ITDMWK_DPT is set.

(2) Packaging updates or a feature update

(a) Packaging updates

To package acquired updates, select the check box beside the update you want to package in List of windows updates, and then click the Package button. You can also select and package multiple updates.

The status icons shown in the following table tell you whether the displayed updates have been packaged before.

Table 8‒1: Status icons that show whether the updates have been packaged before

No.

Status icon

Has the update been packaged before?

1

No

2

Yes

If you select an update that has not been acquired yet and then click the Package button, the selected update is first acquired and then packaged.

When you want to package an update first after installing the Remote Install Manager, you have to first start the Packager and log in to it. Once you are logged in, you can finish the Packager.

When the packaging of updates begins, a dialog box showing the progress of packaging appears. As the updates are packaged one after the other, a package is created for each packaged update according to the settings specified in the Packaging Settings panel. To cancel packaging, click the Cancel button during the packaging process. As soon as the packaging that was being executed when the Cancel button was clicked ends, the packaging process ends without packaging the rest of the updates. When the cabinet has a package with a name that is identical to the one that is about to be created, the creation of that package is skipped, and the packaging process continues.

When the packaging process is completed, a dialog box showing the packaging result appears.

Note

The acquired updates are deleted after they are packaged.

(b) Packaging a feature update to Windows 10

To package a feature update to Windows 10, you have to first download the ISO file with the feature update from Microsoft's website. After downloading the ISO file, select the check box beside the update you want to package in List of windows updates, and then click the Package button. The Feature Update Package dialog box appears.

Note:

You can select only one feature update to Windows 10.

Figure 8‒4: The Feature Update Package dialog box

You can specify the following settings in the Feature Update Package dialog box:

ISO files for feature updates

Specify the ISO file with a feature update that you have downloaded.

Specify the ISO file corresponding to the update which you have selected the checkbox including the language and the CPU architecture in List of windows updates.

Cabinet name

Specify a cabinet name, which must be 1 to 16 characters long. You cannot specify the following symbols or a space in a cabinet name:

Backslash (\), slash (/), asterisk (*), double quotation mark ("), colon (:), or semicolon (;)

Cabinet ID

Specify a cabinet ID by using 2 characters alphanumeric characters.

If you click the OK button in the Feature Update Package dialog box, the packaging of the feature update is executed.

When the packaging process is completed, a dialog box showing the packaging result appears.

(3) Distributing packaged updates

After the updates are packaged, the packages are stored in the specified cabinet. A script file for installing the update is automatically set for each package. The script file contains the following settings. Edit these settings if necessary.

Silent installation

The installer's dialog box is not displayed during the installation of an update. A dialog box indicating that a remote installation is currently in progress is not displayed either.

Suppression of client restart

Packages are designed to suppress the restart of clients upon the successful distribution of the packages. If you want to enable client restart following the installation of updates, select the Restart computer after installation check box in the package settings before distributing the packages.

Deleting the executive file of the installed update

After the update is successfully installed on the clients, the executable file of that update is deleted.

Furthermore, the directory to which to install the package, which you have set in the Packaging Settings panel, is specified in the package, and a script file is specified in the external program to be started after installation. In this way, you can apply patches to clients by simply distributing packages, without the need to specify any special settings.

When you want to distribute a specific update, we recommend that you create a destination group consisting of the clients to which the update has not been applied yet so that you can distribute the update to them without executing unnecessary jobs. You can group together the clients to which the update you want to distribute has not been applied yet, and distribute the update to them as follows:

Find the computers to which the update of interest has not been applied yet.

On the Not Applied Computers tab of the Update List view of the Security module, you can find the computers to which each update has not been applied. For details, see the JP1/IT Desktop Management 2 Overview and System Design Guide for information on how to find out if updates have been applied to computers.

Create a destination group consisting of the computers to which the update of interest has not been applied yet.

For details about how to create a destination group, see 5.2 Creating host groups.

Distribute the update to the created destination group.

After packaging or distributing updates to clients, we recommend that you delete those updates for which data is no longer necessary so as to save database space.

Important

A feature update to Windows 10 is very large, and distributing it during business hours can place a heavy load on the network. We therefore recommend that you start the computers during nighttime to distribute the update to them. Furthermore, split the destinations into groups of appropriate sizes so that the update can be distributed to all destinations overnight.

8.1.3 Automatically acquiring updates

The acquisition of patch information files and updates as well as packaging can all be performed automatically. Note, however, that the updates that can be automatically acquired are limited to OS updates from packaging run time to 60 days ago.

The automatic acquisition of updates is executed as follows:

The patch information file is acquired from the support service site.

In accordance with the settings that specify the updates to be acquired, the updates are acquired.

Updates are packaged according to the packaging settings.

For details about the packaging settings for updates, see 8.1.2(1) Setting up packaging.

For automatic acquisition of updates to work, you have to set the updates to be acquired by using the Automatic Settings panel. You can set the updates to be acquired as follows.

(1) Settings that specify the updates to be acquired

For automatic acquisition and packaging of updates to work, you have to set the types of updates to be acquired.

You can set the types of updates to be automatically acquired by using the Automatic Settings panel that is displayed from the Windows Update Management dialog box.

You can display the Automatic Settings panel as follows:

Click the Setup button.

The Setup dialog box appears.

Select the Automatic Settings tab.

The Automatic Settings panel appears.

Figure 8‒5: The Automatic Settings panel

You can specify the following settings on the Automatic Settings panel:

Windows updates automatically to be download and packaged

Select this check box when you want updates to be automatically downloaded and packaged. By default, this check box is cleared.

Execution Time of Package and Download

Set the time at which to automatically download and package updates. By default, 0:00 in UTC is set.

Target Product

Select the OSs for which to acquire updates.

The automatic acquisition of updates is executed for the OSs selected here. By default, all OSs are selected.

Update Type

Select the classes of the patches to be acquired. By default, Critical Updates and Security Updates are selected.

(2) Executing the automatic acquisition of updates

According to the settings on the Automatic Settings panel, the automatic acquisition of updates is executed.

Details about the error that occurs during automatic acquisition of updates are output to directory-to-which-JP1/IT-Desktop-Management-2-is-installed\LOG\DPT.LOG. The following figure shows the format of DPT.LOG.

Figure 8‒6: Format of DPT.LOG

The following table describes the cause and corrective action for each entry output to DPT.LOG.

Table 8‒2: Cause and corrective action for each log entry output upon the acquisition of a patch

Message ID

Message text

Cause

Corrective action

DPT006-E

Another instance of the application is already running.

The Windows Update Management dialog box is already open.

If you have opened the Windows Update Management dialog box from Remote Install Manager, close it. If you have not opened the Windows Update Management dialog box from Remote Install Manager, wait awhile and then try opening the Windows Update Management dialog box again.

DPT101-E

Database connection failed. Reason: error-message-of database

An attempt to connect to the database failed.

Confirm if the management server is up and running.

Check the Administrator user ID or password in the server setup.

DPT102-E

Error occurred while accessing database. Reason: error-message-of database

An error occurred during access to the database.

Check the environment used for communication with the management server.

Confirm if the management server is up and running.

DPT103-E

Unable to get a DSN to connect or DSN invalid. Reason: error-message-of database

An attempt to acquire the data source might have failed, or the data source might be invalid.

Try acquiring the data source again after starting Remote Install Manager.

DPT204-E

Unable to configure the proxy settings.

An attempt to connect to the proxy server failed.

Check the proxy server setting on the Network Settings panel.

DPT205-E

Error in network settings information. Unable to connect to the internet.

An attempt to connect to the network failed.

Check the network connection setting on the Network Settings panel.

DPT207-E

Unable to store the downloaded information in the file system.

An attempt to download the file failed.

Confirm that there is enough free space on the hard disk.

Confirm that you have the permissions to write to the directory in which JP1/IT Desktop Management 2 - Manager is installed.

DPT209-E

'server-name' login failure.

An attempt to log in to the server failed.

Check the Network Settings panel to confirm the authentication information on the applicable server.

DPT254-E

Unable to establish connection with the JP1/ITDM2 - Manager.

The Packager failed to connect to the server.

Check the connection destination set in the Packager.

Confirm that the network connection is working.

DPT255-E

Unable to communicate with the JP1/ITDM2 - Manager.

An error occurred while the Packager was trying to establish a connection with the server.

Confirm that the network connection is working.

DPT256-E

Unable to transfer the file to the JP1/ITDM2 - Manager.

The network connection might have gone down during packaging.

Confirm that the network connection is working.

DPT257-E

Package 'package-name' already exists.

It is possible that the cabinet to which you want to store the package contains a package having a package ID that is identical to that of the package you are trying to store.

Confirm if the cabinet to which to store the package contains a package having a package ID that is identical to that of the package you are trying to store. If the cabinet contains a package having an identical package ID, either delete that package or select a different cabinet to store the new package.

DPT258-E

Invalid password specified for JP1/ITDM2 - Manager login.

It is possible that the cabinet to which you want to store the package contains a package having a package ID that is identical to that of the package you are trying to store.

Confirm if the cabinet to which to store the package contains a package having a package ID that is identical to that of the package you are trying to store. If the cabinet contains a package having an identical package ID, either delete that package or select a different cabinet to store the new package.

DPT260-E

Unable to execute the command 'full-path-to-the-packaging-command'.

An attempt to start the Packager failed.

Confirm if the Packager is installed. If the Packager is not installed, install it.

DPT264-E

The packaging processing will now stop because an error occurred.

Packaging ended in failure.

Check the free space available on the hard disk.

(3) Disabling Windows update automatic acquisition of security policy

When automatically acquiring or distributing Windows update using Remote Install Manager, disabling Windows update automatic acquisition by security policy can reduce resource usage of the management server. For information regarding Windows update automatic acquisition by security policy, see the description of Managing Windows Updates in the manual JP1/IT Desktop Management 2 Overview and System Design Guide.

When disabling the Windows update automatic acquisition by security policy, set 0 to Mgrsrv_Patch_AutoPackageKind property of the configuration file (jdn_manager_config.conf). For the detail of Mgrsrv_Patch_AutoPackageKind property, see the Property List in the manual JP1/IT Desktop Management 2 Overview and System Design Guide.

9 Collecting Files from Managed Computers

This chapter describes how to collect files from managed computers (by using remote collection).

9.1 Remote collection operations

This section explains how to create a job that instructs remote collection from the managing server, execute the job, and restore collected files with the unarchiver.

9.1.1 Executing remote collection

Execute remote collection from the Remote Install Manager. To start the Remote Install Manager, from the Windows Start menu, select JP1_IT Desktop Management 2 - Manager, and then Remote Install Manager.

(1) Creating and executing a job

The procedure for creating a remote collection job is described below. For details about operations and settings, see 10.2 Creating a job.

In the System Configuration window or the Destination window, select Execute, and then Execute Job. Alternatively, in the Job Definition window, select File, and then Create Job.

The Define New Job dialog box appears.

In the Define New Job dialog box, specify the job type, and then click the OK button.

Jobs that can be specified for remote collection are as follows:

- Collect files from agent

- Remote-collect files from agent to relay computer

- Send package, allow client users to choose

In the Create Job dialog box, set the items on each panel.

The panels displayed in the dialog box and the settings on each panel are shown below. Note that the Job page, Destination page, and Schedule page are common to all jobs, but the Collect File page is only displayed when a job relating to remote collection is created.

Job page

Specify the desired job name.

For details about how to set up the Job page, see 10.2.3 Setting up the Job page.

Destination page

Specify the target system on which remote collection is to be performed. You must specify at least one system.

In a multi-server configuration, you can also specify a destination across relay systems and management relay servers.

For details about how to set up the Destination page, see 10.2.4 Setting up the Destination page.

Collect File page

Specify the software information to be collected by remote collection.

For details about how to set up the Collect File page, see 9.1.1(2) Setting up the Collect File page.

Schedule page

Specify the registration date/time, execution date/time, and execution time limit for the job.

For details about how to set up the Schedule page, see 10.2.5 Setting up the Schedule page.

Save or execute the job by clicking the Execute, Save, or Save and Execute button.

The job is saved or executed depending on the button you click.

Note:

If you execute Acquire collected files from relay computer job while executing Remote-collect files from agent to relay computer job, the following messages may be output. Even so, the process is properly operated and no action is required to be taken.

Source: JP1ITDM2 (DMC)

Type: Error

Event ID: 0

Source: JP1ITDM2 (DMC)

Type: Error

Event ID: 1002

Source: JP1ITDM2 (DMC)

Type: Error

Event ID: 8039

Source: JP1ITDM2 (DMC)

Type: Error

Event ID: 8006

(2) Setting up the Collect File page

To create a remote collection job, use the Collect File page of the Create Job dialog box to specify the files to be collected and the directory where the collected files are to be stored. In the Target file section, you can specify individual files or directories. If you specify a directory in the Target file section, all the files in the specified directory are collected and saved as a single archive file. This archive file is assigned a file name with file extension dmz.

Figure 9‒1: Collect File page

Target file

This section displays the files or directories that have been specified as the target for remote collection. A maximum of 100 files or directories can be specified as the target for remote collection.

If multiple directories of the same name are located on different drives, and are specified as the target for remote collection, make sure these directories do not contain any files of the same name. Any such files are overwritten when they are collected by remote collection.

Directory for saving collected files

Specify which directory to store the files to be collected by remote collection. In the specified directory, the files are collected by remote collection, using the following name format:

<Destination host name or IP address (based on a node identification key)>-<host ID>\<archive file name>

In the Collect File page, you can perform the following operations:

Adding target files

Deleting target files

Specifying remote collection options

(a) Adding target files

If you click the Add button on the Collect File page, the Specify Target File dialog box appears. In this dialog box, specify the target files or directories to be added.

Figure 9‒2: Specify Target File dialog box

In the File name by full path field, specify the path to the file or directory to be added as the target for remote collection. Note that the job generates an error if you specify \ at the end of the path name for a file or directory to be added. The path name must be no more than 256 single-byte characters for Windows computers or no more than 63 single-byte characters for UNIX computers. If the full path to the file exceeds 259 single-byte characters at the time of file restoration, the file cannot be restored.

(b) Deleting target files

Select the file or path to be deleted from the Target file box, and then click the Delete button.

(c) Specifying remote collection options

If you click the Details button on the Collect File page, the Detailed Options For Remote Collection dialog box appears. In this dialog box, you can specify remote collection options such as collection timing, whether to compress the files at the time of collection, and the external programs to be started.

Figure 9‒3: Detailed Options For Remote Collection dialog box

The setting items in this dialog box are shown below.

Collection timing

In this drop-down list, select the timing of remote collection from the relay system, management relay server, or managed computer.

While the agent is running

If you select this option, remote collection is performed while the system on the relay system, management relay server, or managed computer is running. If the system is not running when the job is executed, remote collection is performed next time the system is started.

When the agent starts

If you select this option, remote collection is performed when the system is started for the first time after a job is executed on the relay system, management relay server, or managed computer.

Compress

In this drop-down list box, you can specify whether to compress the files when remote collection is performed. The default is Enabled.

Start external programs on the agent

If you specify settings in this section, user-specific processing can be executed on the relay system, management relay server, or managed computer at the time of remote collection by starting external programs at the following timings:

Before collection

This option starts the specified external program immediately before remote collection. Specify this option when you want to perform data processing (such as data format conversion) on the relay system, management relay server, or managed computer before remote collection.

After collection

This option starts the specified external program immediately after remote collection.

Upon collection error

This option starts the specified external program when a remote collection error occurs. Note that you cannot specify this option for UNIX computers.

For the path name of an external program to be started, specify up to 128 characters for Windows or up to 64 characters for UNIX (including the drive name). Note the following rules when specifying an external program:

If the path to the external program includes spaces, enclose the entire path with double quotation marks ("). Note, however, that the path cannot contain spaces when external programs are executed in UNIX.

The path to an external program cannot include the string %HITACHI_REG\xxx% (where xxx is any string). This string is a path specific to each Hitachi program product, and is reserved for JP1/IT Desktop Management 2. General users cannot specify this string.

(3) Checking execution results

Job statuses are monitored by the managing server at certain intervals and displayed in the Job Status window. The Job Status window displays the statuses of all jobs, and the icon at the beginning of each job name indicates the job type.

: Collect files from agent job

: Remote-collect files from agent to relay computer job

: Acquire collected files from relay computer job

: Delete collected files from relay computer job

If you select a remote collection job in the left pane of the window, the path to the file collected by remote collection is displayed as job details in the right pane. To restore an archived file, check the path to the file before using the unarchiver.

For details about the contents displayed in the Job Status window or how to display detailed information for each job or how to re-execute jobs, see 10.4 Checking the job status.

9.1.2 Restoring collected files

Use the unarchiver to restore files that were archived or compressed (during remote collection) to the original format.

To start the unarchiver, select IT Desktop Management 2 - Manager, and then Unarchiver.

When the unarchiver starts, the IT Desktop Management 2 Unarchiver window appears.

Figure 9‒4: IT Desktop Management 2 Unarchiver window

The right pane of the Unarchiver window displays the directories and files in sorted order. However, if the drive is a FAT file system, the directories and files are not sorted.

Note:

If the user who initiates the Unarchiver does not have administrator permission for the operating system, elevate the user to administrator level before proceeding.

(1) Restoring files

Use the Job Status window to check which directory the file to be restored belongs to before restoring the file.

You can only restore files that are stored in a directory. You cannot restore any files stored immediately under the drive.

To restore files collected by remote collection:

Select the file or directory to be restored, select File, and then Restore File (or click ).

The Restore dialog box appears.

Figure 9‒5: Restore dialog box

Destination directory

Specify the restoration destination directory. The restored file is stored in the specified directory. You must specify a valid path for the destination directory.

The following conditions must be met, depending on the file system you use

- The path to the destination directory must be no more than 247 single-byte characters.

- The full path to the file to be restored must be no more than 256 single-byte characters.

The format of the full path is shown below.

restoration-destination-directory + created-directory + restored-file-name-or-directory-name

The format of created directory is as shown below.

archive-file-name + _ + archive-file-storage-directory

- Do not use the following single-byte symbols:

* " : < > | ?

For details about restoration destination directories for multiple files to be restored, see 9.1.2(2) File configuration at the restoration destination.

Contents

This frame displays the name and contents of the file to be restored.

Archive file name

This box displays the name of the file to be restored. If you select a directory as the restoration target, the names of all the files in the directory are displayed.

List of archived files

This box lists the contents of the file that you selected in the Archive file name box.

Set the necessary items, and then click the OK button.

File restoration processing starts. The Restore File dialog box is displayed during restoration processing.

You can also restore a file by dragging it from Explorer, and then dropping it on the unarchiver icon or into the IT Desktop Management 2 Unarchiver window.

(2) File configuration at the restoration destination

If you restore only one archive file, the restored files are stored immediately under the directory specified in the Destination directory field of the Restore dialog box. However, when you restore multiple archive files at the same time, different archive files might contain files with the same names. For this reason, when you restore multiple archive files, create directories with the following name under the directory specified in the Destination directory field, so that the restored files can be correctly stored in these directories.

archived-file-name(-excluding-the-extension)_parent-directory-name

In the following example, multiple archive files are restored and stored in the destination directory called C:\TEMP\DATA.

Archive file name

File contents

C:\user\PC0001\ED0001.dmz

E10.txt, E11.txt

C:\user\PC0001\ED0002.dmz

E20.dat, E21.dat

C:\user\PC0002\ED0001.dmz

E10.txt, E11.txt

C:\user\PC0002\ED0002.dmz

E20.dat, E21.dat

Figure 9‒6: Configuration of the restoration destination directory

9.1.3 Deleting files on relay systems and management relay servers

A relay system or management relay server used during remote collection temporarily stores all files collected passing through them. These stored files are automatically deleted at the same time as they are collected into the managing server. If, for example, a Remote-collect files from agent to relay computer job is executed, all files stored on the relay system or management relay server are deleted when an Acquire collected files from relay computer job is executed.

However, you might want to forcibly delete any files remotely collected in a relay system or management relay server if these files are not transferred to the managing server, for example. In such a case, delete the files by executing a Delete collected files from relay computer job from the managing server.

9.1.4 Notes on executing remote collection

Note the following points when executing a remote collection job and using the unarchiver:

Remote collection might fail under the following conditions:

When the files to be collected by remote collection are being used on the managed computer

When remote collection is performed from a Windows network drive

When remote collection is performed from a directory without access permissions

The Acquire collected files from relay computer and Delete collected files from relay computer jobs specify a relay system or management relay server as the destination. If you specify an agent as the destination, an error occurs, or the job remains in a running state (execution status: 20%).

Some of the directories or files displayed in the Create Job dialog box or the IT Desktop Management 2 Unarchiver window might be deleted by another application while the window is being displayed. Even if any deletion occurs, the screen is not refreshed with the latest information. Accordingly, if you select a file or directory that has already been deleted, the File access failed error dialog box appears.

In the Directory for saving collected files field on the Collect File page, specify a directory on the server. Take special care when the management server and the Remote Install Manager are located on different PCs.

If you specify a non-existent drive in the Directory for saving collected files field, a directory is created in the JP1/IT Desktop Management 2 - Manager installation directory\mgr\temp directory by using the host name of the managed computer, and the collected files are stored in this directory.

Remote collection from a Windows system and remote collection from a UNIX system cannot be performed as a single job.

Note the following when executing a remote collection job for a UNIX system:

For the file to be collected, specify a path starting from the root directory. However, there is no need to specify a drive.

You can specify only one file or directory to be collected. If you specify more than one file or directory, only the first specification is valid.

For the collection path name, specify no more than 63 single-byte characters. If you specify more than 63 characters, only the first 63 characters are valid (but no error occurs).

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 (but no error occurs).

The path to the external program to be started cannot contain spaces.

You cannot specify arguments in the external program to be started.

In the Directory for saving collected files field on the Collect File page, specify a directory on the local drive. Files collected by remote collection cannot be stored in a network drive.

The Target file section of the Collect File page and the IT Desktop Management 2 Unarchiver window do not support UNC paths. If you use files and directories on the network, allocate them to a network drive before using them.

The maximum total size of the files that can be collected by remote collection at a time is 2 gigabytes.

The maximum total number of files or directories that can be collected by remote collection at a time is 65,531. However, if the files or directories to be collected by remote collection include files with short file names, these files are also included in the count.

Do not log off from a machine while restoring the archive files collected by using the dcmcoll command.

If the restoration of archive files by using an unarchiver or the dcmcoll command fails due to the excess of the path length after restoration, a disk space shortage or such, the files that have been already restored might remain. In this case, delete the files manually.

If you execute Delete collected files from relay computer job while executing Remote-collect files from agent to relay computer job, the files still under the process of the collection will be deleted and they might not be collected by Acquire collected files from relay computer job.

Additionally, depending on the timing of execution of the job, the files still under the process of the collection might remain. In this case, re-execute Delete collected files from relay computer job to delete the remaining files.

9.2 Remote collection operation examples

This section introduces remote collection operation examples that meet various purposes.

9.2.1 Processing data on the managed computer before remote collection

It might be a good practice to process data on the managed computer before the data is collected by remote collection and used on the managing server. For example, if the database on the server is updated according to the data processed by each computer, and the programs on the server must be able to interpret the data from the managed computers, the data must be processed. It might be possible to process data after it is collected into the server by remote collection. However, any attempt to process a large amount of data sent from each computer at the same time will impose a heavy load on the server.

In this case, it is convenient to use a function that starts an external program immediately before remote collection. Operations such as the example shown above can be handled by specifying a data processing program as an external program (to be started immediately before remote collection).

The following figure illustrates the remote collection of data processed by managed computers.

Figure 9‒7: Remote collection of data processed by managed computers

Use the Detailed Options For Remote Collection dialog box to specify the external program to be started immediately before or after remote collection. This dialog box is displayed by clicking the Details button on the Collect File page of the Create Job dialog box.

Figure 9‒8: Detailed Options For Remote Collection dialog box

9.2.2 Remote collection of user application error information

Remote collection can collect information about user application program errors that have occurred on managed computers. To make this possible, each user application program must output error logs to the specified location on each computer. Files collected by remote collection are stored separately for each computer so that error information can be collected by remote collection separately for each computer, even if errors occur on multiple computers at the same time.

The following figure illustrates remote collection of error information from user applications.

Figure 9‒9: Remote collection of error information from user applications

9.2.3 Remote collection of Windows event log information

Windows error information is mainly output to event logs so that the error information can be viewed in the Windows Event Viewer. However, the Event Viewer cannot display event logs from multiple computers at the same time.

To address this issue, if you distribute a program for converting event logs into text files to each computer, and perform remote collection of event logs converted into text files, you can collect and view the event logs from multiple computers.

The following figure illustrates the remote collection of event log information.

Figure 9‒10: Remote collection of event log information

Create a program that converts event logs into text files.

You can use Windows API functions to create a program. Create a program that opens event logs with the OpenEventLog() function, reads each entry sequentially with the ReadEventLog() function, and then outputs the read data to a text file.

Perform a remote installation of the created program on each computer.

This step is not required for computers that have such a program already installed.

Perform a remote collection of event logs.

Specify the text file conversion program (that you have just created) as the external program to be started immediately before remote collection. For the remote collection target, specify the files output by the text file conversion program, rather than directly specifying event logs.

10 Managing Jobs

To execute functions such as remote installations and remote collections on managed computers, use Remote Install Manager to create a set of instructions called "jobs" that will instruct the managed computers.

This chapter describes how to create and manage jobs.

10.1 Creating and executing a job

To execute functions such as remote installation and remote collection, use Remote Install Manager to create and execute a job that provides action definitions. After you execute a job, check the job status and result, and respond accordingly.

The following describes the steps in creating and executing a job.

Creating a job

Use the Create Job dialog box to specify the job name, job destination, job conditions and to create the job. For details about how to do this, see 10.2 Creating a job.

You can customize the window used to create a job, for example by changing the default values or item order. For details about how to do this, see 10.2 Creating a job.

Figure 10‒1: Create Job dialog box

You can save a created job. By editing a saved job, you can easily create similar jobs. A job is saved in each folder in the Job Definition window. For details about how to save a job, see 10.3 Executing and saving a job.

Figure 10‒2: Job Definition window

Executing a job.

During job creation, you can choose to immediately execute a job after the creation or specify a date and time to execute the job. Job execution timing can be specified on the Schedule page.

Figure 10‒3: Schedule page

For details about how to execute a job, see 10.3.1 Executing and saving a job.

Checking the execution results.

The Job Status window allows you to check the job status and results. The Job Status window shows the status of the executed jobs for each folder or job hierarchically. The left pane provides the hierarchical structure such as folder and job, and the right pane shows the progress and execution status information inside the hierarchical structure selected in the left pane. For details about how to check the job execution results, see 10.4 Checking the job status.

Figure 10‒4: Job Status window

Reacting to the result.

Check the results of a job in the Job Status window. If the job has completed successfully, delete the job. If the job has not completed successfully, you need to re-execute the job for that destination. You can use the Job Retry dialog box to request job re-execution.

Figure 10‒5: Job Retry dialog box

If a problem occurs in a relay system, and managed computers under the relay system cannot execute a job, you can execute a job using another relay system. If there is a job being split distributed, you can forcibly complete the split distribution by transferring the remainder of the package in a single transfer.

For details about such job deletion and re-execution, see 10.5 Actions after checking the job results.

Note:

If the job name and execution timing of a job is identical to those of another job, the deletion or re-execution of job cannot be properly operated. Do not create such jobs.

10.2 Creating a job

Job creation starts by selecting a job type in the Define New Job dialog box. Then use the Create Job dialog box to specify other detailed information.

10.2.1 Opening the Define New Job dialog box

The Define New Job dialog box is used to specify a job type.

Figure 10‒6: Define New Job dialog box

How to open the Define New Job dialog box differs depending on which of the following windows of Remote Install Manager is used to create the job:

(1) The Job Definition window

Select File, and then Define New Job.

(2) The Destination window or System Configuration window

Select Execute, and then Execute Job, or click the Create Job button.

(3) The Package window

In the Package window, only the following types of jobs can be created by selecting Execute, and then Execute Job (or clicking the Create Job button):

Install package jobs

Transfer package to relay computer jobs

Send package, allow client users to choose jobs

At this point, if you select a host or package that a job execution is targeting, that information will be set up in the Create Job dialog box, which is displayed later.

If you want to create an Install package, Transfer package to relay computer, or Send package, allow client users to choose job, you can also open the Define New Job dialog box by a drag and drop operation. In addition, in this case, the selected host or package information will be set up in the Create Job dialog box, which is displayed later. The following shows the steps using a drag and drop operation:

Drag a package (or cabinet) icon from the Package window.

If you select a cabinet icon, all packages in the cabinet will be targeted.

Drop it to the host icon in the Destination window or the System Configuration window.

The Define New Job dialog box opens.

10.2.2 Pages displayed in the Create Job dialog box

The following table shows the list of pages provided by the Create Job dialog box for each job type.

Table 10‒1: Pages displayed in the Create Job dialog box

No.

Job Type

Page

Job

Destination

Package

Job Distribution Attributes

Collect File

Acquisition Target

Search Target

Schedule

Client Control

1

Install package#

Y

Y

Y

Y

--

--

--

Y

Y

2

Transfer package to relay computer

Y

Y

Y

Y

--

--

--

Y

Y

3

Batch delete packages on relay computer

Y

Y

--

--

--

--

--

Y

Y

4

Collect files from agent

Y

Y

--

--

Y

--

--

Y

Y

5

Remote-collect files from agent to relay computer

Y

Y

--

--

Y

--

--

Y

Y

6

Acquire collected files from relay computer

Y

Y

--

--

--

--

--

Y

Y

7

Delete collected files from relay computer

Y

Y

--

--

--

--

--

Y

Y

8

Send package, allow client users to choose

Y

Y

Y

Y

--

--

--

Y

Y

9

Get system information from computer (UNIX)#

Y

Y

--

--

--

Y

--

Y

Y

10

Get software information from computer (UNIX)#

Y

Y

--

--

--

--

Y

Y

Y

11

Get system configuration information

Y

Y

--

--

--

--

--

Y

Y

12

Hold report

Y

Y

--

--

--

--

--

Y

Y

13

Cancel holding of report

Y

Y

--

--

--

--

--

Y

Y

14

Suspend file transfer

Y

Y

--

--

--

--

--

Y

Y

15

Resume file transfer

Y

Y

--

--

--

--

--

Y

Y

Legend:

Y: Displayed. --: Not displayed.

#

This job is also applicable to agents for Mac.

References for how to set up the pages are shown below:

Job page

For details about how to set up the Job page, see 10.2.3 Setting up the Job page.

Destination page

For details about how to set up the Destination page, see 10.2.4 Setting up the Destination page.

Package page

For details about how to set up the Package page, see 7.3.2 Setting up the Package page.

Job Distribution Attributes page

For details about how to set up the Job Distribution Attributes page, see 7.3.3 Setting up the Job Distribution Attributes page.

Collect File page

For details about how to set up the Collect File page, see 9.1.1 Executing remote collection.

Acquisition Target page

For details about how to set up the Acquisition Target page, see G.1(2) Setting up the Acquisition Target page.

Search Target page

For details about how to set up the Search Target page, see G.2(2) Setting up the Search Target page.

Schedule page

For details about how to set up the Schedule page, see 10.2.5 Setting up the Schedule page.

Client Control page

For details about how to set up the Client Control page, see 10.2.6 Setting up the Client Control page.

10.2.3 Setting up the Job page

The Job page allows you to check the job type, and specify the job name.

Figure 10‒7: Job page

Job name (Required)

By default, job name is displayed as job-typeyy_mm_dd_hh_mmss, but you can change the job name to facilitate management.

The job-type portion differs depending on the job. For example, the job-type is RemoteInstall for a package that is to be installed from a remote location.

If you modify the default job name, a unique name of a maximum of 32 single-byte characters (or 16 doublebyte characters) can be specified. Note the following when you specify a job name:

Note that you cannot specify the space character or the following symbols:

\, /, *, ", : , ', !, |, ., <, >, ?

Job names are not case sensitive.

Job Type

The job type you have specified in the Define New Job dialog box is displayed. The job type cannot be changed.

10.2.4 Setting up the Destination page

The Destination page allows you to specify a host or group that the job is targeting.

Figure 10‒8: Destination page

Select a Destination type, and then click the Add button to add a destination. The ID group, host group, and managed computers that are specified as target destinations appear in the Destination field. A destination that has already been added can be removed, and the route setting for the destination can be modified.

The following section describes how to specify a destination type, how to add a destination, and how to change a route.

(1) Destination type

To specify a destination on the Destination page, select a Destination type first. There are two destination types:

Host group

ID group

(a) Host group

Select this destination type when you want to specify a group of hosts or a specific host (a management relay server, relay system, or agent) as a job destination. If you change the Destination type of a job specifying an ID group to Host group, the job will be registered as the following type of job. The job is destined for the relay system or management relay server managing the ID group, or for managed computers registered in the ID group.

When you specify a host group or a host, jobs are executed on a different host depending on the job type. The following table shows the relationship between the specified destination and the job type.

Table 10‒2: Relationship between the specified destination and the job type

No.

Job Type

Specified destination

Agent

Relay system

Host group

Management relay server

1

Install package

Y

Y

A

Y

2

Transfer package to relay computer

N

Y

R

Y

3

Batch delete packages on relay computer

N

Y

R

Y

4

Collect files from agent

Y

Y

A

Y

5

Remote-collect files from agent to relay computer

Y

Y

A

Y

6

Acquire collected files from relay computer

N

Y

R

Y

7

Delete collected files from relay computer

N

Y

R

Y

8

Send package, allow client users to choose

Y

Y

A

Y

9

Get system configuration information

N

Y

N

Y

10

Get system information from computer (UNIX)

Y#1

N

Y#2

N

11

Get software information from computer (UNIX)

Y#1

N

Y#2

N

12

Hold report

N

Y

R

Y

13

Cancel holding of report

N

Y

R

Y

14

Suspend file transfer

N

Y

R

Y

15

Resume file transfer

N

Y

R

Y

Legend:

Y: The job is executed on the specified host.

N: The job is not executed on the specified host.

R: The job is executed on the relay system or management relay server that belongs to the specified host group.

The job is also executed on a relay system or management relay server that belongs to a host group under the specified host group.

A: The job is executed on all the hosts that belong to the specified host group.

The job is also executed on all the hosts that belong to a host group under the specified host group.

#1

The job is executed only when the destination is an agent for UNIX or an agent for Mac.

#2

The job is destined for an agent for UNIX or an agent for Mac that belongs to the specified host group.

(b) ID group

Choose whether you want to specify an ID group as a job destination. If you specify an ID group, the job is executed on the computers that belong to that ID group.

The ID group destination type is useful when you want to execute a job on a newly added computer. If an ID group job has been saved in a system connected to a computer, when the computer is registered in the ID group, the job is automatically executed on the computer. Note that if system-configuration information and ID group information are linked, when the route was changed because the destination settings on the computer registered in the ID group were changed, the ID group jobs destined for the computers on the old route are deleted, and ID group job destined for the computer are registered and executed with the new route.

The ID group destination type can be selected for the following job types:

Install package#

Send package, allow client users to choose

Get system information from computer (UNIX)#

Get software information from computer (UNIX)#

#

This job is also applicable to agents for Mac.

If you specify an ID-management relay computer that includes a route, you cannot specify multiple ID groups for destinations. Split the job for each ID, and specify the job. For example, if the destination is ID01 and ID02, create two jobs with the following destination:

host-ID!%ID01

host-ID!%ID02

(2) Adding a destination

The following describes how to add a destination on the Destination page.

Select a destination type on the Destination page, and click the Add button.

The Add Destination dialog box appears. You can adjust the size of the Add Destination dialog box to a comfortable size. If you change the size, the dialog box will be displayed with that size from the next time you open it.

Figure 10‒9: Add Destination dialog box

From the Destination/Agent list, that appears when you select From and Host group or ID group/Relay system, select a host that you want to add to the Destination list.

From

Select which window you want to use to acquire the information for a new destination: System Configuration window or Destination window.

Host group or ID group/Relay system

If you select System Configuration in From, relay systems or management relay servers are displayed in a hierarchical structure. If you select Destination in From, host groups or ID groups are displayed.

Destination/Agent

If you select System Configuration or Destination in From, hosts included in the management relay server or relay system selected in Host group or ID group/relay computer or hosts included in the host group are displayed as a list. Clicking Network in Host group or ID group/Relay system displays the computers placed directly under the network.

Enter route

If you want to add a host that is not included in the System Configuration window, specify a route to the host. Specify host names using ! as a delimiter, for example, host-name1!host-name2.

Describe the host name as a host ID.

For details about how to specify a host name, see 5.1.2 Assigning host names in JP1/IT Desktop Management 2.

If you want to specify the route of a job whose destination is set to a relay system, specify the relay system name to both the route and the destination.

Example:

Specifying a relay system as a destination

host-id-of-relay-system!host-id-of-relay-system

To enter an ID group, put % at the beginning of the ID group. The host group cannot be specified. Note that if you specify an ID group managed by a relay system, specify only a single ID group.

Example:

Specifying an ID group (ID01) managed by a relay system in a configuration that uses a relay system

host-id-of-relay-system!%ID01

Specifying an ID group (IDSERVER) managed by JP1/IT Desktop Management 2

%IDSERVER

Select a host, host group, or an ID group you want to add as a destination in the left pane, and click the > button.

The selected item will be added to the Destination pane on the right. Clicking the >> button will add all hosts or computers shown in the Destination/Agent field to the Destination field.

If you want to remove a specified item from the Destination field, click the < button.

Click the OK button.

The Add Destination dialog box closes, and the specified destinations appear in the Destination field on the Destination page.

(3) Changing a route

Clicking the Change Route button on the Destination page allows you to change the execution route of a job. This allows operation by avoiding a relay system on which a problem has occurred, and executing the job via an alternate relay system.

Note the following when you change a route:

You cannot change the route to a management relay server, or the route to a relay system or agent under a management relay server.

The route cannot be changed if the destination of a job is a host group or an ID group.

If you change a route of a Send package, allow client users to choose job, the result of the job may remain in Waiting for execution status. In this case, redefine the relay system or the host connected from managed computers on which the Send package, allow client users to choose job is to be executed on an upper level host indicated by the new route.

The Start the target computer if it is not running command on the Client Control page cannot be used.

To change a route:

Select a route you want to modify in the Destination page, and click the Change Route button.

The Change Transmission Route dialog box appears. The destinations and all relay systems selected in the Destination page are shown with the route defined in the System Configuration window.

Figure 10‒10: Change Transmission Route dialog box

Select a relay system route you want to modify, and click the Change, Move, or Add button.

Change button

The Select Relay System to be Used dialog box appears. The managed computers under the relay system specified in the Change Transmission Route dialog box are moved to the relay system specified in this dialog box.

Add button

The Select Relay System to be Added dialog box appears. The relay system and the managed computers under the relay system specified in this dialog box are moved to the relay system specified in the Change Transmission Route dialog box.

Move button

The Select Relay System to Which Client Will Move dialog box appears. The managed computers specified in the Change Transmission Route dialog box are moved to the relay system specified in this dialog box.

Reset button

The order of the relay system and the managed computers under the relay system listed in the Change Transmission Route dialog box is reset to the condition before the modification.

You can also move the managed computers or relay system in the transmission route tree with a mouse drag and drop operation. You can click the name of an icon, and directly edit the name.

Click the OK button.

The Change Transmission Route dialog box closes, and the modified route is shown on the Destination page.

(4) Important notes on specifying a destination

The following section contains important notes on specifying a destination.

(a) Limitation on the destination length

The status of a job whose destination name is 256 characters or more will not be displayed in the Job Status window. You must specify a destination of 255 characters or less.

(b) Changing the destination type

If you change the destination type of a job whose destination type is already set to a host group to an ID group, destinations other than the ID group will be deleted. On the other hand, if you change the destination type of a job whose destination type is already set to an ID group to a host group, a job destined for a relay system that manages the ID group or the managed computers registered in the ID group are registered.

(c) Handling a job for which a nonexistent destination is specified

Do not create a job by specifying a nonexistent destination. If you execute such jobs, it may slow down the operation of Remote Install Manager or other adverse effects may occur.

If a specified destination includes a nonexistent destination, the job executes targeting only the existent destination. Note that the status of a job with a nonexistent destination after the job execution depends on the settings in the Settings for Address Resolution panel specified during JP1/IT Desktop Management 2 - Manager setup. If a When resolution of IP address fails item is set to The job ends in error, the status will be Error, and if it is set to The job starts., the status will be waiting for execution.

(d) Specifying the name of a management relay server

When you directly enter the name of a management relay server or specify the route to a destination via a management relay server, you must specify the host name of the management relay server, regardless of the node identification key.

(e) Setting an operation key

If the key item is set to Host name in the Address Resolution panel specified during JP1/IT Desktop Management 2 - Manager setup, or in the Specify ID Key for Operations in the Relay system settings in the agent configurations, select Use Network in Windows for How to resolve IP addresses.

If you select Use the system configuration information for IT Desktop Management 2 for How to resolve IP addresses, a job execution request cannot be sent to a destination if you specify the destination as below. However, when The job starts. is selected for When resolution of IP address fails, these kinds of jobs are executed by polling from the destination.

When a route is specified in Enter route in the Add Destination dialog box.

When a destination is specified by changing the route.

10.2.5 Setting up the Schedule page

The Schedule page allows you to specify job execution date and time for the managing server and managed computers.

Note that the specified execution date and time are monitored every minute, so that the execution may be delayed for one minute at the maximum.

Figure 10‒11: Schedule page

(1) Specifying the date and time when a job is executed on the managing server

You can select if the managing server executes a job immediately, or executes the job at a date and time you specified.

Immediate execution

Select this option if you want to execute a job immediately.

Server starts the job at specified date/time

Select this option if you want to execute a job at a specified date and time. You can also specify Registration date/time and Execution time limit of the job. To specify a date, enter the last two digits of the year.

Note that if you select Server starts the job at specified date/time for a job and save the job, the execution date/time setting of the saved job will be changed to Immediate execution when the job is executed with the menu or the F5 key after the job is saved.

Registration date/time

Specifies the date and time when the job was registered to the managing server. Select the checkbox if you want to specify the Registration date/time.

Scheduling many jobs at the same execution date and time may temporarily overload the managing server, and delay execution of the jobs. Specifying the Registration date/time can prevent this delay.

Execution date/time

Specifies the date and time when the job is executed.

Execution time limit

Specifies the time limit for execution of a job that was not executed at the specified date and time. Select the checkbox to specify the execution time limit.

Generally, a job is executed at the specified execution date and time, but the job may not be executed, for example, when the managing server is not running at the specified date and time. The job that was not executed will be executed when the managing server started the next time if the execution limit has not been passed. If the execution limit has passed, the job remains, and is treated as a job whose execution limit has passed. Check for and delete jobs whose execution limit has passed.

Note that if you execute a job by specifying the execution date and time in the managing server, avoid taking the actions below until the execution date and time. Such jobs cannot be executed, and the job definition is deleted.

Changing the job name

Deleting all destinations or packages

(2) Specifying the date and time when a job is executed on the agent

Specify the date and time when a job is to be executed on the agent. You can specify the date and time of execution on agents only for the following jobs:

Get system information from computer (UNIX)#

Get software information from computer (UNIX)#

#

This job is also applicable to agents for Mac.

The following explains how to specify the date and time of job execution on agents. As is the case in specifying the date and time of job execution on managing servers, you can select whether to execute a job immediately or at a specified date and time.

Agent starts the job now

Select this option if you want to execute a job immediately.

Agent starts the job at specified date/time

Specify the date and time when the job is to be executed on the agent. For Year, enter the last two digits of the year.

Set the execution interval

Set if periodically executing jobs from the agent side.

Execute every day

Specify if executing each day.

Execute every week

Specify if executing each week.

Execute every month

Specify if executing each month.

Set the execute time

Specify the timing of job execution on the agent. For the Get software information from computer (UNIX) job, you can select only While System Is Running.

When System Starts up

Executes the job when the system on the agent starts. If you specify a date and time of execution, the job is executed when the system starts for the first time after the specified date and time.

While System Is Running

Executes the job while the system on the agent is running. If you specify a date and time of execution, the job is executed at the specified date and time. However, if the agent is not running at the specified date and time, the job will be executed next time the system starts.

When System Stops

Executes the job when the system on the agent terminates.

10.2.6 Setting up the Client Control page

The Client Control page allows you to set up the system so that the system starts the job destination PC to execute the job if the PC is not running. You can also specify to have the system shut down the destination PC after starting it. If the destination is an agent for UNIX, Shut down the client after the job execution is ignored. In addition, you cannot specify to shut down a computer for the following jobs executed on an agent for UNIX or an agent for Mac: Get system information from computer (UNIX) and Get software information from computer (UNIX).

Figure 10‒12: Client Control page

Start the target computer if it is not running

If the destination PC is not running, the system starts the PC and then executes the job. This start operation is destined for PCs that belong to the ID group or host group specified as the destination of the job. Therefore, if a relay manager or management relay server on the route to the destination is not running, the job transfer stops there.

Shut down the client after the job execution.

Select this option if you want to shut down the destination PC after starting it.

Do not select this option if you remote install JP1/IT Desktop Management 2 - Agent. The remote installation may not be completed normally. For the Get system information from computer (UNIX) and Get software information from computer (UNIX) jobs, this item is not displayed.

10.3 Executing and saving a job

A job can be executed in the following three ways:

Create a job and execute it immediately.

Create a job, save it, and then execute it.

Find a specific destination, and execute a job.

Saving a job allows you to check, modify, and execute the job. A saved job can be executed after making corrections, or can be reused many times by making modifications.

The following sections describe how to execute a job and how to manage saved jobs.

10.3.1 Executing and saving a job

This section describes how to execute a job immediately after creation, and how to save a job after creation and then execute it. This section also describes how to find a specific destination and then execute a job.

(1) Executing a job immediately after creating it

To execute a job immediately after creating it:

Click the Execute button in the Create Job dialog box.

The job is executed, and the Create Job dialog box closes.

Note that if you want to specify a date and time when a job is executed, you need to save the job first.

(2) Executing a job after saving it

A job is saved in each folder in the Job Definition window of Remote Install Manager. The following describes how to execute a job that has been created and saved.

(a) Saving a job

A job is saved in the Job Definition window of Remote Install Manager.

To save a job:

Click the Save button or Save & Execute button in the Create Job dialog box.

The Save Job dialog box appears. You can adjust the size of the Save Job dialog box to a comfortable size. If you change the size, the dialog box will be displayed with that size the next time you open it.

Figure 10‒13: Save Job dialog box

Specify a folder in which you want to save the job, and click the OK button.

The job is saved in the selected folder.

If you have clicked the Save & Execute button in step 1, the job is saved and executed at the same time.

(b) Executing a saved job

You can check or execute a saved job in the Job Definition window of Remote Install Manager.

Figure 10‒14: Job Definition window

To execute a job selected in the Job Definition window:

Select a job you want to execute in the Job Definition window.

The selected job is highlighted.

Select Execute, and then Execute Job.

The job is executed. You can also execute the job in either of the following ways:

Click the Execute Job button.

Press the F5 key.

Pressing the F5 key opens up a confirmation dialog box that asks the user whether to execute the job. If you execute a job with the In the future, do not display the confirmation message check box selected, the confirmation dialog box will not appear again when you press the F5 key. If you want to re-open the confirmation dialog box, press the Ctrl + F5 keys to execute a job.

Note that even if you have selected Server starts the job at specified date/time in the Schedule page during job creation, the execution date/time setting of the job will be changed to Immediate execution when the job is executed with the menu or the F5 key after the job is saved.

(3) Finding a specific destination and executing a job

The following describes how to execute a job after finding a specific destination in the System Configuration window or Destination window. You can find a destination by an IP address, destination name, host group name, ID group name, and host registration date. You can also find a host on which a job error has occurred, and connect to the host via a remote control function to investigate the cause of the error.

The following table shows available search keys for the System Configuration window and Destination window:

Window name

Find by Name

Find by Dates

System Configuration window

Y

Y

Destination window

Y

N

Legend:

Y: Possible.

N: Not possible.

(a) Find by name

This section describes how to execute a job by finding a destination by a name such as an IP address, destination name, host group name, ID group name.

Select Options, and then Find in the System Configuration window or Destination window.

The Find dialog box appears. The items in the Find dialog box differ depending on whether it is opened from the System Configuration window or the Destination window.

Figure 10‒15: Find dialog box opened from the Destination window

Destination (only when opened from the Destination window)

Select this option if you want to find a destination name.

Host group/ID Group (only when opened from the Destination window)

Select this option if you want to find a host group name and ID group name.

Find what

Specify a search string of no more than 64 bytes. Note that you cannot specify the space character or the following symbols:

\, /, *, ", : , !, |, <, >, ?, %, @, '

The system searches for a destination that includes the specified string.

Find host names

Select this option if you want to search for a host name.

This option is disabled if you open the Find dialog box from the Destination window and select the Host group/ID Group option as a search target.

Find IP addresses

Select this option if you want to search for an IP address.

This option is disabled if you open the Find dialog box from the Destination window and select the Host group/ID Group option as a search target.

Find whole word only

Select this check box if you want to search for a string that exactly matches the specified search string.

Match case

Select this check box if you want to perform a case-sensitive search.

Specify a search condition and click the Find button.

The search starts, and the results appear in the Search results list at the lower part of the dialog box.

You can adjust the size of the Find dialog box to a comfortable size.

In the Search results list, right click a destination to which you want to execute a job, and select the Execute Job menu.

In the Define New Job dialog box that appears, you can execute a job for the selected destination.

(b) Find by dates

This subsection describes how to execute a job by searching for a host according to the date when the host was registered on the management server. For details about how to search by date, see 6.1.2 Searching for hosts by date and 6.1.5 Example of maintenance of system configuration information.

Select Options, and then Find in the System Configuration window.

The Find dialog box opens.

Select the Find by Dates tab.

Figure 10‒16: Find by Dates page

Specify a range of dates for your search.

Range

Specify one or both of the start date and end date for your search. Specify in the format of MM/DD/YY, where MM represents the month, DD represents the day, YY represents the last two digits of the year. The specifiable date range is from January 1, 1971 to December 31, 2037.

To specify only the start date or the end date, clear the check box for the date you omit.

For the past n months

Specify the past number of months you want to include in the search range. The specifiable number of months is from 1 to 999. The default value is 1. If you have performed a search once, the number you specified previously will appear. However, if the date specified by the past number of months becomes earlier than the searchable date limit of January 1, 1971, the search range is set to from January 1, 1971 to the current date.

For the past n days

Specify the past number of days you want to include in the search range. The specifiable number of days is from 1 to 999. The default value is 1. If you have performed a search once, the number you specified previously will appear. However, if the date specified by the past number of days becomes earlier than the searchable date limit of January 1, 1971, the search range is set to from January 1, 1971 to the current date.

After specifying a search condition, click the Find button.

The search starts, and the results appear in the Search results list at the lower part of the dialog box.

You can adjust the size of the Find dialog box to a comfortable size.

In the Search results list, right click a host on which you want to execute a job, and select the Execute Job menu.

In the Define New Job dialog box that appears, you can execute a job on the selected host.

(c) Using a remote control function

This section describes how to search for a specific host, and then connect to the host with the remote control function. This helps you to easily investigate the cause of an error when a job error occurs on a host.

Select Options, and then Find in the System Configuration window or Destination window.

The Find dialog box appears.

Search for a destination.

For details about how to do this, see 10.3.1(3)(a) Find by name and 10.3.1(3)(b) Find by dates.

In the Search results list, right click a destination and select the Start Remote Control menu.

The controller starts up.

If one of the conditions below applies, the Start Remote Control dialog box appears. In this case, perform step 4.

When you selected multiple hosts

When you performed a search by an ID group name and host group name, and multiple hosts are returned in the search results

Figure 10‒17: Start Remote Control dialog box

Select a host on which you want to start a controller, and click the Start button.

The controller for the selected host starts.

Note the following if a PC that uses Remote Install Manager specifies Host name for the operation key:

If you select a host name to connect to the host, the address must be able to be resolved in the PC using Remote Install Manager.

If you select a single host, and you have the IP address information of the host, you can select either the host name or IP address to connect to that host. However, in an environment where destination IP address changes dynamically, you may not be able to connect to the intended PC if you select an IP address.

10.3.2 Managing saved jobs and folders

This section describes how to create a folder, and how to edit a saved job and folder.

(1) Creating a folder

Creating a folder for each job type facilitates the job management. Folders can be created in a hierarchical structure. You can create folders no more than four levels deep.

To create a folder:

Bring up the Job Definition window, and select File, and then Create Folder (or click the Create Folder button).

The Create Folder dialog box appears.

Enter a folder name.

Specify a unique name for the folder of no more than 32 single-byte characters (or 16 doublebyte characters). Note the following when you specify a folder name:

Note that you cannot specify the space character or the following symbols:

\, /, *, ", :, ', !, |, ., <, >, ?

Folder names are not case sensitive.

After specifying the items, click the Add button.

If you want to add more folders, repeat step 3.

Click the Exit button.

The Create Folder dialog box closes.

(2) Changing a folder name or job name

This section describes how to change the name of a folder or job that has already been specified.

Note that if you change a folder name or a job name before the job is executed, the scheduled job will be deactivated.

Bring up the Job Definition window, and select a folder or job whose name you want to change.

The selected folder or job is highlighted.

Select File, and then Rename.

Specify a name, and press Enter.

The name will be changed to the specified name.

(3) Modifying a saved job

You can modify the destination, execution date and time, and execution limit for a saved job.

To modify a saved job:

Select a job you want to modify in the Job Definition window, and select Edit and then Modify (or double click the selected job).

The Edit Job dialog box appears.

This dialog box allows you to modify the job definitions with steps similar to the Create Job dialog box.

Figure 10‒18: Edit Job dialog box

After changing the definitions, save or execute the job.

(4) Deleting a folder or job

This section describes how to delete a folder or a job. Once deleted, the folder or job cannot be recovered. If you delete a folder, jobs and lower-level folders inside the folder will also be deleted.

(a) Deleting a folder or job

Bring up the Job Definition window, and select a folder or job you want to delete.

The selected folder or job is highlighted.

Select Edit and then Delete.

A deletion confirmation dialog box appears. Clicking the Cancel button closes the dialog box without deleting the selection.

(b) Important notes on deleting a folder or job

A job that has an execution date and time set up on the Schedule page appears in both the Job Definition window and the Job Status window. If you want to delete such a job before the specified date and time, you need to delete it not only from the Job Definition window but also from the Job Status window. If you delete such a job only from the Job Definition window, an error will occur at the specified execution date and time because the job definition has been deleted.

10.4 Checking the job status

You can check a job's status in the Job Status window. This section describes how to check a job's status. After completing the operations required after the check, see 10.5 Actions after checking the job results.

10.4.1 Settings required to check a job's status

To check a job's status, the following items must be set up.

(1) Specifying the recorded results

If too many completed jobs are left among the list of results of completed jobs, the operation of Remote Install Manager may slow down. Therefore, we recommend that you only leave jobs with an execution status that requires your attention, among the results of completed jobs. The recorded result can be specified for each job destination type in the Result Recording Options panel in the Setup for Distribution by Using Remote Install Manager window during JP1/IT Desktop Management 2 - Manager set up.

(a) Normal job

If a job is a normal job (a job whose destination is not an ID group), you can select an execution status you want to record in the managing server from Error and Completed.

Note that this setting is invalid for the following jobs and all execution statuses are recorded on the managing server:

Send package, allow client users to choose

Get system information from computer (UNIX)#

Get software information from computer (UNIX)#

#

This job is also applicable to agents for Mac. Therefore, if the destination is an agent for Mac, this setting is also invalid and all execution statuses are recorded on the managing server.

(b) ID group job

If a job is an ID group job, you can select an execution status you want to record in the managing server from Error, Finished, and Completed.

This setting is applied to all jobs of the same job type on the computers that belong to the ID group managed by the relay system. In the case of a job as described in 10.4.1(1)(a) Normal job, on a computer that belongs to the ID group managed by the managing server, this setting is disabled and the job is recorded for any execution status.

(2) Setting up a monitoring interval for the execution status

The job status is monitored by the managing server at regular intervals. You can set the job execution monitoring interval in the Job Environment dialog box.

If you specify a shorter job monitoring interval, the load may increase, and may affect operations of other applications. We recommend that you specify a monitoring interval of approximately 30 minutes to 1 hour.

To open the Job Environment dialog box, select Options and then Job in the Job Status window.

Figure 10‒19: Job Environment dialog box

Monitor job

Specifies the job monitoring interval. The system monitors the job execution status when the Enable monitoring check box is selected. You can specify a job monitoring interval between 1 second to 10 days, 23 hours, 59 minutes, and 59 seconds. By default, this check box is selected and the monitoring interval is set to 15 minutes.

If you specify the monitoring time interval, the items selected in the left pane and all the items in the right pane in the Job Status window are updated at every job monitoring time. If you have not set up a job monitoring time, or if you want to update the information at a time other than the job monitoring timing, double click a folder hierarchy one level above the item whose status you want to check, in the left pane of the Job Status window, to refresh the view.

Read Agents Partially

The Job Status window allows you to manage the number of hosts to read (i.e. amount of data) for the jobs to be displayed.

Match window size

The system reads the amount of data for twice the number of hosts that can be displayed in the window. The unread data will be newly read when you manipulate the vertical scroll bar the next time.

Specify the number

Specify a value from 1 to 2,147,483,647. Regardless of the number of hosts that can be displayed in the window, the specified number of hosts are read when the window is displayed. If you check the results for a job executed on hundreds or thousands of hosts, specify this option and limit the amount of data to be read. However, if the specified number of hosts is smaller than twice the number of hosts that can be displayed in the window, the system reads the amount of data for twice the number of hosts that can be displayed in the window.

10.4.2 Important notes on checking a job status

This section describes provides important notes on checking a job status.

(1) Holding result reports from relay systems and management relay servers

When a job is executed from the managing server, the managed computers automatically report the results to a higher level system. If the job is executed via relay systems or management relay servers, the relay systems or management relay servers collect their execution results and the results of execution on their managed computers, and send them to a higher level system.

However, if the job execution results are reported from a relay system or management relay server when the network is congested, the network might be overloaded. In such a case, you can temporarily suspend reporting from the relay system or management relay server. To suspend reporting, execute a Hold report job whose destination is set to the relay system or management relay server. Similarly, to resume the reporting, execute a Cancel holding of report job.

To check whether the reporting from the relay system or management relay server has been suspended, select the relay system or management relay server in the System Configuration window or Destination window and then open the Attributes page.

If the relay system or management relay server in reporting suspension status is an ID-management relay computer, the execution results of the jobs specifying that ID group are also held on the relay system or management relay server.

(2) If the display of the host executing a job disappears

If the display of the host executing a job disappears from the Job Status window, the job that was being relayed might have been deleted by Remote Install Manager on the management relay server.

(3) If the status of a job executed through a relay system or management relay server does not change

For the following jobs, the execution status on Remote Install Manager does not change until the file transfer between the relay system or management relay server and a lower system finishes.

A job on which split distribution of the package is specified#

A job that failed to start a lower system from the relay system or management relay server through which the job passed

#: If the Notify JP1/IT Desktop Management 2 - Manager of the status of the split distribution executed on the lower JP1/IT Desktop Management 2 - Agent check box has been selected in the Settings to send notifications to JP1/IT Desktop Management 2 - Manager page opened from the Relay system settings in the agent configurations, the execute status will change.

10.4.3 Items displayed in the Job Status window

This section describes the items displayed in the Job Status window.

(1) Items

The Job Status window shows the following information.

Figure 10‒20: Job Status window

Status

This column shows the current job status in percentage (%). In the case of a configuration where the managing server is connected to a managed computer via a relay system, 50% represents that the job has been transferred to the relay system. If there are multiple relay systems, the value depends on the number of relay systems.

The job status changes as follows:

0%

The managing server has created the job, but has not been transferred yet.

20%

The managing server has started the job transfer. In the case of a split distribution job, the display changes in small increments depending on the split distribution progress rate.

50%

The job has been transferred to the relay system. This value will not be displayed in a configuration without a relay system. In the case of a split distribution job, if the Notify JP1/IT Desktop Management 2 - Manager of the status of the split distribution executed on the lower JP1/IT Desktop Management 2 - Agent check box has been selected in the Settings to send notifications to JP1/IT Desktop Management 2 - Manager page opened from the Relay system settings in the agent configurations, the display changes in small increments depending on the split distribution progress rate.

70%

The job is transferred to the managed computer, and is waiting for execution. This value will not be displayed for a job that is executed immediately after being transferred to the managed computer.

100%

The job processing has finished.

Result

This column displays the current job condition. For details about the job execution status, see 10.4.3(3)(a) Types of job execution status.

Finished/Errors/Total

Displays the number of finished jobs, the number of errors, and the total number of jobs.

Selected destination

Displays the route of the job, and indicates to what point of the route the processing has finished. A route shown in blue indicates that the processing has started, and a route shown in black indicates that the processing has not been finished.

Scheduled date/time

Displays the date and time when the job is to be executed.

Execution time limit

Displays the time limit by when the job is executed.

Execution date/time

Displays the date and time when the job was executed.

Scheduled installation date/time

Displays the date and time when the package is to be installed.

(2) Execution status color

Job statuses are color-coded. The following describes the relationship between the display colors and the execution statuses.

Green

Represents a job that is completed.

White

Represents a job that is running, or has not been executed because the computer is not running.

This kind of job includes jobs waiting for a user to log in to the managed computer, jobs that were set to be executed the next time the computer starts and with Waiting for installation status, and jobs that are waiting for collection during remote collection.

Dark gray

Represents a job whose execution is suspended.

Red

Represents a job on which an error occurred.

Orange

Represents a job on which a communication error occurred during the file transfer. This does not include a communication error between an ID-management relay computer and a managed computer.

Only the following types of jobs can have the Communication error status.

Install package#

Send package, allow client users to choose

Transfer package to relay system

Get system information from computer (UNIX)#

Acquire collected files from relay computer

Get system configuration information

Hold report

Cancel holding of report

Note that a setup in the managing server is required before you can monitor a job with a communication error.

#

This job is also applicable to agents for Mac. Therefore, the job is also subject to monitoring of communication errors when the destination is an agent for Mac.

Light gray

Represents a job that is currently being deleted on a relay system, management relay server, or a managed computer. These kinds of jobs are not displayed by default.

For details about how to display job(s) that are being deleted, see 10.4.4(6) Displaying a job that is being deleted.

If a job has multiple statuses, the job is displayed with the color associated with the lowest or worst status. For example, in a job that remotely installs multiple packages, if some packages are Completed, some are Running, and others are Error, the job is displayed in red (the color for Error).

(3) Job execution status

This section describes how to check the transition of job status by progress, color, and status displayed in the Job Status window.

For details about how to check transition of the status of an ID group job, see 10.4.5 Checking the status of an ID group job.

(a) Types of job execution status

The following table shows the types of execution statuses displayed in the Job Status window.

Table 10‒3: Types of the job execution statuses

Job execution status

Job Status

Status Color

Description

Waiting for execution

0%

White

The job was created, but waiting to be transferred from the management server.

Running

20% to 70%

White

The job is being transferred to the managed computer, or the job is running.

Startup failure#1

0% to 50%

White

The system tried to transfer the job, but the relay system or managed computer is not running.

Suspended

20% to 70%

Dark gray

Execution of the job is suspended due to a suspension instruction.

Resumed

20% to 70%

White

Execution of the job is resumed due to a resuming instruction.

Waiting for installing/collecting

70%

White

The job is waiting for remote installation or collection or is being processed on the managed computer.

Installation rejected

70%

Light gray

Package installation cannot be rejected, but an installation rejection command (rdsinsset -d) was executed on an agent for UNIX.

Completed#2

100%

Green

Execution of the job has completed successfully.

Error

0%

Red

An error occurred during execution.

Communication error

0% to 70%

Orange

A communication error occurred during file transfer.

Now being deleted

None

Light gray

A job is being deleted on a relay system, management relay server, or managed computer.

#1

If the system is set to break down the cause of a Startup failure, the following statuses are displayed:

If the machine was not started because JP1/IT Desktop Management 2 is stopped: Startup failure. (IT Desktop Management 2 is stopped.)

If the machine was not started because the PC is shut down: Startup failure (Machine is powered off)

If the machine was not started due to a cause other than the above (for example a network problem): Startup failure

Note that if a packet for checking that the machine is started is lost, the system displays Startup failure (Machine is powered off).

#2

If the job type is Install package, the following statues are displayed:

When the installation package is executed: Completed

The package has been distributed but was not executed: Completed (distributed)

(b) Transition of the job execution status

The job execution status changes with the job status. The following figure shows the transition of the job execution status.

Figure 10‒21: Transition of the job execution status

(4) Example transition of the job execution status

The following table shows the status transition of a job that installs a package when the system starts.

Table 10‒4: Example transition of execution status (Install package job)

Job status

Item displayed in the Job Status window

Progress of the job

Job color

Execution status

The job was created, but is waiting to be transferred from the managing server.

0%

White

Waiting for execution

The transfer of the job has been started.

20%

White

Running

The relay system issued a job suspension instruction in response to a suspension instruction from the managing server.

50%

Dark gray

Suspended

The relay system issued a job resuming instruction in response to a job resuming instruction from the managing server.

50%

White

Running

The system tried to transfer the job, but the managed computer is not running.

50%

White

Startup failure

The job was transferred to the managed computer.

70%

White

Waiting for installing/collecting

The managed computer is started, and execution of the job has started.

70%

White

Running

An error occurred on the job.

0%

Red

Error

Execution of the job completed successfully.

100%

Green

Completed

10.4.4 Displaying the job status

You can display the status for each hierarchy in the window, or display all the jobs or job details at the same time. Displaying the jobs or job details at the same time helps you to efficiently view the status across multiple folders. The following section describes each display option listed below:

Displaying information in each folder hierarchy,

Displaying all the jobs under a folder hierarchy,

Displaying detailed information of all the jobs under a folder hierarchy,

Selecting displayed date/time items,

Sorting the information by specifying a condition,

Displaying a job that is being deleted.

For details about how to display the status of an ID group job, see 10.4.5 Checking the status of an ID group job.

(1) Displaying information in each hierarchy

To display information in the selected hierarchy:

Select View and then Specified Information Only in the Job Status window.

Select a folder hierarchy in which you want to display the information.

The information in the selected folder hierarchy is displayed.

Figure 10‒22: Job Status window (displaying the information for each folder hierarchy)

(2) Displaying all the jobs under a folder hierarchy

To display all the jobs under a selected folder hierarchy:

Select View and then All Jobs in the Job Status window.

Select a folder hierarchy in which you want to display the information.

All the jobs under the selected folder hierarchy are displayed.

Figure 10‒23: Job Status window (displaying all the jobs under a folder hierarchy)

The following job information is displayed:

Job/Destination/Package

Displays the job name, host or package on which the job was executed.

Execution date/time

Displays the date and time at which the job was executed.

Result

Displays the execution status of the job.

Scheduled date/time

Displays the date and time on which the job is to be executed.

Execution time limit

Displays a time limit by which a job is to be executed.

Selecting View and then Display Job Detailed Information after selecting a job in the right pane (or double clicking the job) opens the Display Job dialog box.

Figure 10‒24: Display Job dialog box

The Display Job dialog box includes the following items:

Job name

Displays the name of the job.

Date/time items

Displays the information about the date and time specified for the job.

Job execution date/time

Displays the date and time at which a job was executed.

Scheduled job execution

Displays the date and time at which a job is to be executed.

Job execution time limit

Displays a time limit by which a job is to be executed.

Detailed job status

Displays the number of each detailed job status. Total represents the total of the relevant numbers.

(3) Displaying detailed information of all the jobs under a folder hierarchy

To display detailed information of all the jobs under a selected folder hierarchy:

Select View and then All Job Details in the Job Status window.

Select a folder hierarchy in which you want to display the information.

All the details of the jobs in the selected folder hierarchy is displayed.

Figure 10‒25: Job Status window (displaying detailed information of all the jobs under a folder hierarchy)

The job detailed information as below is displayed.

During remote collection, the path of the files remotely collected (name of the directory in which a file is stored or file name) is displayed in the job details. To recover an archived file, check the file path and then use the unarchiver.

Job/Destination/Package

Displays the job name, or host or package that the job is targeted.

Destination

Displays the name of the host that the job is targeted.

Package

Displays the name of the package that the job is targeted.

Package ID

Displays the name of the package ID that the job is targeting.

Version

Displays the component version of the package that the job is targeting.

Generation

Displays the generation number of the package that the job is targeting.

Execution date/time

Displays the date and time at which the job was executed.

Result

Displays the execution status of the job.

Installation timing

Displays the timing when the package is to be installed.

On top of the above items, you can also display more detailed information such as package details, the cause of the job error, and maintenance code. To do so, take the following steps:

Select View and then Display Job Detailed Information after selecting a job details in the right pane (or double click the job details).

The Detailed Information dialog box appears.

Figure 10‒26: Detailed Information dialog box

Package information

Displays the package-related information including the package name, package ID, and package storage limit.

Details

Displays the job-related information such as job type, job execution route, and maintenance code. The Description field also gives information such as the cause of a job error.

Note that when UNIX is displayed in Error function, the number displayed in Error reason is the message ID posted by the UNIX version or Mac version of JP1/IT Desktop Management 2 - Agent.

Split distribution information

This section is activated in the case of a split distribution package. This section displays the package split size, transfer interval, and split distribution status.

The split distribution status is shown in transferred size/total size (in the units of kilobytes).

The transferred size will be reset to 0 and starts again every time the job passes a relay system.

(4) Selecting displayed date/time items

To specify a date/time item to be displayed:

Select View and then Set Display in the Job Status window.

The Set Display dialog box appears.

Figure 10‒27: Set Display dialog box

This dialog box has the following items:

Display date/time of the job in the Job Status window

Specify a date/time item to display. An item whose check box is selected is displayed.

Scheduled date/time

Displays the date and time when the job is to be executed.

Execution time limit

Displays the time limit by when the job must be executed.

Execution date/time

Displays the date and time when the job was executed.

Scheduled installation date/time

Displays the date and time when the package is to be installed.

Display system information as a comment about the destination client in the Job Status window

You can select this option if you want to display information other than the key items about job destination. The item set as a key item is grayed out. Specifiable value is Subkey, Host ID, or Comment.

Select one or more items you want to display, and click the OK button.

The specified items will be displayed.

(5) Sorting the information by specifying a condition

The order of the information displayed in the right pane of the Job Status window can be sorted by specifying a condition. The list of job statuses can be sorted based on the job execute date/time or destination name, so that you can check the execution statues more easily.

To sort information:

Select View and then Arrange in the Job Status window.

The Sort Order dialog box appears. Specify the sort order in this dialog box and click the OK button. The order of the information displayed in the right pane of the Job Status window is changed.

Figure 10‒28: Sort Order dialog box

Priority

Specifies a sort key (reference item).

A sort operation is first performed based on the 1st priority key. If there are multiple items with the same order after the sort, they are sorted with the 2nd priority key. If there are still multiple items with the same order after the sort, they are sorted with the 3rd priority key.

If you do not specify any key, select None.

Sort with unexecuted jobs at top

Use this option to select if unexecuted jobs are displayed at the top or bottom of the list. By default, unexecuted jobs are displayed at the top of the list. Clear this check box to display them at the bottom of the list.

(6) Displaying a job that is being deleted

When you have deleted a job in the Job Status window, you can leave the deleted job displayed until the job is deleted from the relay system, management relay server, or managed computer that is the transfer destination. A job which has not been deleted yet is displayed with (Now being deleted), and the job disappears after it is deleted from the entire system. However, to check whether the job was deleted before it was executed on the relay system, management relay server, or managed computer, use information about the packages installed on the agent.

To display a job being deleted:

In the Job Status window, select View and then Jobs Being Deleted.

(Now being deleted) is displayed at the end of the name of a job that has not finished being deleted on a relay system, management relay server, or managed computer. Finished/Errors/Total displays the total number of jobs that are being deleted.

Figure 10‒29: Job Status window (Jobs Being Deleted)

10.4.5 Checking the status of an ID group job

Among the jobs whose destination is set to an ID group, execution status for the following types of jobs can be checked in the Job Status window.

Install package

Send package, allow client users to choose

The following sections describe how to check the status of a job whose destination is set to an ID group.

(1) Displaying the job status for each ID-management relay computer

To check the execution status for each relay system that is managing ID group jobs:

In the Job Status window, clear the View ID Job Agents check box in the View menu.

Double click an ID group job.

The ID group is displayed under the job.

Figure 10‒30: ID group is displayed under a job in the Job Status window

Double click the ID group.

Under the ID group, the relay system managing the ID group appears. A package name is displayed in the Job/Destination/Package pane on the right.

Figure 10‒31: The relay system is displayed under an ID group in the Job Status window

(a) Types of execution status for ID group jobs

The table below shows the types of execution status for ID group jobs that are displayed in the Job Status window when the View ID Job Agents check box is cleared.

For the types of execution status for ID group jobs that are displayed in the Job Status window when the View ID Job Agents check box is selected, see 10.4.3(3)(a) Types of job execution status.

Table 10‒5: Types of execution status for ID group jobs

Job execution status

Status

Color representing the status

Description

Waiting for execution

0%

White

The job was created, but waiting to be transferred from the managing server.

Registering

Registering

White

The job is being transferred to an ID-management relay computer.

The job is being transferred from a manager to an ID-management relay computer.

Standing by

Standing by

White

The job is being transferred from an ID-management relay computer to a managed computer, or the job is running.

Finished

Finished

Green

The package was deleted by a relay system.

Waiting for execution

0%

Red

An error occurred during the execution.

(b) Transition of the status of an ID group job

The following figure shows the transition of the execution status of an ID group job when the View ID Job Agents check box is cleared.

Figure 10‒32: Transition of the execution status of an ID group job

(2) Displaying execution status for each managed computer

This section describes how to check execution status on the managed computers for an ID group job.

Select View, and enable the View ID Job Agents in the Job Status window.

Double click an ID group job.

The ID group is displayed under the job.

Figure 10‒33: ID group is displayed under a job in the Job Status window

Double click the ID group.

The managed computers that belong to the ID group are displayed under the ID group.

Figure 10‒34: Managed computers are displayed under the ID group in the Job Status window

Click a managed computer.

The job status on the selected managed computer is displayed in the right pane.

Figure 10‒35: The job status on the selected managed computer is displayed in the Job Status window

Double clicking a package opens a Detailed Information dialog box.

Figure 10‒36: Detailed Information dialog box

(3) Important notes on checking the status of an ID group job

Note the following when you check the status of an ID group job:

The managing server cannot display the status of the a job on which a communication error has occurred between the relay system managing the ID group and a managed computer.

10.4.6 Displaying the jobs with a specific execution status

JP1/IT Desktop Management 2 - Manager allows you to display jobs that have a specific execution status. This enables you to display only the jobs that ended in error or jobs that completed successfully. To display jobs that have a specific execution status, select View and then Filter to open the Filter dialog box, and specify the view conditions. To display entire jobs after displaying jobs with a specific status, select View and then All Job Types.

The following describes the items you can specify with the Filter dialog box.

Figure 10‒37: Filter dialog box

Jobs to display

Specifies the types of jobs to display.

All jobs

Select this option to display all the jobs.

Host group job

Select this option to display jobs whose destination is set to a node.

ID group job

Select this option to display jobs whose destination is set to an ID group.

Job type

Displays jobs that have one or more selected job types. To select a job type, select a check box on the left of the job type name. By default, all the job types are selected.

Job execution status

Displays a job that has one or more selected execution statuses. To select a status, select a check box on the left of the job execution status. This item can only be selected when View - All Jobs is selected in the Job Status window.

If you select multiple execution statuses, all the jobs that satisfy at least one of the selected execution statuses are displayed.

The following describes each execution status.

All successfully completed

Displays the jobs whose execution has completed successfully.

Error in job(s) sent client

Displays the jobs on which an error occurred during execution.

Installation/collection job(s) waiting for client response

Displays the jobs waiting for remote installation or collection on a relay system, management relay server, or managed computer.

Job(s) are running/registering/waiting/startup failure

Displays the jobs that are Registering or Standing by, among the running jobs or ID group jobs.

Job(s) have not been sent to client

Displays the jobs that have not been executed among the scheduled jobs.

Now being deleted

Displays the jobs that are being deleted on a relay system, management relay server, or managed computer.

Job status

Displays the details of the selected execution status. To select a job status, select a check box on the left of the job status. This item can only be selected when View - All Job Details is selected in the Job Status window.

If you select multiple job statuses, all the jobs that satisfy at least one of the selected job status are displayed.

The following describes each job status.

Completed

Displays the details of the jobs whose execution has completed successfully.

Error

Displays the details of the jobs on which an error occurred during execution.

Suspended/resumed

Displays the details of the jobs whose execution has been temporarily suspended by a suspension condition, or jobs that are resuming execution in response to a resume instruction.

Waiting for installing/collecting

Displays the details of the jobs waiting for remote installation or collection on a relay system, management relay server, or managed computer.

Running/Registering/Standing by/Startup failure

Displays the details of the jobs that are Registering or Standing by, among the running jobs or ID group jobs.

Waiting for execution

Displays the details of the jobs that have not been executed among the scheduled jobs.

Now being deleted

Displays the jobs that are being deleted on a relay system, management relay server, or managed computer.

Execution date/time

You can specify as a condition a date and time at which a job was executed. To do so, select the Execution date/time check box. You can also specify a date/time range. The date/time range can be selected from the following pull-down syntax list:

From/to

The range is set to from the date and time specified in the left-side fields to the date and time specified in the right-side fields.

Before

The range is set to before the date and time specified in the left-side fields.

After

The range is set to after the date and time specified in the left-side fields.

On or before

The range is set to the date and time specified in the left-side fields and before that date and time.

On or after

The range is set to the date and time specified in the left-side fields and after that date and time.

On

Select this option to specify a specific date and time. Specify the date and time in the left-side fields.

Scheduled execution date/time

You can specify a date and time on which a job is scheduled to be executed as a condition. To do so, select the Scheduled Execution date/time check box. You can specify a date/time range in the same manner as Execution date/time.

Execution time limit

You can specify an execution time limit as a condition. To do so, select the Execution time limit check box. You can specify a date/time range in the same manner as Execution date/time.

10.5 Actions after checking the job results

This section describes the possible actions after you checked the job results, including how to delete a job and how to re-execute a job on which an execution error has occurred.

10.5.1 Deleting a job

The following section describes the flow of deleting a job, steps to delete a job, and notes on deleting a job.

(1) Flow of deleting a job

If you delete a job from an upper system, and if the job was already transferred to a lower system, the job downloaded to the lower system will also be deleted. The following figure shows a job deletion flow.

Figure 10‒38: Flow of deleting a job

You delete a job called Job A in the managing server.

If you display Jobs Being Deleted in the Job Status window, Job A, to be deleted, is displayed with (Now being deleted).

Job A, which has been transferred to the relay system or management relay server, is deleted.

Because the Job A has been transferred to a lower system, the Job A with (Now being deleted) remains in the Job Status window.

Job A, which has been transferred to each of the managed computers, is deleted.

After it is reported to the managing server that Job A has been deleted from the entire system, Job A disappears from the Job Status window.

(2) Deleting a job

This section describes how to delete a job in the Job Status window. Once deleted, the job cannot be recovered. If you delete a folder, all jobs and lower-level folders inside the folder will also be deleted.

Bring up the Job Status window, and select a folder or job you want to delete.

The selected folder or job is highlighted.

Select Edit and then Delete.

A deletion confirmation dialog box appears. Clicking the Cancel button closes the dialog box without deleting the selection.

(3) Important notes on deleting a job

Note the following when you delete a job:

A job that has an execution date and time set up on the Schedule page appears both in the Job Definition window and the Job Status window. If you want to delete such a job before the specified date and time, you need to delete it not only from the Job Status window but also from the Job Definition window.

If you perform a deletion operation on a job currently being deleted, the system forcibly deletes the job without waiting until the job is deleted on the relay system, management relay server, or managed computer. Depending on the timing of forced deletion, the job might be forcibly deleted from the managing server before an instruction to delete the job is sent to the relay system, management relay server, or managed computer. In this case, the job that was sent to the relay system, management relay server, or managed computer might be executed without the job being deleted. To check whether an instruction to delete the job has been sent to the relay system, management relay server, or managed computer, you can use the numeric value of the maintenance code displayed in the job details.

If the third and fourth value from the beginning of the maintenance code is 10:

The deletion of the job has been instructed.

If the third and fourth value from the beginning of the maintenance code is 20:

The deletion of the job has not been instructed.

If the Display when a job fails check box is selected in the Display settings for notification dialog boxes section in the User notification settings in the agent configurations, and when you delete a job whose execution status is Waiting for execution or Communication error, an error dialog box may appear on the distribution destination system.

If you delete a Send package, allow client users to choose job from the Job Status window, the package will also be deleted from the package list in the package setup manager job.

10.5.2 Re-executing a job with an error

When you execute a job destined to multiple destinations, the job may complete in one location, but does not complete successfully in other locations and shows an execution error due to waiting for execution or connection error. The job that has not completed successfully needs to be re-executed, but the job does not have to be re-executed to all the destinations. You can re-execute the job that is Waiting for execution or Error.

The following section describes the settings required to re-execute a job, and how to re-execute a job.

(1) Settings required to re-execute a job

To be able to re-execute a job, you must have set up the managing server to record the job execution results.

(a) Executing normal jobs

To re-execute a normal job (a job whose destination is not an ID group), you must set up the managing server to manage the results. In the JP1/IT Desktop Management 2 - Manager setup, select the Record job execution results check box in the Result Recording Options panel of the Setup for Distribution by Using Remote Install Manager window.

(2) Re-executing a job with an error

You can instruct a job re-execution for a destination with Waiting for execution or Error in the Job Status window. You can specify multiple destinations in a single instruction. You cannot re-execute multiple jobs at the same time.

To re-execute a job:

Select the job to be re-executed.

To re-execute an ID group job, select the relay system managing the ID group.

Select Execute, and then Re-execute Job in the Job Status window.

The Job Retry dialog box appears.

Figure 10‒39: Job Retry dialog box

Job

Displays the name of the job to be re-executed. This item is also displayed when you request re-execution by selecting a management relay server, relay system, or managed computer within the job.

Destination

Displays the management relay server, relay system, or managed computer where the job is to be re-executed. Only the first destination is displayed when you have selected two or more destinations in the Job Status window.

All destinations

This item is displayed when you requested re-execution by selecting a job in the Job Status window. All the management relay servers, relay systems, and managed computers within the job are subject to the re-execution of the job.

Specify valid execution status of each client

You can specify the status of the management relay server, relay system, or managed computer where the job is to be re-executed.

Waiting for execution

Re-requests the management relay server, relay system, or managed computer waiting for job execution to receive the selected job.

Temporary error

Re-requests the management relay server, relay system, or managed computer (that generated a communication error or failed to start) to execute the job. For temporary errors that occur under a relay system or management relay server, a re-execution request job is created in the RETRY_RELAY_SYSTEM folder. In a re-execution of a Temporary error job, the status of the job is not be changed by the re-execution, and is changed when the communication error is recovered. Note that needless re-execution request jobs are created if you repeat re-executions.

Error

Extracts only the job request that resulted in an execution error, and re-requests the management relay server, relay system, or managed computer to execute the job.

Click the Execute button.

The job is re-executed with the specified settings.

10.5.3 Executing a job while avoiding a failed relay system

If a problem occurs in a relay system, you can execute a job on a managed computer connected to the relay system via another relay system.

To execute a job and change the path, use the Create Job dialog box to create a job specifying a new route. For details about how to change the route, see 10.2.4 Setting up the Destination page.

10.5.4 Forcibly completing a split distribution job

Forced completion is to suspend a split distribution job, and transfer the remainder of the package in a single transfer. To forcibly complete a split distribution job, select Execute, and then Forcibly Complete Split Distribution in the Job Status window. The forcibly completed job is transferred from a system directly under the system to the distribution destination system, in a single transfer without splitting (normal distribution). Note that forced completion of split distribution applies to only the split distribution jobs on all the systems under a system that executed the forced completion. Note also that a suspended job or resuming job cannot be forcibly completed.

You might want to forcibly complete split distribution only on a relay system or management relay server directly under the system where you executed forced completion. You might also want to execute split distribution to distribution destination systems under the relay system or management relay server. In such a case, distribute the same package by executing a Transfer package to relay computer job. Split distribution to the relay system or management relay server is forcibly completed (then changed to normal distribution), but split distribution is performed on the distribution destination systems under the relay system or management relay server.

10.6 Customizing job creation dialog boxes

The Define New Job dialog box and Create Job dialog box allow you to customize the order of the items and default values.

10.6.1 Customizing the Define New Job dialog box

To customize the order of the job types displayed in the Define New Job dialog box:

Select Edit and then Customize in the Job Definition window.

The Customize Job Definition dialog box appears.

Select Define New Job dialog box.

A dialog box named Customize the Define New Job Dialog Box appears.

Figure 10‒40: Customize the Define New Job Dialog Box dialog box

The right pane shows the job types to be displayed in the Define New Job dialog box. By default, all the job types are displayed. The left pane shows the job types to be hidden in the Define New Job dialog box.

Selecting a job type in the left pane and clicking the > button adds the selected job type. Selecting a job type in the right pane and clicking the < button removes the selected job type and moves them to the Optional job types pane. If you want to remove all the job types from the Current job types pane, click the << button.

Use the up-arrow button to move the Current job types list upward. Use the down-arrow button to move the Current job types list downward.

Specify the order of the job types, and click the OK button.

The settings are saved, and the Customize the Define New Job Dialog Box dialog box closes.

10.6.2 Customizing the Create Job dialog box

The Create Job dialog box allows you to customize the default value of the displayed items to best suit your operation.

(1) Steps

To change the default values of the Create Job dialog box:

Select Edit and then Customize in the Job Definition window.

The Customize Job Definition dialog box appears.

Select Create Job dialog box.

A dialog box named Customize the Create Job Dialog Box appears.

Figure 10‒41: Customize the Create Job Dialog Box dialog box

The page names and item names in the Customize the Create Job Dialog Box dialog box correspond to those in the Create Job dialog box. The values you specify in the Customize the Create Job Dialog Box dialog box will be the default values of the Create Job dialog box.

For items that you can customize the default value, see 10.6.2(2) Customizable items.

Change the default value and click the OK button.

The default value of the Create Job dialog box is changed.

(2) Customizable items

The following tables describe customizable items and the default value for each page in the Customize the Create Job Dialog Box dialog box.

Destination page

Customizable item

Default value

Destination type

Host group

From#

Destination

#: This item is displayed when you click the Add button.

Job Distribution Attributes page

Customizable item

Default value

Distribution to suspended destination

Do not distribute

Distribution methods#1

Unicast distribution

Split distribution settings

Do not split package for distribution

Split size

Deactivated#2

Transfer interval

Deactivated#2

#

These are displayed when the following job types are specified:

- Install package

- Transfer package to relay computer

- Send package, allow client users to choose

#1

This item in the Create Job dialog box is always set to Unicast distribution regardless of the default value setting when the job type is either Transfer package to relay computer or Send package, allow client users to choose.

#2

You can specify a value if Split package and then distribute is selected in the Split distribution settings.

Collect File page

You can specify values for the following items in the Detailed Options For Remote Collection dialog box that appears when you click the Details button.

Customizable item

Default value

Collection timing

While the agent is running

Compress

Compress

Start external programs on the agent

Blank

Acquisition Target - System Information page

This page corresponds to the Acquisition Target page of the Create Job dialog box, which is displayed when the job type is Get system information from computer (UNIX).

Customizable item

Default value

System information

Acquire only items modified after the last time that system information was acquired.

Search Target - Software Information page

This page corresponds to the Acquisition Target page of the Create Job dialog box, which is displayed when the job type is Get software information from computer (UNIX).

Customizable item

Default value

Software to be searched

Software installed by remote install

Search list

Disabled#

File system to be searched

Disabled#

#

You can specify a value if you select All software in the Software to be searched drop-down list.

Schedule page

Customizable item

Default value

Job execution date/time at the server

Server starts the job now

Job execution date/time at the agent

Agent starts the job now

Set the execution interval

Execute every day

Set the execute time

While System Is Running

Client Control page

Customizable item

Default value

Start the target computer if it is not running

Off

Shut down the client after the job execution

Off

11 Outputting Management Information

This chapter explains how to output (to CSV files) information managed by the managing server, and how to print such information.

11.1 Outputting files by using the CSV File Output function

Information managed by the managing server (hereinafter called management information) can be output to CSV files.

This section explains how to use the CSV File Output function to output management information to CSV files.

11.1.1 Items that can be output to CSV files

The CSV File Output function provides templates to output management information. The following table lists the items you can output (to CSV files), according to each template:

Table 11‒1: Items that can be output to CSV files

Template name

Output item

Host attributes

Host name, IP address, Host ID, MAC address, Type, Route, Member of#1, Hold report, Suspend file transfer, Comment, Creation date/time, Update date/time, and Installed package information last update date

Package attributes

Cabinet name, Cabinet ID, Package name, Package ID, Version, Generation, Package size, Transfer package size, Packaging date, Expiration date, Package type, Installation mode, Package compression, Restoration, Restart specification, and Display processing message

Package contents

Cabinet name, Cabinet ID, Package name, Package ID, Version, Generation, File name, Size, and Update date/time

Installed package information

Host name, IP address, Package name, Package ID, Installation, Version, Generation, and Installation or search date/time

Job status#2

Folder name, Job name, Job attribute, Execution date/time at the server, Scheduled execution date/time at the server, Execution time limit at the server, Scheduled registration date/time at the server, Job destination name, Job type, Job execution date/time by destination, Package name, Package ID, Cabinet ID, DM ID code, Version, Generation, Agent-side installation date and time, Result, and Status

#1

This item outputs the name of the affiliated host group or ID group.

#2

The following table lists supplemental information about job status output contents.

Table 11‒2: Supplemental information about job status output contents

Output item

Output contents

Job attribute

This item outputs a folder, host group job, or ID group job.

Execution date/time at the server

This item outputs the date and time when a job was executed on the managing server.

Scheduled execution date/time at the server

This item outputs the date and time that was specified in Execution date/time on the Schedule page when a job was executed.

Execution time limit at the server

This item outputs the date and time that was specified in Execution time limit on the Schedule page when a job was executed.

Scheduled registration date/time at the server

This item outputs the date and time that was specified in Registration date/time on the Schedule page when a job was executed.

Job execution date/time by destination

This item outputs the date and time when a job was executed on the managing server.

DM ID code

This item outputs information on whether the distributed package was created in Windows or UNIX.

Agent-side installation date and time

For remote installation jobs, this item outputs the installation date and time that was specified on the Schedule page during packaging, or on the Package page during job execution.

Result

This item outputs job status. However, while a job is being deleted, the job status is not output.

Status

This item outputs a maintenance code in the Detailed Information dialog box, which is displayed by using the Display Job Detailed Information menu in the Job Status window.

11.1.2 Outputting to CSV files

This section explains how to output management information to CSV files.

Start the CSV File Output function.

To start the CSV File Output function, from the File menu of the Remote Install Manager, select Output to CSV File. The CSV File Output dialog box appears.

In the CSV File Output dialog box, specify the output items and output destination file name.

For details about how to specify the settings, see 11.1.3 Specifying the output range for CSV files.

11.1.3 Specifying the output range for CSV files

The output range for CSV files can be specified using the CSV File Output dialog box. This section explains how to specify the output range using the CSV File Output dialog box.

(1) Select the template

In this dialog box, select a template to be output (CSV format).

(2) Select the data

In this dialog box, specify the items to be output to the columns of the CSV file. This dialog box appears when the Host attributes, Installed package information, or Job status template is selected.

(3) Specify output constraints

In this dialog box, specify the output conditions for information to be output to the rows of the CSV file. This dialog box appears when the Installed package information or Job status template is selected.

Figure 11‒1: CSV File Output - Specify output constraints dialog box

Before setting values for an item, select the check box to the left of the item. Based on the specified conditions, information about each package is individually output to the Installed package information template, and information about each job is individually output to the Job status template.

Data item

You can specify a maximum of three items to be compared.

Comparison

Select the comparison condition.

Value

Specify the value to be used for the comparison condition. Note the following rules when entering a value:

When specifying multiple values, separate each value by using a comma (,). (Example: value 1, value 2, value 3, value 4)

When specifying a value range, separate the values by using a greater-than symbol (>). (Example: value 1 > value 2)

You can use the * and ? symbols as wildcards. * indicates multiple characters, and ? indicates a single character.

Enter a value (in the date format) in the Value column for the following items:

Installed package information template

Installation date/time

Job status template

Execution date/time at the server

Scheduled execution date/time at the server

Execution time limit at the server

Scheduled registration date/time at the server

Job execution date/time by destination

The date format is YYYYMMDDhhmm (numerical). You must at least specify YYYY. The minimum (default) values for MMDDhhmm are set, if they are not manually set. Enter 0 in front of any single-digit value. (An error will result if only a single-digit value is entered.)

Examples of specifying date and time are as follows:

200

An error occurs.

2014

January 1, 2014 at 00:00

2014101

An error occurs.

20141010

October 10, 2014 at 00:00

201401010101

January 1, 2014 at 01:01

201412312359

December 31, 2014 at 23:59

For the date/time specifications, you cannot specify the following comparison conditions: equals, not, is included in, using wild cards, is not among, and without wild cards

AND/OR

When specifying multiple conditions, select either AND or OR. The meaning of each value is as follows:

AND

Outputs information when both (or all) of the specified conditions are met.

OR

Outputs information when either (or one) of the specified conditions is met.

If you specify multiple conditions, select the check box on the second row (or the check boxes on the second and third rows).

Comment

If you change a value in the Date item or Comparison column, this box displays information pertaining to the change.

(4) Set the range of hosts to be output

If you want to output CSV files to only the hosts that belong to a particular host group, ID, or system configuration, specify settings in this dialog box. To output CSV files to all hosts, do not specify settings in this dialog box. This dialog box appears only when the Host attributes or Installed package information template is selected.

Figure 11‒2: CSV File Output - Set output range of the host dialog box

Select the range by

For the output target, select Host group, ID, or System configuration. The default is Host group.

Directly Specify

Clicking this button displays the Type Output Host Range dialog box.

Figure 11‒3: Type Output Host Range dialog box

You can specify the hosts to which to output a CSV file by using a path where each level under the root is delimited by \. Specify the path by using the names displayed by the Remote Install Manager.

Note that restrictions on path specification vary according to the output target, as follows:

When Host group is selected as the output target

You cannot use the following single-byte symbols:

/ * " ' : ! | . < > ? @ %

Use the \ symbol only to separate each path component.

Specify no more than six levels.

You cannot begin a path with a comma (,).

When ID is selected as the output target

You cannot use the following single-byte symbols:

/ * " ' : ! | . < > ? @ %

Use the \ symbol only to separate each path component.

You cannot begin a path with a comma (,).

When System configuration is selected as the output target

You cannot use the following single-byte symbols and space characters:

! " $ % & ' ( ) = ~ | ^ [ ] { } : ; + * _ / ? > < , @ ` "

Use the \ symbol only to separate each path component.

Specify no more than six levels.

Do not begin a path with a comma (,).

Browse

Clicking this button displays the Select Output Host Range dialog box.

Figure 11‒4: Select Output Host Range dialog box

Select the desired host, and then click the Add button.

Delete

Clicking this button deletes the selected path.

(5) Specify the output file

In this dialog box, specify the file name for the output destination.

11.1.4 Notes on outputting to CSV files

When outputting data to CSV files, observe the following:

Do not use the Package window to display the contents of a package that is being output to a CSV file, as doing so might cause processing to fail.

At least one data item must be registered before you can use CSV File Output function to output CSV files. If data is not registered, you can not output CSV files. Make sure that data items are registered before you use this function.

11.2 Printing management information

This section explains how to print information managed by the managing server. Use the Print Setup dialog box to select items to be printed and to specify the necessary information.

11.2.1 Printable items

Printable information differs for each window. This section explains what information can be printed according to the window.

The following table shows the information that can be printed in the System Configuration window.

Table 11‒3: Information that can be printed in the System Configuration window

Print item

Print information

Lower Hosts

Key, Host name, IP address, Host ID, Type, and Lower host name

Attributes

Key, Host name, IP address, Host ID, MAC address, Type, Route, Holding report, Suspend file transfer, Comment, Creation date/time, and Update date/time

Installed Package Information

Key, Host name, IP address, Host ID, Package name, Package ID, Installation, New version, New generation, Previous version, Previous generation, and Installation or search date/time#

#

For software distributed by JP1/IT Desktop Manager 2, this item outputs the date and time of installation completion. For software detected on agents for UNIX or agents for Mac, this item outputs the date and time when information was collected by a Get software information from computer (UNIX) job.

The following table shows the information that can be printed in the Destination window.

Table 11‒4: Information that can be printed in the Destination window

Print item

Print information

Lower Hosts

Host group/ID group/key, Host name, IP address, Host ID, Type, and Lower host group/host name

Attributes

Host group/ID group/key, Host name, IP address, Host ID, MAC address, Type, Route, Member of, Comment, Holding report, Suspend file transfer, Creation date/time, and Update date/time

Installed Package Information

Host group/ID group/key, Host name, IP address, Host ID, Package name, Package ID, Installation, New version, New generation, Previous version, Previous generation, and Installation or search date/time#

ID-management Relay Computer

ID group name and ID-management relay computer name

#

For software distributed by JP1/IT Desktop Manager 2, this item outputs the date and time of installation completion. For software detected on agents for UNIX or agents for Mac, this item outputs the date and time when information was collected by a Get software information from computer (UNIX) job.

The following table shows the information that can be printed in the Package window.

Table 11‒5: Information that can be printed in the Package window

Print item

Print information

Package List

Cabinet name, Cabinet ID, Package name, Package ID, Version, and Generation

Attributes (cabinet name)

Cabinet name/package name, Cabinet ID, and Number of packages in cabinet

Attributes (package name)

Package ID, Cabinet name, Version, Generation, Package size, Transfer package size, Packaging date, Expiration date, Package type, Installation mode, Package compression, Backup/restore, Restart specification, Display processing message, and AIT file

The following table shows the information that can be printed in the Job Status window.

Table 11‒6: Information that can be printed in the Job Status window

Print item

Print information

Attributes

Folder/job/host name

Attributes (folder name)

Lower folder/job name

Attributes (job/ID group name)

Job type, Finished/Errors/Total, Status, Execution date/time, Scheduled date/time, and Execution time limit

Attributes (host name)

Finished/Errors/Total and Status

Attributes (package name)

Status, Result, Selected destination, Scheduled date/time, Execution time limit, Execution date/time, and Scheduled installation date/time

Details

Job name, Destination name, Details#, and Value

#

Print contents differ according to each job type. The following table shows the contents of the Details item according to the job type.

Table 11‒7: Contents of the Details item for each job type

Job type

Contents of the Details item

Install package

Transfer package to relay computer

Send package, allow client users to choose

Job type, Package name, Package ID, Package version / revision, Generation, Execution date/time, Result, and Status

Batch delete packages on relay computer

Acquire collected files from relay computer

Delete collected files from relay computer

Get system configuration information

Get system information from computer (UNIX)

Get software information from computer (UNIX)

Hold report

Cancel holding of report

Suspend file transfer

Resume file transfer

Job type, Execution date/time, Result, and Status

Collect files from agent

Job type, Collection target directory, Collection target file name, Execution date/time, Result, and Status

Remote-collect files from agent to relay computer

Job type, Collection target file name, Execution date/time, Result, and Status

11.2.2 Printing method

This section explains how specify and print information.

Open the window where you want to print information, select File, then Print.

The Print Setup dialog box appears.

Figure 11‒5: Print Setup dialog box

Print item

Select the desired print item from the drop-down list. Selectable print items differ according to the window type.

Print information

In this section, select the check boxes to the left of the desired print information. The check boxes of information that is always printed according to the specified print item are automatically selected. The text to the right of these check boxes is gray.

Select print range

In this section, select the desired print range from the following two options:

All

This option displays a printed image of all information in the window.

Selection

This option displays a printed image of a preselected range of information in the window. This option becomes available after you have preselected a range of information in the window.

Printer button

Clicking this button displays the Printer Setup dialog box, where you can specify the printer, paper size and other items.

Depending on the printer you use, specifying a print magnification rate might not enlarge or reduce the image. In such a case, change the font size accordingly before printing.

Font button

Clicking this button displays the Font dialog box where you can specify the font to be used for printing. The following font type and size are recommended:

- Font type: MS Gothic

- Font size: 8 point

Set all items, and then click the OK button.

The Windows Print dialog box appears.

Click the OK button in the Windows Print dialog box.

Printing starts.

Note that, if you select Print Setup or Print Preview from the File menu, the Print Setup dialog box also appears.

Note:

When printing by specifying a page range from the remote install manager, if the specified page is outside the actual page range, only the title is printed. Select All or enter the correct page range to print.

12 Performing Operations on the Agent

All management relay servers with JP1/IT Desktop Management 2 - Manager installed, and relay systems and managed computers with JP1/IT Desktop Management 2 - Agent installed have agent functionality. Agent functionality includes receiving jobs from the managing server and managing a local personal computer system.

This chapter describes how to use the functions of the agent.

12.1 Before using the agent

This section describes the prerequisite knowledge (for example, settings necessary for agent functionality and types of icons displayed by the agent) to operate the agent for distribution by using Remote Install Manager.

12.1.1 Agent's menu items for the distribution by using Remote Install Manager

The system with JP1/IT Desktop Management 2 - Agent installed generates the following program folders in the Start menu:

JP1_IT Desktop Management 2 - Agent folder

ITDM2_Startup folder

The system generates the ITDM2_Startup folder when you perform the following operation in the Settings module of the Window Operations window of JP1/IT Desktop Management 2:

Choosing Agent, Windows Agent Configurations and Create Agent Installers, Add/Edit Agent Configuration, Startup settings, and then Create the startup folder (ITDM2_Startup) for only IT Desktop Management 2.

The following describes the roles of individual program folders and menu items:

(1) JP1_IT Desktop Management 2 - Agent folder

The following describes the items (stored in the JP1_IT Desktop Management 2 - Agent folder) that users use to run JP1/IT Desktop Management 2 functions:

Package Setup Manager

This menu item starts Package Setup Manager, which is used to remotely install software (distributed from the managing server) on a managed computer, as instructed on the managed computer. Package Setup Manager enables you to perform the following operations:

Selecting and installing software on a managed computer

Checking the software packages installed on a managed computer

For details about how to install software by using Package Setup Manager, see 12.4 Operating Package Setup Manager.

Register in ID Group

This menu item is used to register a managed computer in an ID group. For details about how to register a managed computer in an ID group, see 12.2.1 Registering a managed computer in an ID group.

(2) ITDM2_Startup folder

The ITDM2_Startup folder delays the starting of specific startup programs, in order to prevent them from starting at the same time as when remote installation is performed using JP1/IT Desktop Management 2.

Programs registered in the Windows Startup group start at the same time as Windows startup. Therefore, those programs cannot be upgraded by using the Install when the system starts option. Move startup programs that might be upgraded by remote installation to the ITDM2_Startup folder.

Note, however, that some application programs might fail to be uninstalled if their shortcuts are placed in the ITDM2_Startup folder (for example, as in the case of Microsoft Office Shortcut Bar). To avoid this problem, do not move shortcuts for such application programs to the ITDM2_Startup folder.

For details about moving startup programs, see the description of agent configurations in the JP1/IT Desktop Management 2 Configuration Guide.

12.2 Setting the operating environment for the agent

This section describes how to set the operating environment needed to use the agent.

12.2.1 Registering a managed computer in an ID group

For a managed computer, you must register its local system in an appropriate group (called an ID group) so that the managed computer can receive jobs from the managing system. To register the managed computer in an ID group, use the Register in ID Group dialog box, which appears when you open the Windows Start menu, and then choose the Register in ID Group.

Figure 12‒1: Register in ID Group dialog box

Register a managed computer in an ID group while the managed computer is connected to the ID-management relay computer. The ID-management relay computer is a higher system that manages ID groups, which is a higher server specified in agent configurations. The Register in ID Group dialog box displays the name of the higher server. When connecting via Internet Gateway, "Internet Gateway" is displayed.

Even while a managed computer is not connected to the ID-management relay computer, registration of the managed computer in an ID group or unregistration of it from the ID group can be put on hold. In such a case, the ID-management relay computer will be notified of actual registration or unregistration when you log on to the relay or select the Register in ID Group after connection to the relay is enabled. Therefore, you can register a managed computer in an ID group even during pre-installation or system configuration. While a managed computer is in the process of remote installation or another operation, it is connected by using a different function from an ID-management relay computer. In such cases, registering in and unregistering from an ID group are both handled in the same way as when the managed computer is not connected to the relay.

The following subsections describe how to use the Register in ID Group dialog box, according to the status of the connection between a managed computer and an ID-management relay computer.

(1) Registering a managed computer in an ID group when the managed computer is connected to the ID-management relay computer

You can perform the following operations when a managed computer is connected to the ID-management relay computer (when, in the Register in ID Group dialog box, Server connection is set to Connected):

Registering the managed computer in an ID group

Unregistering the managed computer from an ID group

(a) Registering a managed computer in an ID group

The following describes how to register a managed computer in an ID group:

In List of available ID groups, select an ID group.

The selected ID group is highlighted. You can select only one ID group.

Click the > button.

If the selected ID group does not require a password, the selected ID group moves to List of selected ID groups, and registration of the managed computer in the ID group ends.

If the selected ID group requires a password, the Confirm Registration dialog box appears.

Enter a password, and then click the OK button.

Enter the password (a maximum of 14 single-byte alphanumeric characters) informed to you by the system administrator. If the entered password is valid, the selected ID group moves to List of selected ID groups, and registration of the managed computer in the ID group ends.

(b) Unregistering a managed computer from an ID group

The following describes how to unregister a managed computer from an ID group.

In List of selected ID groups, select the relevant ID group.

The selected ID group is highlighted. You can select multiple ID groups.

Click the < button.

A confirmation dialog box appears to ask you whether you are sure you want to unregister the managed computer from the ID group.

Click the OK button. The selected ID group moves to List of available ID groups, and unregistration of the managed computer from the ID group ends.

(2) Registering a managed computer in an ID group when the managed computer is not connected to the ID-management relay computer

You can perform the following operations when a managed computer is not connected to the ID-management relay computer (when, in the Register in ID Group dialog box, Server connection is set to Disconnected):

Setting the status of waiting for registration in an ID group

Setting the status of waiting for unregistration from an ID group

Canceling the status of waiting for registration in an ID group

Canceling the status of waiting for unregistration from an ID group

Revising ID group information

(a) Setting the status of waiting for registration in an ID group

The following describes how to enable a managed computer to be registered in an ID group managed by a relay (server) managing the ID group when the managed computer connects to the relay:

In the Enter an ID group field, enter the ID group in which to register the managed computer.

The ID group name to be entered must not exceed 32 single-byte characters (or 16 double-byte characters). You cannot use the following symbols or space characters:

\ / * : " ' | ! . < > ? %

Note also that an ID group name beginning with a network ID cannot be used.

Click the > button.

The Confirm Registration dialog box appears to prompt you to enter a password. If the entered ID group does not require a password for registration in the ID group, enter nothing in the Password field, and then click the OK button. Preparation for registering in the ID group ends.

Enter a password.

If the entered ID group requires a password for registration, enter the password informed to you by the system administrator, and then click the OK button. Preparation for registering in the ID group ends. The ID group with which preparation for registering has ended is displayed in List of selected ID groups with the comment Now registering in ID groups attached against a yellow background.

Registration in an ID group that is put on hold is reported to the ID-management relay computer later. Specifically, this notification occurs when you log on to the ID-management relay computer or select the Register in ID Group for the first time after communication with the ID-management relay computer is enabled.

If an error is returned when registration in an ID group in the waiting status is reported, you can revise the ID group information, and then retry registering the managed computer in the ID group.

(b) Setting the status of waiting for unregistration from an ID group

The following describes how to enable a managed computer to be unregistered from an ID group managed by the relay (server) managing the ID group when the managed computer connects to the relay:

In List of selected ID groups, select the relevant ID group.

The selected ID group is highlighted. You can select multiple ID groups.

Click the < button.

A confirmation dialog box appears asking whether you are sure you want to unregister the managed computer from the ID group.

Click the OK button.

The selected ID group moves to List of available ID groups, and preparation for unregistering the managed computer from the ID group ends.

The ID group with which preparation for unregistering has ended is displayed in List of available ID groups with the comment Canceling attached against a yellow background.

(c) Canceling the status of waiting for registration in an ID group

The following describes how to cancel the status of waiting for registration in an ID group:

In List of selected ID groups, select the relevant ID group.

The selected ID group is highlighted. You can select multiple ID groups.

Click the < button.

A confirmation dialog box appears asking whether you are sure you want to cancel the status of waiting for registration in the selected ID group.

Click the OK button.

The selected ID group is deleted from List of selected ID groups, and canceling the status of waiting for registration from the ID group ends.

(d) Canceling the status of waiting for unregistering from an ID group

The following describes how to cancel the status of waiting for unregistration from an ID group:

In List of available ID groups, select the relevant ID group.

The selected ID group is highlighted. You can select multiple ID groups.

Click the > button.

The selected ID group is deleted from List of available ID groups, and canceling the status of waiting for unregistration from the ID group ends.

(e) Revising ID group information

The following describes how to revise the ID group information specified for setting the status of waiting for registration of a managed computer:

Note that the Register in ID Group dialog box reporting an error might appear during registration processing. If this dialog box appears, click the Retry button to revise the ID group information (as described below), or click the OK button to cancel registration in the ID group that resulted in the error, and end processing.

In List of selected ID groups, select the relevant ID group.

Select the ID group of which to revise information from List of selected ID groups. You can revise the information of only an ID group that is in the status of waiting for registration (displayed against a yellow background), or an ID group that has caused a registration error (displayed against a red background).

Click the Revise button.

The Revise ID Group dialog box appears.

Revise the ID group name and/or password, and then click the OK button.

The ID group information is revised, and is displayed with the comment Now registering in ID groups attached (displayed against a yellow background).

(3) Notes on registering a managed computer in an ID group

Agent functions cannot be used while the Register in ID Group dialog box is active. When you finish the registering the managed computer in an ID group, close the Register in ID Group dialog box.

If you have changed the connection-destination server through agent configurations on a managed computer, re-register the managed computer in ID groups.

12.2.2 Notes on using the agent functions for the distribution by using Remote Install Manager

This subsection describes the notes on operating the agent for the distribution by using Remote Install Manager.

(1) Installation modes and user permissions

There are two modes for remote installation: background installation mode (install by simply copying files), and GUI installation mode (operate by windows and dialog boxes). Most distributed software products, such as Hitachi program products and other companies' software, use the GUI installation mode.

Do not enable non-Administrator users to change their access permissions for the registry below. If non-Administrator users are enabled to change their access permissions for the registries, remote installation might be disabled.

In a 32-bit OS:

HKEY_LOCAL_MACHINE\SOFTWARE\HITACHI\JP1/IT Desktop Management - Agent\DMP

In a 64-bit OS:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Hitachi\JP1/IT Desktop Management - Agent\DMP

Note, however, that, in background installation mode, packages are installed in a computer, regardless of the permissions given to the user logged on to the computer.

In addition, when you perform installation with GUI installation mode to the Citrix XenApp and Microsoft RDS server, any user must log on to the Citrix XenApp and Microsoft RDS server.

(2) Restrictions on installation with non-Administrator user permissions

The following describes the installation restrictions on the agent:

(a) Moving of startup programs

Moving of startup programs is subject to the following restrictions:

Changes of the ITDM2_Startup folder

If you select (in agent configuration dialog box) Create the startup folder (ITDM2_Startup) for only IT Desktop Management 2. for Startup settings, where the ITDM2_Startup folder is created varies depending on whether installation is performed with non-Administrator permissions.

When installation is performed with non-Administrator permissions, the ITDM2_Startup folder is created in a shared program folder.

If Move startup programs into the ITDM2_Startup folder. is selected and shortcuts are registered for the startup programs in both shared and personal program folders, the ITDM2_Startup folder is created in both shared and personal program folders.

If non-Administrator and Administrator users are to share the ITDM2_Startup folder, a shortcut for the ITDM2_Startup folder must be created so that the folder can be accessed with either non-Administrator or Administrator permissions.

Applicable scope of the setting to automatically move startup programs

If you select (in the agent configuration dialog box) Move startup programs into the ITDM2_Startup folder. for Startup settings, automatic moving applies to all users' startup programs.

Applicable scope of uninstallation when startup programs are automatically moved

If you select (in the agent configuration dialog box) Move startup programs into the ITDM2_Startup folder. for Startup settings, the following operations are performed automatically only for logged-on users:

Moving startup programs into a startup group

Deleting the ITDM2_Startup folder

Users who are not logged on must perform the above operations manually.

12.3 Holding job execution

The Job Suspended function is available as a means to prevent one-sided execution of jobs by a higher system (managing server) and execute jobs at the convenience of users.

To enable the job hold facility, in the agent configuration dialog box, choose Job settings, and then select the Permit users to hold job check box under Settings to permit job holds.

12.3.1 How to hold a job

When the job hold facility is enabled, the JP1/IT Desktop Management 2 Job Hold dialog box appears in the following timings:

When a job execution request is received from a higher server

When Package Setup Manager is started or information is updated in the Package window

The JP1/IT Desktop Management 2 Job Hold dialog box lists downloaded jobs.

Figure 12‒2: JP1/IT Desktop Management 2 Job Suspended dialog box

Package name

This column shows the name of the package.

Operation

This column shows the operation (that is, execution or holding) to be done for the job.

Timing

This column shows the execution timing specified for the package.

Size

This column shows the size of the package.

Date

This column shows the date at which the job arrived at the managed computer.

OK button

This button executes the operation selected by the Execute or Hold button, and then closes this dialog box.

Execute button

This button immediately executes the selected (highlighted) job.

Hold button

This button temporarily holds the selected (highlighted) job.

Confirm when the job operation is changed.

Select this check box if you want to open a confirmation dialog box each time job operation is changed by the Execute or Hold button, or the OK button is clicked.

n seconds until operation

"n" indicates the remaining number of seconds of dialog box display time specified in the agent configurations.

The following describes how to hold a job by using the JP1/IT Desktop Management 2 Job Hold dialog box.

Select a job, and then specify the method of job operation in the Operation column.

Click the Execute or Hold button to change the job operation, and then click the OK button. If you want to open a confirmation dialog box each time one of these buttons is clicked, select the Confirm when the job operation is changed. check box.

Click the OK button.

The specified operation is performed for the selected job.

In the JP1/IT Desktop Management 2 Job Hold dialog box, n in n seconds until operation indicates the remaining number of seconds of the dialog box display time specified in the agent configurations. This indication disappears when you perform an operation (such as clicking) in this dialog box. If the specified display time passes without any operation in this dialog box, and the remaining number of seconds reaches 0, the operation shown in the Operation column is performed, and then this dialog box closes.

12.3.2 How to execute a held job

To execute a held job, choose the Package Setup Manager icon to start Package Setup Manager.

12.3.3 Notes on holding a job

The JP1/IT Desktop Management 2 Job Hold dialog box opens only after you log on to Windows. Therefore, if a given time passes without logging on to Windows after you have started the personal computer, jobs might be executed.

The operation of an installation job for a package with the Run at next startup option specified differs between the case in which the OK button is clicked, and the case in which the dialog box display time elapses. The difference is as follows:

When the OK button is clicked:

Downloading and installation of the package are executed as one operation.

When the dialog box display time elapses:

Only downloading of the package is executed. Its installation will be executed at the next system startup.

While the file transfer from the connection destination is suspended, no jobs can be executed. Job execution is enabled when the file transfer is resumed.

The JP1/IT Desktop Management 2 Job Hold dialog box displays all jobs, including those originating from the server with which communication has been lost.

If, when the installation operation is executed for the held job, communication has already been lost with the server from which the job originated, the job will be deleted from the dialog box but the package will not be downloaded. The package is downloaded and installed only after the communication is resumed with the server from which the job originated and another job for which the job hold facility is enabled is executed.

When the JP1/IT Desktop Management 2 Job Hold dialog box is being displayed, the higher system for distribution using Remote Install Manager cannot be changed.

12.4 Operating Package Setup Manager

Usually, a managed computer only receives, from a managing server, the packages to be installed remotely by the managing server. However, a package distributed as a "Send package, allow client users to choose" job from the managing server only gives the managed computer permission to install. You can select necessary software programs from such a package, and then install them by using Package Setup Manager on the managed computer.

To start Package Setup Manager, open the Start menu, and then choose the Package Setup Manager icon.

12.4.1 Configuration of the Package Setup Manager window

Starting Package Setup Manager opens the Package Setup Manager window. The Package Setup Manager window has the following two windows, which can be switched between one or the other:

Package window

Package Setup Manager - Installed Package

(1) Package window

The Package window lists the software packages of which installation is permitted. Listed software packages vary depending on the higher system to which the managed computer is connected. You can select only necessary software products from this list, and then install them.

Figure 12‒3: Package window

After you have performed installation of packages (by using Package Setup Manager), results of installation are reported to the higher system. A blue circle is displayed on the icon of each package that was installed successfully. A red cross is displayed on the icon of each package that failed to be installed. The same marking also applies to the package icons also when packages have been installed without using Package Setup Manager (a blue circle is displayed on the icon of each installed package). The marking applies, for example, when a package has been automatically installed by a normal remote installation job, or when a package has been locally installed by a user.

For details about the operations of the Package window, see 12.4.2 Package installation using Package Setup Manager.

(2) Installed Packages window

The Installed Packages window lists the packages that have been installed by Remote Install Manager.

Figure 12‒4: Installed Packages window

For the display contents of the Installed Packages window, see 12.4.3 Checking software installation status.

(3) Linkage between windows

The two windows in the Package Setup Manager window are linked to each other. Assume that a package is installed by using Package Setup Manager. In this case, in addition to a blue circle displayed on the icon of the package in the Package window, software information corresponding to the package is also added in the Installed Packages window.

Also, assume that a package displayed in the Package window is locally installed. In this case, in addition to the information about the package being displayed in the Installed packages window, a blue circle is also displayed on the icon of the package in the Package window.

(4) Notes

If you have installed a package while specifying the installation-destination drive with a numerical value, the numerical value is displayed as the drive name also in the Installed Packages window. The numerical value is not converted to the corresponding drive name.

When a managed computer is registered in multiple ID groups, multiple identical packages might be displayed in the Package window.

While the file transfer from the connection destination is suspended, package installation is disabled. A red cross mark is displayed on the icon of packages that could not be installed. When, however, the file transfer is resumed, package installation is enabled.

If an attempt to install a package by overwrite installation has resulted in an error, the package is displayed as an installed package, even after occurrence of the error.

12.4.2 Package installation using Package Setup Manager

You can perform the following operations using the Package Setup Manager window:

Installing packages (automatically and manually)

Displaying detailed package information

(1) Installing packages (by automatic installation)

You can install packages automatically. When installing packages automatically, you can change the setting of the installation-target directory beforehand for individual packages. You can change the installation-target directory also when installation is executed.

The following describes how to change the installation-target directory, and how to perform automatic installation:

(a) Changing the installation-target directory

Select the package for which to change the installation-target directory, and then, from the Edit menu, choose Change Installation Path.

The Change Installation Path dialog box appears.

Figure 12‒5: Change Installation Path dialog box

Change the installation-target directory, and then click the OK button.

The installation-target directory is changed.

(b) Automatically installing a package

Select the package to be installed (multiple packages can be selected), and then, from the Execute menu, choose Install.

The Specify Installation Method dialog box appears, displaying the selected package.

Figure 12‒6: Specify Installation Method dialog box

Change Installation Path button

This button displays a directory-browsing dialog box to change the installation-target directory for the selected package.

Package Details button

This button enables you to display and browse the description files appended to the package.

Command Option button

This button enables you to specify options for the executable file of the installer.

Installation method

This item enables you to select between automatically installing the package and manually installing it.

Execute button

This button starts installation of the displayed package.

Select Automatic under Installation method.

If you want to change the installation-target directory, click the Change Installation Path button to open the Change Installation Path dialog box, and then specify a new installation-target directory in the dialog box.

You can browse description files appended to the package. To browse them, click the Package Details button.

Click the Execute button.

Remote installation of the selected package starts.

(2) Installing a package (by manual installation)

You can manually install a package whose package type is Hitachi program product or another company's software while manually responding to the installer of the package on the GUI. If custom installation is required, manually install a package, and then adjust it to the user's environment. Note, however, that some Hitachi program products cannot be installed manually. To install a package manually, do the following:

Select the package to be installed, and then, from the Execute menu, choose Install.

The Specify Installation Method dialog box appears, displaying the selected package. Note that you can select only one package for manual installation.

Select Manual under Installation method.

The Change Installation Path button is deactivated. The installation-target directory, however, can be changed in a subsequent step of manual installation.

When description files are appended to the package, you can browse them. To browse them, click the Package Details button.

When the package to be installed is another company's software, click the Command Option button to open the Setup Command Option dialog box. In the dialog box, specify the name of the installer (for example, setup.exe) and, if necessary, a command option (1,024 or fewer bytes).

Figure 12‒7: Setup Command Option dialog box

Click the Execute button.

The installer starts.

Perform installation as instructed by the installer for the selected package.

Some packages require you to replace the CD-R during installation processing, and then enter the path name of the CD-R to be read next. If the entry of the path name is requested, change the last numerical value of the path name displayed in the dialog box to the numeric value assigned to the CD-R to be read next.

When processing by the installer ends, the Send Result of Manual Installation dialog box appears.

Figure 12‒8: Send Result of Manual Installation dialog box

Notify the status of installation execution (result of execution) to JP1/IT Desktop Management 2 - Agent (relay system or agent).

If the user remotely installed a package by manually responding to the installer, Package Setup Manager cannot recognize the execution result of installation. Therefore, specify the execution result in the Send Result of Manual Installation dialog box. In the dialog box, select Installation completed or Installation failed, and then click the OK button.

The Send Result of Manual Installation dialog box appears when the setup command ends. Therefore, the dialog box might appear before installation is complete. In such a case, if you click the OK button in the dialog box before installation is complete, the installation is terminated forcibly. Before clicking the OK button, make sure that the installation is complete.

(3) Displaying detailed package information

You can display information about packages that permit remote installation. For packages that failed to be installed, you can display the cause of failure. Reference the information as needed.

Select the package about which information is to be displayed, and then, from the View menu, select Details.

The Package Details dialog box appears, displaying the information about the package.

Figure 12‒9: Package Details dialog box

12.4.3 Checking software installation status

In the Installed Packages window, you can check packages that have already been installed on a managed computer.

Figure 12‒10: Installed Packages window

The icon displayed to the left of each software name indicates the type of software.

: Hitachi program product

: Another company's software

: User program or data

The Installed Packages window lists the packages that have been installed by Remote Install Manager.

The information in the Installed Packages window is updated in the following timings:

When Package Setup Manager starts

When installation using Package Setup Manager succeeds

When, in the View menu, the Refresh menu command is executed

The information displayed in the Package window is linked to the information displayed in the Package window of Package Setup Manager. When a package displayed in the Package window is installed locally, a circle indicating installation completed is displayed on the icon of the corresponding package displayed in the Installed Packages window.

12.5 Managing backup files

If remote installation using the backup/restore function fails, restoration (file recovery) using backup files is usually executed automatically. In some cases, however, restoration might fail, or not be executed.

For packages created by the UNIX-version Packager, managed computers store the backup files that failed to be restored, according to the backup storage period specified during packaging.

You can handle stored backup files with commands. Check the backup files, and then delete files (or retry restoration) as needed.

The following table lists the commands that are used to manage stored backup files:

Table 12‒1: Commands to manage backup files

Command name

Function

dmpbklst

Outputs a list of backup files.

dmpbkdel

Deletes backup files.

dmprcvry

Retries restoration using stored backup files.

12.5.1 Outputting a backup status list (dmpbklst command)

Function

This command outputs a list of stored backup files to a backup status list file (file name: DMPBKLST). The backup status list file contains text-format data that indicates the package IDs (package IDs in the UNIX version of JP1/IT Desktop Management 2 - Agent) of stored backup files and the total number of backup files.

Format

dmpbklst /directory to output backup status list file

Argument

/directory to output backup status list

Specifies the path to the directory to which to output the backup status list file (file name: DMPBKLST).

Output format

NUMBER_OF_ENTRY  =  3         (1)
RESOURCE_NAME  =  UAP1        (2)
RESOURCE_NAME  =  UAP2
RESOURCE_NAME  =  USERDATA
END_OF_FILE                   (3)

(1) NUMBER_OF_ENTRY = number of backup files

Indicates the total number of stored backup files (1 to 127)

(2) RESOURCE_NAME = package ID

Indicates the package ID (package ID in the UNIX version of JP1/IT Desktop Management 2 - Agent) of the package for which a backup has been stored. A package ID must not exceed 44 characters. If the package ID is less than 44 characters, spaces are added up to the 44th character.

(3) END_OF_FILE

Indicates the end of the backup status list file.

Return codes

0

The command ended normally.

1

No backup file was found.

Example

The following example shows use of this command to output the backup status list file to the directory C:\Program Files\Hitachi\JP1ITDMA. The name of the output file is fixed to DMPBKLST.

dmpbklst.exe /"C:\Program Files\Hitachi\JP1ITDMA"

12.5.2 Deleting backup files (dmpbkdel command)

Function

This command deletes the backup files that have a specified package ID (package ID in the UNIX version of JP1/IT Desktop Management 2 - Agent).

Format

dmpbkdel /package ID

Argument

/package ID

Specifies the package ID of the backup files to be deleted.

Return codes

0

The command ended normally.

1

The specified package ID does not correspond to any backup files.

2

A system error occurred at deletion of backup files.

Example

The following example shows use of this command to delete backup files that have the package ID TEST.

dmpbkdel.exe /TEST

12.5.3 Retrying restoration (dmprcvry command)

Function

This command retries restoration by using backup files that have a specified package ID (package ID in the UNIX version of JP1/IT Desktop Management 2 - Agent).

Format

dmprcvry /package ID

Argument

/package ID

Specifies the package ID of the package of which restoration is to be retried.

Return codes

0

The command ended normally.

1

The specified package ID does not correspond to any backup files.

2

A system error occurred at restoration.

3

An error occurred during processing after restoration.

Example

The following example shows use of this command to retry restoration using the backup files that have the package ID TEST.

dmprcvry.exe /TEST

12.6 Notes on job execution after the managed computer awakes from sleep mode

The following describes job execution on a managed computer that has just awoken from the sleep mode. (A managed computer that has not been operated for a given time enters the sleep mode to save power.)

Polling and package installation scheduled since system startup cannot be executed. To execute these jobs, restart the managed computer after it awakes.

The programs in the ITDM2_Startup group are not started. To start them, log back on from the agent to the managing server.

The polling and package installation scheduled with date and time specified are executed if the managed computer awoke after a specified date and time.

If package downloading was started before the managed computer entered the sleep mode, the job cannot be executed after the managed computer has awoken. The job is resumed after it is retried, or when polling is executed.

If package installation was started before the managed computer entered the sleep mode, the job is resumed after the managed computer awakes from the sleep mode.

13 Reporting JP1 Events to JP1/IM

The results of jobs executed by Remote Install Manager can be sent to JP1/IM by using the event service functionality of JP1/Base. In JP1/IM, JP1 events sent from JP1/IT Desktop Management 2 can be checked in the Event Console window of JP1/IM - View.

This chapter describes the information (for example, types and attributes of JP1 events) used to check JP1 events sent from JP1/IT Desktop Management 2 to JP1/IM.

13.1 Types of JP1 events

This section describes the JP1 events that JP1/IT Desktop Management 2 sends to JP1/IM. Specify the JP1 events to be sent to JP1/IM on the Event Service panel in the Setup for Distribution by Using Remote Install Manager window of JP1/IT Desktop Management 2 - Manager Setup.

Job end event

A job end event is a JP1 event that is sent when a job is complete, and which reports the result of job execution to JP1/IM. The following lists the jobs whose execution results can be reported as job end events (JP1 events):

Install package job

Transfer package to relay computer job

Collect files from agent job

Remote-collect files from agent to relay computer job

Acquire collected files from relay computer job

Send package, allow client users to choose job

Instruction end event

An instruction end event is a JP1 event that is sent when the result of instruction execution is reported from the managed computer to report the result of instruction execution to JP1/IM. An instruction, which is the minimum unit of a job, is created by the managing server for each destination and package. For example, when a job to distribute two packages to two destinations is executed, four instructions are created.

Jobs whose execution results can be reported as instruction end events (JP1 events) are the same as those described for a job end event.

13.2 Attributes of JP1 events

A JP1 event has basic and extended attributes. An instruction end event notifies JP1/IM of detailed information about its extended attributes. You can check this information in the Event Console window of JP1/IM - View.

Table 12-1 lists the basic attributes of a JP1 event, Table 12-2 lists the extended attributes of a JP1 event, and Table 12-3 lists the detailed information about the extended attributes of an instruction end event.

This product uses the same event IDs used by JP1/NETM/DM. If you want to distinguish between JP1 events in JP1/NETM/DM and those in this product, define the name of this product as a filter condition for JP1/IM.

Table 13‒1: Basic attributes of a JP1 event

JP1 event name

Event ID

Message

Instruction end event

Normal end

00010402

Instruction xxx (instruction number) ended normally.

Error

00010403

Instruction xxx (instruction number) ended abnormally.

Job end event

Normal end

00010406

xxx (job name) ended normally.

Error

00010407

xxx (job name) ended abnormally.

Table 13‒2: Extended attributes of JP1 event

Attribute name

Meaning

Attribute value

SEVERITY

Severity

Severity for the system

(Error or Information)

USER_NAME

User name

User who executed the job

JP1_SOURCEHOST

Event source host name

Name of the host that caused the event triggering the issuance of a JP1 event

PRODUCT_NAME

Program product name

/HITACHI/JP1/ITDM2

OBJECT_TYPE

Object type

Hierarchical level where the JP1 event occurred

(DMJOB or COMMAND)

OBJECT_NAME

Object name

Name of the object that caused the JP1 event

(Job number or instruction number)

ROOT_OBJECT_TYPE

Root object type

Type of root object

(DMJOB)

ROOT_OBJECT_NAME

Root object name

Name to be the unit of root object execution

(Job number)

OBJECT_ID

Object ID

Character string that can be uniquely identified within the integrated system

(Job number or instruction number)

OCCURRENCE

Event type

Type of issued event

(END)

START_TIME

Start time

Execution start time (number of seconds from 00:00:00 on 1970-01-01)

END_TIME

End time

Execution end time (number of seconds from 00:00:00 on 1970-01-01)

RESULT_CODE

Result code

Result code

Table 13‒3: Detailed information about the extended attributes of instruction end event

Attribute name

Description

S1

Job name

S2

Job number

S3

Job type

D: Install package job

M: Transfer package to relay computer job

G: Collect files from agent job

S: Remote-collect files from agent to relay computer job

A: Acquire collected files from relay computer job

J: Send package, allow client users to choose job

S4

Instruction number

S5

Maintenance code

S6

Route information

P1

Package name

P2

Package ID

P3

Package version

P4

Package generation number

P5

Cabinet ID

P6

Package code

D: Package that was packaged from Windows

14 Commands of the Distribution Function That Uses Remote Install Manager

This chapter describes how to automate job execution and packaging in linkage with JP1/AJS, which is a program associated with JP1/IT Desktop Management 2. This chapter also describes the commands of the distribution function that uses Remote Install Manager.

14.1 Overview of automatic operations linked with JP1/AJS

JP1/IT Desktop Management 2 provides commands to run several functions, including packaging and remote installation. You can automatically operate various functions by these commands in combination with JP1/AJS functionality.

This section describes the following automatic operations by JP1/IT Desktop Management 2 in linkage with JP1/AJS:

Detecting a file update, and remotely installing the file automatically

Detecting a remote installation error, and retrying remote installation

Collecting files from remote managed computers, processing those files, and redistributing them

14.1.1 Detecting a file update and remotely installing the file automatically

If you install a PC used as a model for monitoring of data updates, you can automatically execute packaging and remote installation of data when a specific folder or file is updated. The following figure shows an overview of the process.

Figure 14‒1: Detecting a file update, and remotely installing a file automatically

In this example, the administrator can update data on all managed computers simply by storing the file to be distributed in a specific folder on a specific PC. The administrator can also automate all operations so as to prevent incorrect operations and distribution of incorrect files.

14.1.2 Detecting a remote installation error and retrying remote installation

You can automate a sequence of jobs for remote installation. Remote installation by JP1/IT Desktop Management 2 is monitored, and then data is retransmitted only to PCs on which remote installation fails. Reports of failures are sent to the administrator. The following figure shows an overview of the process.

Figure 14‒2: Detecting a remote installation error, and retrying remote installation

In this example, subsequent processing is triggered by an error. You can also design the system to automatically trigger other processing when remote installation ends normally.

14.1.3 Collecting files from remote managed computers, processing those files, and redistributing them

You can collect files from the managed computers installed at remote places by using the file collection function of JP1/IT Desktop Management 2, process data on the managing server, and update the database from the managing server. You can also transfer processed data to managed computers to update their respective data. The following figure shows an overview of the process.

Figure 14‒3: Collecting files from remote managed computers, processing those files, and redistributing them

14.2 Command types and input/output information

This section describes the types of commands for distribution by using Remote Install Manager, and the information input to and output by commands when they are executed.

14.2.1 Types of commands

This subsection describes the types of commands related to distribution by using Remote Install Manager, and classifies them according to purpose.

(1) Commands related to job creation and execution

These commands can be executed on the management server by a user who has permission to update the directory where JP1/IT Desktop Management 2 - Manager is installed. These commands connect to the managing server on the local host, and create and execute jobs.

Table 14‒1: Commands related to job creation and execution

Function

Command name

Reference section

This command creates and executes jobs related to remote installation. The following four types of jobs can be created and executed:

Install package job

Transfer package to relay computer job

Batch delete packages on relay computer job

Send package, allow client users to choose job

dcminst.exe

14.6

This command creates and executes jobs related to remote collection. The following four types of jobs can be created and executed:

Collect files from agent job

Remote-collect files from agent to relay computer job

Acquire collected files from relay computer job

Delete collected files from relay computer job

This command also unarchives collected archive files.

dcmcoll.exe

14.4

This command suspends or resumes file transfer.

dcmsusp.exe

14.17

This command executes a job defined in the managing server.

dcmjexe.exe

14.8

This command re-executes a job.

dcmrtry.exe

14.14

This command deletes an executed job.

dcmjbrm.exe

14.7

This command deletes a job definition.

dcmrmgen.exe

14.13

This command acquires job status.

dcmstat.exe

14.15

This command monitors job status, and starts an external program according to the monitored status.

dcmstsw.exe

14.16

(2) Commands related to packaging

These commands can be executed on the management server by a user who has permission to update the directory where JP1/IT Desktop Management 2 - Manager is installed. The catAndValidatePackagingFile.exe command, however, can be executed by all users. The dcmpack.exe command connects to the managing server specified by Packager, and executes packaging. Other commands connect to the managing server on the local host, and delete, back up, and recover packages.

Table 14‒2: Commands related to packaging

Function

Command name

System on which the command can run

Reference section

This command packages user data and user programs.

dcmpack.exe

Computer with Packager installed

14.9

This command deletes a package from a cabinet.

dcmpkrm.exe

Management server

14.12

This command makes a backup of a package.

dcmpkget.exe

Management server

14.10

This command recovers a package by using a backup.

dcmpkput.exe

Management server

14.11

This command combines files split by the dcmpack command and restores a file before split.

catAndValidatePackagingFile.exe

All computers

14.18

(3) Command related to system configuration

This command can be executed on the management server by a user who has permission to update the ODBC system data source. This command connects to the managing server on the local host, and applies policies to all hosts in a host group.

Table 14‒3: Command related to system configuration

Function

Command name

Reference section

This command applies created policies to all registered hosts to add them to a host group.

dcmgpmnt.exe

14.5

14.2.2 Input/output information at command execution

The following figure shows the information that is input to and output by a command when it is executed.

Figure 14‒4: Input/output information at command execution

(1) Input information

To execute a command, execution conditions and details of the job to be executed are specified in command arguments and a parameter file. Some items can be specified in both command arguments and a parameter file, while other items can be specified only in command arguments or a parameter file.

Command

The name of the command to be executed and values of its arguments are input. In arguments, you can specify the names of parameter files and output files, and also define various execution conditions for the job to be executed.

Parameter file

A parameter file is used to write the information required for job execution, for example, the destination of remote installation and installation conditions. For how to create a parameter file, see 14.20 Creating a parameter file. You can input the output file (that is output when a command is executed) as a parameter file for another command.

(2) Output information

You can check the following information to know the execution result of a command.

Return code

The execution result of a command is output as a return code.

Output file

The execution result of a command is output to the output file that is specified at execution of the command. You can use this output file as a parameter file for execution of a command to acquire job status or re-execute a job.

(3) Note

When executing commands by using Windows Task Scheduler or JP1/AJS, carefully avoid specifying parameter files and output files in directories or folders in a network drive, for which users who execute commands do not have access permissions.

14.2.3 Checking command error information

If a command has resulted in an error, you can check event logs by using Event Viewer of Windows.

Check the event (event ID is 1 to 2018) for which JP1ITDM2 (DMU) is displayed in the Source column in the Event Viewer window. Detailed event information provides the command name and error cause details. The following is an example of the detailed information display:

dcmpack.exe /i C:\dmbat\in.txt /k********

The parameter file includes invalid values: L.23

This detailed information indicates that line No. 23 in the parameter file (C:\dmbat\in.txt) has an error. "********" represents the password you specified.

14.2.4 Command input format

Use the following format to specify a command related to distribution by using Remote Install Manager:

command-name /argument-1 [value-1] [/argument-2 [value-2] ... ]

As an argument, specify a string of alphabetic characters beginning with /.

Every character string beginning with / is interpreted as an argument. Therefore, you must not specify any character string beginning with / as a value.

One or more spaces must be inserted between the command name and argument, and between an argument and its value.

When a value includes a space or MS-DOS control character, enclose the value in double quotation marks ("). Every string enclosed in " " is analyzed according to the MS-DOS specification. To write " as a character in a string enclosed in " ", write \".

Example:

dcmpack.exe /b "dcmpack /i \"C:\dev 1\parameter-file-1.txt\"" /i "C:\dev 2\parameter-file-2.txt"

14.3 Command description format

In this chapter, the commands that can use parameter files are described on the premise that they use parameter files. The specification items that can be specified in both parameter files and command arguments are assumed to be specified in parameter files. For how to specify those specification items with the same content by using command arguments, see Command format without using any parameter file for individual commands.

In a parameter file for a command, write the parameters required to execute the command under different tags corresponding to the contents of parameters. To create a parameter file, first confirm the tags corresponding to the parameters to be set in the table for the specification contents of the parameter file. After that, check how to specify individual tags in 14.20.3 How to specify tags. For details about the types of tags, and parameter file format, see 14.20 Creating a parameter file.

If a specification item is specified in both a parameter file and a command argument, only the specification in the command argument is effective (the specification in the parameter file is ignored). Note, however, that, for the dcmpkget command, some items defined in the parameter file are effective, even when the same items are specified in both the parameter file and command arguments. For details about the dcmpkget command, see 14.10 dcmpkget.exe (making a backup of a package).

The following items are described for individual commands:

Function

Describes the function of a command.

Format

Shows the syntax of a command. An argument enclosed in brackets ([ ]) can be omitted. For commands that can use parameter files, the syntax is shown on the premise that parameter files are used.

Example of format

dcmXXXX.exe [/A] [/B]
             /i parameter-file-1 [parameter-file-2]

In this example of format, you can omit arguments other than /i parameter-file-1. Also, you can specify a maximum of two parameter files.

Arguments

Describes the arguments shown in Format. The arguments described here are those which cannot be specified in a parameter file.

Correspondence between the specification contents of parameter file and command arguments

Describes, in table format, the specification contents of the parameter file to be used for the command. The table also shows command arguments corresponding to parameters of parameter files that can be specified also as command arguments.

For details about parameters (and their defaults) that are specified in parameter files, see 14.20 Creating a parameter file. If a specification item is specified in both a parameter file and a command argument, only the specification in the command argument is effective, and the specification in the parameter file is ignored.

In the description of the command for which no parameter of the parameter file can be specified as a command argument, the title of this description item is replaced with Specification contents of parameter file.

Command format without using any parameter file

Shows the command format to be used when you do not use a parameter file but use only command arguments. The vertical bar (|) indicates that only one of the specification items separated by | can be specified.

Example of format

dcmXXXX.exe [/A|/B]
             /j job-name [/l path-name-of-job-storage-folder]

In this example of format, you can omit the arguments other than /j job-name. Also, you can specify /A or /B.

In the description of a command for which no parameter of the parameter file can be specified as a command argument, or the command that cannot use any parameter file, this description item is omitted.

Return codes

Describes the return codes that are output when a command is executed.

Note

Describes any points to be noted for a command.

Example

Describes how to execute a command with an actual example.

14.4 dcmcoll.exe (collecting files)

This section describes the dcmcoll command, which collects files.

You can check the result of a job executed by this command in the Job Status window of the managing server.

Function

This command creates and executes the following jobs related to remote collection:

Collect files from agent job

Remote-collect files from agent to relay computer job

Acquire collected files from relay computer job

Delete collected files from relay computer job

This command also unarchives collected archive files.

Format

dcmcoll.exe [processing-key] [/G] [/Z] [/s]
            /i parameter-file-1 [parameter-file-2]
            [/o output- file-name]

Arguments

processing-key

This argument specifies the type of job to be executed. Specify one of the processing keys listed below immediately after the command name. When this argument is omitted, specification of NETM_COLLECT is assumed.

NETM_COLLECT

When the processing key is NETM_COLLECT, this command executes a Collect files from agent job. In the parameter file (or command arguments), specify the job destination, file to be collected, and storage directory for collected file.

NETM_COLTOS

When the processing key is NETM_COLTOS, this command executes a Remote-collect files from agent to relay computer job. In the parameter file (or command arguments), specify the job destination, file to be collected, and storage directory for collected file.

NETM_COLTOM

When the processing key is NETM_COLTOM, this command executes an Acquire collected files from relay computer job. In the parameter file (or command argument), specify the job destination (a relay system or management relay server).

NETM_COLRESET

When the processing key is NETM_COLRESET, this command executes a Delete collected files from relay computer job. In the parameter file (or a command argument), specify the job destination (a relay system or management relay server).

NETM_UNARC

When the processing key is NETM_UNARC, this command unarchives an archive file (with the extension of dmz). In the parameter file (or command arguments), specify the name of the file to be unarchived, the directory storing the file, and the directory to store unarchived files.

/G

When the argument /G is specified and the processing key is NETM_UNARC, this command directly stores unarchived files in the directory specified as the restoration destination. When the processing key is other than NETM_UNARC, this argument is ignored even if specified.

When the argument /G is omitted, this command automatically generates a directory with the same name as the host name of the job destination under the directory specified as the directory to store unarchived files.

Do not specify this argument when you need to distinguish the job-destination host from others.

/Z

When the argument /Z is specified and the processing key is NETM_UNARC, this command deletes the archive file at the same time as unarchiving the file. The directory having stored the archive file is not deleted.

When the processing key is other than NETM_UNARC, this argument is ignored even if specified.

/s

When the argument /s is specified, this command creates a job, and then stores it without execution. When the processing key is NETM_UNARC, this argument is ignored even if specified.

When this command is executed with this argument specified, the job number is not output to the output file.

/i

In the argument /i, specify one or two full path names of the parameter files to be used. When specifying two full path names, separate them by a space. Specifying more than two full path names will cause this command to fail.

When two parameter files are specified, JP1/IT Desktop Management 2 interprets individual files while linking their contents with each other. If you define the information on the job destination and the information on file collection and restoration in separate parameter files, you can conveniently change the content of either file when you want to re-execute this command.

Because unnecessary parameters are ignored, the parameter files can be shared for file collection and file restoration. Specifying the same parameter in both parameter files will cause an error.

/o

In the argument /o, specify the full path name of the output file.

When the processing key is NETM_UNARC, this argument is ignored even if specified. When the processing key is other than NETM_UNARC, always specify this argument.

When this command ends normally, the items listed below are output to the specified output file. If the output file already contains data, the data is overwritten.

Job name

Job number

Path name of job storage folder

The job number (value of jobno) identifies the job that is started. When you need to delete the job or check the job status, write the value of jobno to the parameter file.

When the argument /s is specified, the job number is not output.

When the argument /s is specified, the output file can be used as a parameter file for the dcmjexe command without change. When the argument /s is not specified, the output file can be used as a parameter file for the dcmjbrm, dcmrtry, dcmstat, and dcmstsw commands.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file and the command arguments corresponding to them.

Table 14‒4: Correspondence between parameter file contents and command arguments (dcmcoll command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_DESTINATION

group

Host group name

Y#1

/g value

host_name

Host name

Y#1

/h value

JOB_DESTINATION_ID

destination_id

ID name

Y#1

/X value

FILE_COLLECTION

source_path

Name of file to be collected

Y#2

/y value

dmz_path

Storage folder for collected file (for collection) or file/folder to be unarchived (for restoration)

Y#3

/z value

unarc_path

Storage folder for unarchived file

Y#4

/r value

JOB_ATTRIBUTE

job_generator

Job name

Y/N#5

/j value

jobno

Job number

N

--

job_folder

Path name of job storage folder

Y/N

/l value

unsuspended

Whether to distribute during suspension

N

--

JOB_SCHEDULE

job_entry_date

Job registration date and time

Y/N#6

/jst value

job_execution_date

Job execution date and time

Y/N#6

/jsx value

job_expiration_date

Job expiration date

Y/N#6

/jsp value

SCHEDULE

expiration_date

Expiration date of package storage on relay computer

N

--

expiration_days

The relay computer holds relayed packages for

N

--

installation_date_and_time

Installation date and time

N

--

installation_timing

Installation (collection) timing

Y/N

/tS or /tN

OPTION

compress

Whether to compress

Y/N

/uY or /uN

restore

Whether to restore at upgrade

N

--

reboot

Computer restart after installation

N

--

processing_dialog

Whether to display processing message during installation

N

--

USER_PROGRAM_INSTALLATION_CONDITIONS

external_program_executed_before_installation

External program to be started before installation (collection)

Y/N

/b value

external_program_executed_after_installation

External program to be started after installation (collection)

Y/N

/a value

external_program_error_handler

External program to be started at installation (collection) error

Y/N#7

/e value

external_program_handler

External program to be started

N

--

exit

How to report the processing result of external program

N

--

action

Action to take when processing result is error

N

--

wait

Monitoring method

N

--

timeout

Monitoring time

N

--

wait_code

Monitoring code

N

--

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag. Also, you cannot specify /g and /h together with /X. You must specify only either JOB_DESTINATION or JOB_DESTINATION_ID or either /g and /h or /X.

When the processing key is NETM_COLTOM or NETM_COLRESET, only the ID group registered as an ID-management relay computer can be specified as the job destination.

When the processing key is NETM_UNARC, this parameter is ignored even if specified.

#2

When the processing key is NETM_COLLECT or NETM_COLTOS, you must specify this parameter.

#3

When the processing key is NETM_COLLECT, NETM_COLTOS, or NETM_UNARC, you must specify this parameter.

#4

When the processing key is NETM_UNARC, you must specify this parameter.

#5

When the job_generator parameter (or the argument /j) is omitted, processing key and job execution date and time is automatically set as the job name. Therefore, if multiple commands with the same processing key are executed concurrently, their job names might be duplicated, and their jobs might not be executed correctly. We recommend that, when executing multiple commands with the same processing key concurrently, you specify different job names for the commands by using job_generator (or /j).

#6

When the processing key is NETM_UNARC, this parameter is ignored even if specified.

#7

You cannot specify this parameter when you collect files from UNIX computers.

Command formats without using any parameter file

The following shows the command formats to be used when you specify only command arguments without using a parameter file.

To collect files from managed computers:

dcmcoll.exe {[NETM_COLLECT]|NETM_COLTOS} [/s]
            {[/g host-group- name] [/h host-name]|/X ID-name}
            /y name-of-file-to-be-collected /z path-name-of-storage-folder-for-the-files-to-be-collected
            [/j job-name] [/l path-name-of-job-storage-folder]
            [/jst job-registration-date-and-time] [/jsx job-execution-date-and-time]
            [/jsp job-expiration-date]
            [{/tS|/tN}] [ {/uY|/uN}]
            [/b external-program-to-be-started-before-file-collection]
            [/a external-program-to-be-started-after-file-collection]
            [/e external-program-to-be-started-at-file-collection-error]
            /o output-file-name

To collect or delete files collected on a relay system or management relay server:

dcmcoll.exe {NETM_COLTOM|NETM_COLRESET} [/s]
            {[/g host-group- name] [/h host-name]|/X ID-name}
            [/j job-name] [/l path-name-of-job-storage-folder]
            [/jst job-registration-date-and-time] [/jsx job-execution-date-and-time]
            [/jsp job-expiration-date]
            /o output-file-name

To unarchive files:

dcmcoll.exe NETM_UNARC [/G] [/Z]
            /z file-or-folder-to-be-unarchived
            /r storage-folder-for-unarchived-file

Return codes

The following table lists the return codes that are output when the dcmcoll command is executed:

Code

Meaning

Action to be taken

0

The managing server started the job, or restoration of archive file ended normally.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in a command argument or the parameter file.

Check the values specified in command arguments and the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file cannot be opened.

Check the specification of the output file.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

7

Restoration of one or more archive files failed.

Check the path name of each archive file.

The full path name of the archive file might exceed 259 single-byte characters. (The full path name consists of the name of the storage directory for unarchived file, name of file creation directory (name of the storage directory for archive file), and name of unarchived file or directory.)

12

Other error occurred.

Reference the event log.

Notes

Specifiable numbers of job destinations and the files to be collected

When you use the parameter file for specification, you can specify a maximum of 200 job destinations (such as hosts, host groups, and ID groups) per single execution of the dcmcoll command. For 200 job destinations, you can specify a maximum of 100 files or directories to be collected.

When using command arguments for specification, you can specify only one job destination and one file to be collected.

Even if multiple job destinations and files to be collected have been specified in the parameter file, all those specifications become invalid when a job destination and a file to be collected are specified by using command arguments.

When you execute a command, do not specify the same destination more than once. It will execute the same jobs at a destination for multiple times.

Route to a job destination

You can specify a route to a job destination. Even if the same job destination is specified as multiple definitions with different routes, only the first definition is valid.

Jobs destined for a relay system or management relay server

The Acquire collected files from relay computer and Delete collected files from relay computer jobs specify a relay system or management relay server as the destination. If a managed computer is specified as the destination of either job, the job results in an error, or is kept in the running state.

Collection-destination and restoration-destination directories

When files are collected, a directory with the same name as the job-destination host name is automatically created under the directory specified as the collection destination. Files are archived when they are collected, and stored as an archive file (with the extension.dmz) in the directory whose host name corresponds to the collected files.

When an archive file is unarchived, a directory with the same name as the host name corresponding to the archive file is automatically created under the directory specified as the restoration destination (in a similar way to file collection). Note, however, that, if multiple archive files are unarchived at the same time, any files of the same name and included in different archive files will overwrite one another. Therefore, if you want to unarchive multiple archive files, some of which include a file of the same name, execute the dcmcoll command specifying different restoration-destination directories for the different archive files.

When an archive file is unarchived by the dcmcoll command with the argument /G specified, files are extracted directly in the directory specified as the restoration destination. If the archive files collected from multiple job destinations are unachieved at a time by the dcmcoll command with /G specified, all extracted files overwrite one another, and cannot be sorted out by job destination. Use the argument /G only when unarchiving a single archive file.

When an archive file is unarchived by the dcmcoll command without the argument /G specified, a directory with the same name as the job-destination host name is automatically created under the directory specified as the storage destination for unarchived files. When, however, the directory storing the archive file to be unarchived is specified in the argument /z or the dmz_path parameter in the FILE_COLLECTION tag, no directory is created. Then, files are extracted directly in the directory specified as the storage destination for unarchived files.

If you need to sort out unarchived files by job destination, specify the directory you specified for file collection in the argument /z or the dmz_path parameter in the FILE_COLLECTION tag.

Specification of the path name of job storage folder

When you execute the dcmcoll command specifying the path name of a folder not defined in the Job Definition window as the path name of job storage folder, the specified folder is created. The created job storage folder is not deleted, even after command execution. If you do not use this folder, delete it after the job is complete.

Points to be noted when not using a parameter file

If the collection destination is a workstation (UNIX system), specify any drive as the drive of the collection destination directory. However, the specified drive will be ignored during collection, and files will be collected according to the specified directory. In the following example, the drive name c: is ignored.

Example: c:/user/tmp

When you use a backslash (\) to separate each directory, there is no need to specify a drive name.

Example: \user\tmp

Notes on specifying external programs

If the collection destination is a workstation (UNIX system), and you specify external programs, use a parameter file to execute commands.

Notes on execution of remote collection job and restoration of archive file

See 9.1.4 Notes on executing remote collection.

Notes on execution of the command

If you pause the command by pressing of the (Ctrl + C, or else) keys during the execution, the job definitions that the command has created might not be deleted.

If you pause the command, check the job definition window on the remote install manager and delete job definitions if necessary.

Example

The following example shows use of this command to collect files from the directories SDerror.dir, SDerror2.dir, and SDerror3.dir under the directory C:\temp on the hosts dmp491 and dmp492 on which JP1/IT Desktop Management 2 - Agent (agent) is running. The parameter file defines operations to start collection when the managed computer starts, and to activate an external program before and after collection, and if a collection error occurs.

Creating the parameter file

Specify the hosts and the attributes of the files to be collected as shown below, and then save the parameter file under any name.

** dcmcoll Parameter File Sample

JOB_DESTINATION{
host_name=dmp492.soft.hitachi.co.jp
host_name=dmp491
group = \grp\gname1
group = \grp\gname2;\grp\gname3
}
SCHEDULE{
installation_timing = S
}
OPTION{
compress=Y
}
USER_PROGRAM_INSTALLATION_CONDITIONS{
external_program_executed_before_installation = "C:\test B.exe"
external_program_executed_after_installation = C:\testA.exe -x "a aa"
external_program_error_handler = "C:\test E.exe"
}
FILE_COLLECTION{
source_path= C:\temp\SDerror.dir
source_path= C:\temp\SDerror2.dir;C:\temp\SDerror3.dir
dmz_path= C:\temp\collection
}

Executing the command

To store the created parameter file as C:\Dmbat\dcmcoll.txt and acquire the output file as C:\Dmbat\out.txt, specify the command as follows:

dcmcoll.exe /i C:\Dmbat\dcmcoll.txt /o C:\Dmbat\out.txt /j tempcollection

Checking the output file

When the command ends normally, the job name, job number, and path name of job storage folder are output to the file C:\Dmbat\out.txt as follows:

JOB_ATTRIBUTE{
job_generator= NETM_COLLECT_03_12_11_13_34_36
jobno= JB03121113315383
job_folder= \
}

14.5 dcmgpmnt.exe (applying policies to all hosts in a host group)

This section describes the dcmgpmnt command, which applies policies to all the hosts in a host group.

Function

This command connects to the managing server (JP1/IT Desktop Management 2 - Manager) on the local host, and adds all the registered hosts to a host group according to created policies.

Format

dcmgpmnt.exe [processing-key]

Arguments

processing-key

This argument specifies the type of policy to be applied to all hosts in a host group. Specify one or more processing keys among those listed below immediately after the command name. When this argument is omitted, specification of ALLGROUP is assumed.

ALLGROUP

When the processing key is ALLGROUP, this command applies all policies to all hosts in a host group.

IPSCOPE

When the processing key is IPSCOPE, this command applies the policy whose type is IP address to all hosts in a host group.

OSTYPE

When the processing key is OSTYPE, this command applies the policy whose type is OS type to all hosts in a host group.

HWASSETFIELD

When the processing key is HWASSETFIELD, this command applies the policy whose type is Custom Fields (Hardware Assets) to all hosts in a host group.

DEPARTMENT

When the processing key is DEPARTMENT, this command applies the policy whose type is department to all hosts in a host group.

LOCATION

When the processing key is LOCATION, this command applies the policy whose type is location to all hosts in a host group.

You can specify IPSCOPE, OSTYPE, HWASSETFIELD, DEPARTMENT, and LOCATION in any combination. When you specify a combination of processing keys, separate them by a space. Note that specifying processing keys in one of the following ways results in an error indicated by the return code 2.

Specifying ALLGROUP together with any other processing key

Specifying the same processing key multiple times

Return codes

The following table lists the return codes that are output when the dcmgpmnt command is executed:

Code

Meaning

Action to be taken

0

Processing ended normally, or no target host was found.

None

2

An invalid value was set in a command argument.

Check the values set in command arguments.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

15

Another process is updating the database.

Wait awhile, and then re-execute the command, or check the process that is updating the database.

Example

The following example shows use of this command to apply the policies whose types areIP address and OS type to the hosts in a host group.

dcmgpmnt.exe IPSCOPE OSTYPE

Notes

The time required for the batch maintenance of a host group increases in proportion to the number of hosts and the number of policies.

While batch maintenance is being executed, host group automatic maintenance (executed when device information is updated) does not work. Therefore, we recommend that you execute host group batch maintenance during a period when less device information is updated.

14.6 dcminst.exe (creating and executing jobs)

This section describes the dcminst command, which creates and executes jobs.

You can check the result of a job executed by this command in the Job Status window of the managing server.

Function

This command creates and executes the following jobs related to remote installation:

Install package job

Transfer package to relay computer job

Batch delete packages on relay computer job

Send package, allow client users to choose job

Format

dcminst.exe [processing-key] [/f] [/s]
            /i parameter-file-1 [parameter-file-2]
            /o output-file-name

Arguments

processing-key

This argument specifies the type of job to be executed. Specify one of the processing keys (listed below) immediately after the command name. If this argument is omitted, specification of NETM_INSTALL is assumed.

NETM_INSTALL

When the processing key is NETM_INSTALL, this command executes an Install package job. In the parameter file (or command arguments), specify the package to be installed and the job destination.

NETM_STORE

When the processing key is NETM_STORE, this command executes a Transfer package to relay computer job. In the parameter file (or command arguments), specify the package to be transferred and the job destination (an agent that is under a relay system or management relay server and that has the same name as the relay system or management relay server).

NETM_DELETE

When the processing key is NETM_DELETE, this command executes a Batch delete packages on relay computer job. In the parameter file (or command arguments), specify the job destination (an agent that is under a relay system or management relay server and that has the same name as the relay system or management relay server).

NETM_USERINST

When the processing key is NETM_USERINST, this command executes a Send package, allow client users to choose job. In the parameter file (or command arguments), specify the package to be installed and the job destination.

/f

If the package specified as the installation target has already been installed in the installation-destination computer, this command with the argument /f specified installs the package by overwriting the already installed package. When this argument is not specified, this command ends normally without overwriting the already installed package.

When the processing key is NETM_DELETE, this argument is ignored even if specified.

/s

When the argument /s is specified, this command creates a job, and then stores it without execution. When the processing key is NETM_UNARC, this argument is ignored even if specified.

When this command is executed with this argument specified, the job number is not output to the output file.

/i

In the argument /i, specify one or two full path names of the parameter files to be used. When specifying two full path names, separate them by a space. Specifying three or more full path names causes this command to fail.

When two parameter files are specified, JP1/IT Desktop Management 2 interprets individual files while linking their contents with each other. If you define the job destination and the package to be installed in separate parameter files, you can conveniently use the parameter files. For example, you can re-distribute a different package to the same computer or the same package to a different destination simply by changing the content of either file. In this case, you can use the output file of the dcmpack command as a parameter file specifying package attributes.

/o

In the argument /o, specify the full path name of the output file. When this command ends normally, the items listed below are output to the specified output file. If the output file already contains data, the data is overwritten.

Job name

Job number

Path name of job storage folder

The job number (value of jobno) identifies the job that is started. When you need to delete the job or check the job status, write the value of jobno to the parameter file. Note that, if the argument /s is specified, the job number is not output.

If the argument /s is specified, the output file can be used as a parameter file for the dcmjexe and dcmrmgen commands without change. When the argument /s is not specified, the output file can be used as a parameter file for the dcmjbrm, dcmrtry, dcmstat, and dcmstsw commands.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file and the command arguments corresponding to them.

Table 14‒5: Correspondence between parameter file contents and command arguments (dcminst command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_DESTINATION

group

Host group name

Y#1

/g value

host_name

Host name

Y#1

/h value

JOB_DESTINATION_ID

destination_id

ID name

Y#1

/X value

PACKAGING_INFORMATION#2

package_name

Package name

Y

/p value

package_id

Package ID

Y

/I value

version_revision

Version/revision

Y

/v value

generation

Generation number

Y

/G value

cabinet_name

Cabinet name

Y

/c value

cabinet_id

Cabinet ID

Y

/C value

package_code

Code type

Y/N

/KW or /KP

JOB_ATTRIBUTE

job_generator

Job name

Y/N#3

/j value

jobno

Job number

N

--

job_folder

Path name of job storage folder

Y/N

/l value

unsuspended

Whether to distribute during suspension

Y/N#4

/uns value

JOB_SCHEDULE

job_entry_date

Job registration date and time

Y/N

/jst value

job_execution_date

Job execution date and time

Y/N

/jsx value

job_expiration_date

Job expiration date

Y/N

/jsp value

JOB_SPLIT_DELIVERY#4

split_size

Split size

Y/N

/sds value

wait_time

Distribution interval

Y/N

/sdt value

JOB_CLIENT_CONTROL

client_wake_up

Whether to start the client

Y/N

/WWU

client_shutdown

Whether to shut down the client

Y/N

/WUS

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag. Also, you cannot specify /g and /h together with /X. You must specify only either JOB_DESTINATION or JOB_DESTINATION_ID, or either /g and /h or /X.

Note that, when the processing key is NETM_STORE or NETM_DELETE, you cannot specify an ID.

#2

For this command, you cannot use a reserved word for any parameter in the PACKAGING_INFORMATION tag.

#3

When the job_generator parameter (or the argument /j) is omitted, processing key and job execution date and time is automatically set as the job name. Therefore, if multiple commands with the same processing key are executed concurrently, their job names might be duplicated, and their jobs might not be executed correctly. We recommend that, when executing multiple commands with the same processing key concurrently, you specify different job names for the commands by using job_generator (or /j).

#4

You cannot specify the unsuspended parameter of the JOB_ATTRIBUTE tag together with the JOB_SPLIT_DELIVERY tag.

Command format without using any parameter file

The following shows the command format to be used if you specify only command arguments without using a parameter file.

dcminst.exe [processing-key] [/f] [/s]
            {[/g host-group-name] [/h host-name]|/X ID-name}
              /p package-name /I package-ID
              /v version/revision /G generation-number
              /c cabinet-name /C cabinet-ID
            [{/KW|/KP}]
            [/j job-name] [/l path-name-of-job-storage-folder]
            [/uns whether-to-distribute-during-suspension]
            [/jst job-registration-date-and-time] [/jsx job-execution-date and-time]
            [/jsp job-expiration-date]
            [/sds split-size] [/sdt distribution-interval]
            [/WWU whether-to-start-the-client]
            [/WUS whether-to-shut-down-the-client]
             /o output-file-name

Return codes

The following table lists the return codes that are output when the dcminst command is executed:

Code

Meaning

Action to be taken

0

The managing server started the job.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in a command argument or the parameter file.

Check the values specified in command arguments and the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file cannot be opened.

Check the specification of the output file.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Notes

Specifiable numbers of job destinations and packages

When you use the parameter file for specification, you can specify a maximum of 200 job destinations per single execution of the dcminst command. Also, you can specify a maximum of 100 packages per single execution of the command.

When using command arguments for specification, you can specify only one job destination and package. In the arguments /g and /h, however, you can specify a maximum of 200 values for each, by separating the values by a semicolon (;).

Even if multiple packages have been specified in the parameter file, the package all specifications become invalid when packages are specified by using command arguments.

When you execute a command, do not specify the same destination or package more than once. It will execute the same jobs at a destination for multiple times.

Specification of argument /f

When the argument /f is specified, this command transmits packages to specified destinations regardless of whether the same packages have already been distributed to the destinations. To avoid needlessly increasing network traffic, use the argument /f only when you need to overwrite already-distributed packages.

When the argument /f is specified, this command enables you to install software (of the same version, but different content, as already-installed software) by overwriting. If, however, overwrite installation is performed, JP1/IT Desktop Management 2 might be disabled from managing versions in installed package information.

How this command operates when the job name specified in the job_generator parameter under the JOB_ATTRIBUTE tag already exists

This command creates a new job based on the job definition for the existing job.

Specification of whether to start the client

When specifying whether to start the client, specify a host group name or ID for the job destination. If you specify a host name for the job destination, the specification of whether to start the client, is ignored. Note that, when the job destination is a relay system, the specification of whether to start the client, is ignored unconditionally.

Specification of the path name of job storage folder

When you execute the dcmcoll command specifying the path name of a folder not defined in the Job Definition window as the path name of job storage folder, the specified folder is created. The created job storage folder is not deleted, even after command execution. If you do not use this folder, delete it after the job is complete.

Job names when executing multiple dcminst commands

When you execute multiple dcminst commands, do not omit the job names but specify a unique job name for each job. Also, when you simultaneously execute the remote installation related jobs from the remote install manager or using the dcminst command, make sure to specify a unique job name for each job.

Notes on execution of the command

If you pause the command by pressing of the (Ctrl + C, or else) keys during the execution, the job definitions that the command has created might not be deleted.

If you pause the command, check the job definition window on the remote install manager and delete job definitions if necessary.

Example

The following example shows use of this command to distribute software packaged under the name of Finance Data 2003 5 to the hosts dmp491 and dmp492, on which JP1/IT Desktop Management 2 - Agent (agent) is running.

Creating the parameter file

Specify the hosts and the attributes of the packages as shown below, and then save the parameter file under any name.

** dcminst Parameter File Sample

JOB_DESTINATION{
host_name=dmp491;dmp492
}
PACKAGING_INFORMATION
{
package_name=Finance Data 2003 5
package_id=FD200305
version_revision=000001
generation=0000
cabinet_name=FCAB01
cabinet_id=F1
package_code=P
}

Executing the command

To store the created parameter file as C:\Dmbat\dcminst.txt and acquire the output file as C:\Dmbat\out.txt, specify the command as follows:

dcminst.exe /i C:\Dmbat\dcminst.txt /o C:\Dmbat\out.txt /j overwrite installation /f

Checking the output file

When the command ends normally, the job name, job number, and path name of the job storage folder are output to the file C:\Dmbat\out.txt as follows:

JOB_ATTRIBUTE{
job_generator= NETM_INSTALL_2003_12_11_13_34_36
jobno= JB03121113315383
job_folder= \
}

14.7 dcmjbrm.exe (deleting a job)

This section describes the dcmjbrm command, which deletes an executed job.

Function

This command deletes, on the managing server, an executed job specified in the parameter file.

Format

dcmjbrm.exe /i parameter-file-name

Arguments

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can also use the output file output by the dcmcoll command (without /s specified), the dcminst command (without /s specified), the dcmjexe command, or the dcmsusp command (without /s specified) as the parameter file.

Specification contents of parameter file

The table below shows the specification contents of the parameter file for the dcmjbrm command. The contents of the parameter file for this command cannot be specified by using command arguments.

Table 14‒6: Specification contents of parameter file (dcmjbrm command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

N

--

jobno

Job number

Y

--

job_folder

Path name of job storage folder

N

--

unsuspended

Whether to distribute during suspension

N

--

Legend:

Y: The parameter must be specified.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

Return codes

The following table lists the return codes that are output when the dcmjbrm command is executed:

Code

Meaning

Action to be taken

0

The specified job was set to the Now being deleted state, or was not found.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check the database settings in the setup of the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Notes

In the parameter file, specify the job number that was output to the output file by the dcmcoll command (without /s specified), the dcminst command (without /s specified), the dcmjexe command, or the dcmsusp command (without /s specified).

If the job number of the job to be deleted is unknown, you cannot execute the dcmjbrm command. In such cases, in the Job Status window of the managing server, delete the job that has the job name of the job to be deleted.

Example

The following example shows use of this command to delete the Collect-slip-file-0001 job executed by the dcmjexe command.

Creating the parameter file

In the parameter file, specify the job number output to the output file by the dcmjexe command as shown below.

If the output file output by the dcmjexe command has been stored, you can specify the stored file as the parameter file.

** dcmjexe output->dcmjbrm input

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
jobno= JB03121113315383
job_folder= \batch-definition
}

Executing the command

When the output file output by the dcmjexe command is stored as the file C:\Dmbat\out.txt, specify the command as follows:

dcmjbrm.exe /i C:\Dmbat\out.txt

14.8 dcmjexe.exe (executing a job)

This section describes the dcmjexe command, which executes a job.

Function

This command executes a job defined in the parameter file. You can specify only one job to be executed in the JOB_ATTRIBUTE tag.

Format

dcmjexe.exe /i parameter-file-name /o output-file-name

Arguments

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can also use the output file output by the dcmcoll command (with /s specified), the dcminst command (with /s specified), or the dcmsusp command (with /s specified) as the parameter file.

/o

In the argument /o, specify the full path name of the output file. When this command ends normally, the items listed below are output to the specified output file. Any data already contained in the output file is overwritten.

Job name

Job number

Path name of job storage folder

The job number (jobno value) identifies the job that is started. When you need to delete the job or check the job status, write the jobno value to the parameter file. The output file can be used as a parameter file for the dcmjbrm, dcmrtry, dcmstat, and dcmstsw commands.

Correspondence between the specification contents of parameter file and command arguments

This command always requires a parameter file. Some contents of the parameter file, however, can also be specified in command arguments. The following table shows the specification contents of the parameter file and the command arguments corresponding to them.

Table 14‒7: Correspondence between parameter file contents and command arguments (dcmjexe command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

Y

--

jobno

Job number

N

--

job_folder

Path name of job storage folder

Y/N#

--

unsuspended

Whether to distribute during suspension

N

--

JOB_SCHEDULE

job_entry_date

Job registration date and time

Y/N

/jst value

job_execution_date

Job execution date and time

Y/N

/jsx value

job_expiration_date

Job expiration date

Y/N

/jsp value

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#

If this parameter is omitted, this command searches all the folders and files under the root folder to find the specified job, and then executes the job.

Command format to be used when the contents of the parameter file are specified in command arguments

The following shows the command format to be used when you specify the job registration date and time, job execution date and time in command arguments.

dcmjexe.exe /i parameter-file-name /o output-file-name
           [/jst job-registration-date-and-time] [/jsx job-execution-date-and-time]
           [/jsp job-expiration-date]

Return codes

The following table lists the return codes that are output when the dcmjexe command is executed:

Code

Meaning

Action to be taken

0

The managing server started the job.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file cannot be opened.

Check the specification of the output file.

The job might have started. Check the job status.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Example

The following example shows use of this command to execute the Collect-slip-file-0001 job stored in the batch-definition folder in the managing server.

Creating the parameter file

Specify the folder storing the job to be executed and the name of the job as shown below, and then save the parameter file under any name.

** dcmjexe Parameter File Sample

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
job_folder= \batch-definition
}

Executing the command

To store the created parameter file as C:\Dmbat\dcmjexe.txt and acquire the output file as C:\Dmbat\out.txt, specify the command as follows:

dcmjexe.exe /i C:\Dmbat\dcmjexe.txt /o C:\Dmbat\out.txt

Contents of the output file

When the command ends normally, the job name and job number of the executed job and the path name of job storage folder (storing the executed job) are output to the file C:\Dmbat\out.txt as follows:

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
jobno= JB03121113315383
job_folder= \batch-definition
}

14.9 dcmpack.exe (executing packaging)

This section describes the dcmpack command, which packages user data and user programs.

Function

This command packages user data and user programs in the managing server (JP1/IT Desktop Management 2 - Manager).

This command cannot package program products.

Format

dcmpack.exe /k password
            /i parameter-file-name [/o output-file-name]
            [/split /tempdir temporary-folder-name [/splitfilesize size-of-files-after-split]]

Arguments

/k

In the argument /k, specify the password to package software in the managing server.

Specify the password for the database of the managing server.

/i

In the argument /i, specify the full path name of the parameter file.

/o

Specify the full path name of the output file. When this command ends normally, the attribute information of the created package is output to the specified output file. You can use this output file as a parameter file for the dcminst, dcmpkget, and dcmpkrm commands.

When this argument is omitted, no output file is created.

/split

Specify this argument to split a file or folder larger than 2 gigabytes and distribute it.

If the packaging target is a folder, the maximum size of the entire folder that can be packaged is 127 GB. The maximum file size in the folder is 127GB.

If the packaging target is a file, the maximum file size that can be packaged is 255 GB.

/tempdir

Specify the name of the temporary-file output folder, which is used when a file or folder larger than 2 gigabytes is split and distributed.

/splitfilesize

Specify the size of pieces into which a file larger than 2 gigabytes is split, in bytes. The possible values range from 1,024 to 1,073,741,824. When the argument is omitted, it is set to 1,073,741,824 (1 gigabyte).

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file and the command arguments corresponding to them.

Table 14‒8: Correspondence between parameter file contents and command arguments (dcmpack command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

PACKAGING_SOURCE

file_path

Name of packaging-target file

Y/N

/P value

base_fullpath

Path name of packaging base directory

Y

/B value

PACKAGING_INFORMATION

package_name

Package name

Y

/p value

package_id

Package ID

Y

/I value

version_revision

Version/revision

Y

/v value

generation

Generation number

Y

/G value

cabinet_name

Cabinet name

Y

/c value

cabinet_id

Cabinet ID

Y

/C value

package_code

Code type

N

--

SYSTEM_CONDITIONS

directory

Installation-target directory

Y/N

/D value

condition

System condition

Y/N#1, #2

/O value

SOFTWARE_CONDITIONS

condition

Package condition

Y/N#1, #2

/l value

INSTALLSOFTWARE_CONDITIONS

condition

Software condition

Y/N#3

--

FILE_PROPERTIES

permission

Restoration of file access permission

Y/N

/qY or /qN#4

SCHEDULE

expiration_date

Expiration date of package storage on relay computer

Y/N

/x value

expiration_days

The relay computer holds relayed packages for

Y/N

/ed value

installation_date_and_time

Installation date and time

Y/N

/d value

installation_timing

Execution timing

Y/N

/tS or /tN

INSTALLATION_METHOD

installation_mode

Installation mode

Y/N

/mB or /mG

OPTION

compress

Whether to compress

Y/N

/uY or /uN

compress_type

Compression mode

Y/N

/ctN or /ctH#5

restore

Whether to restore at upgrading

Y/N

/RY or /RN

reboot

Computer restart after installation

Y/N

/reboot

processing_dialog

Whether to display processing message during installation

Y/N#2

/procS, /procY, or /procN

priority

Priority

Y/N

/priority value

USER_PROGRAM_INSTALLATION_CONDITIONS

external_program_executed_before_installation#6

External program to be started before installation

Y/N

/b value

external_program_executed_after_installation

External program to be started after installation

Y/N

/a value

external_program_error_handler#7

External program to be started at installation error

Y/N

/e value

external_program_handler

External program to be started

N

--

exit#7

How to report the processing result of external program

Y/N

/rbR, /rbM, /raR, /raM, /reR, or /reM

action#7

Action to take when processing result is error

Y/N

/ybC, /ybS, /yaC, or /yaS

wait#7

Monitoring method

Y/N

/wbU, /wbT, /wbG, /waU, /waT, /waG, /weU, or /weY

timeout

Monitoring time

Y/N#8

/n value

wait_code

Monitoring code

N

--

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

If multiple sets of system condition and package condition are specified, the package is installed when all the system conditions are met and at least one of the package conditions is met. When using command arguments to specify system and package conditions, you can specify a total of 10 arguments /O and /l.

#2

You cannot specify this parameter for packages to be distributed to UNIX computers.

#3

If multiple software conditions are specified, the package is installed when at least one of the specified conditions is met.

#4

Specify /qN for packages to be distributed to UNIX computers.

#5

Specify /ctN for packages to be distributed to UNIX computers.

#6

For packages to be distributed to UNIX computers, this parameter is ignored if you specify the installation_date_and_time parameter for the SCHEDULE tag at the same time.

#7

For packages to be distributed to UNIX computers, this parameter is ignored even if it is specified.

#8

When U is specified in the wait parameter (or when /wbU, /waU, or /weU is specified as a command argument), the timeout parameter is ignored even if specified.

Command format without using any parameter file

The following shows the command format to be used when you specify only command arguments without using a parameter file:

dcmpack.exe /k password
            [/P name-of-packaging-target-file]
             /B path-name-of-packaging-base-directory
             /p package-name /I package-ID
             /v version/revision /G generation-number
             /c cabinet-name /C cabinet-ID
            [/D installation-target-directory]
            [/O system-condition] [/l package-condition]
            [{/qY|/qN}] [/x expiration-date-of-package-storage-on-relay-computer]
            [/ed the-relay-computer-holds-relayed-packages-for]
            [/d installation-date-and-time] [{/tS|/tN}] [{/mB|/mG}]
            [{/uY|/uN}] [{/ctH|/ctN}] [{/RY|/RN}]
            [/reboot] [{/procS|/procY|/procN}]
            [/b external-program-to-be-started-before-installation [{/rbR|/rbM}]
            [{/ybC|/ybS}] [{/wbU|/wbT|/wbG}] [/n monitoring-time]]
            [/a external-program-to-be-started-after-installation [{/raR|/raM}]
            [{/yaC|/yaS}] [{/waU|/waT|/waG}] [/n monitoring-time]]
            [/e external-program-to-be-started-at-installation-error
            [{/reR|/reM}] [{/weU|/weY}] [/n monitoring-time]]
            [/o output-file-name]
            [/split /tempdir temporary-folder-name [/splitfilesize size-of-files-after-split]]

Return codes

The following table lists the return codes that are output when the dcmpack command is executed:

Code

Meaning

Action to be taken

0

The command ended normally.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in a command argument or the parameter file.

Check the values specified in command arguments and the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file could not be created, or automatic incrementing of the version/revision and generation numbers for which reserved words were used failed. The package, however, was registered successfully.

Check the specified path names of the files to be packaged.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

6

Data communication with the managing server failed.

Check the communication environment.

7

This code means one of the following:

No packaging-target file or directory was found.

Number of packaging-target files or directories exceeded the maximum limit.

Check the specified path names of the files or directories to be packaged.

Reduce the number of the files or directories to be packaged.

9

The packaging-target file has already been packaged.

Change the value of one of the following parameters, and then retry packaging.

Cabinet ID

Package ID

Version number

Generation number

12

Restoration of one or more archive files failed.

Reference the event log.

13

The password is invalid.

Check the specified password.

14

Package registration failed because incrementing of the version/revision or generation number exceeded the maximum allowable number of digits.

Check the settings of reserved words for version/revision and generation numbers.

32

An error occurred when the split file was output.

Check the existence of the folder specified by the /tempdir argument, the access permissions to that folder, and the free space of the folder.

Notes

Specification of the cabinet

If you specify an undefined cabinet ID in the parameter file or corresponding command argument, a new cabinet is created.

If you specify different combinations of cabinet ID and cabinet name for installation of multiple packages, the second and subsequent packages are stored in the cabinet indicated by the cabinet ID in the respective combinations. Such a specification does not cause an error.

Specifiable number of packages

When using either the parameter file or command arguments for specification, you can specify only one package per single execution of the dcmpack command.

Automatic incrementing of version/revision and generation numbers

You can automatically increment the version/revision and generation numbers by using reserved words. The incrementing operation varies as described below depending on whether reserved words are specified in the parameter file or they are specified in command arguments.

When reserved words are specified in the parameter file:

The initial values for incrementing are updated when the dcmpack command is executed, and the new values are written to the parameter file by overwriting. The next time the command is executed by using the same parameter file, incrementing begins with the new values.

When reserved words are specified in command arguments:

The initial values for incrementing are not updated even when the dcmpack command is executed. Each time the command is executed, incrementing begins with the initial values.

Connection destination of the dcmpack command

The connection destination of the dcmpack command is the server that is connected when you start the Packager as a user who has permission to update the registry HKEY_LOCAL_MACHINE. If you want to change the connection destination, start the Packager as a user who has permission to update the registry HKEY_LOCAL_MACHINE, change the connection destination, and then execute the dcmpack command.

Point to be noted when you do not use a parameter file

Do not specify a path name that includes a space for an external program.

If the distribution destination is a workstation (UNIX system), specify any drive as the drive of the directory where external programs are to be stored or installed. However, the specified drive will be ignored during distribution, and external programs will be distributed according to the specified directory. In the following example, the drive name c: is ignored.

Example: c:/user/tmp

When you use a backslash (\) to separate each directory, there is no need to specify a drive name.

Example: \user\tmp

Point to be noted when you have newly installed the Packager

When you have newly installed the Packager, before executing the dcmpack command, start the Packager and specify the server to be used

Point to be noted on the background installation mode

When the background installation mode is used, do not specify a network drive as the installation-target directory.

Point to be noted when /split is specified

Before executing the dcmpack command, check that the folder you specify in the /tempdir argument has more free space than the size of the file before split.

When you execute the dcmpack command, the folder below is created as a temporary file area. Do not delete this folder during command execution.

temporary-folder-specified-in-the-tempdir-argument\process-ID#

#: Process ID of the dcmpack command.

The temporary file area is deleted automatically after the command ends.

A file can be split into 255 pieces maximum. We recommend that you create a new cabinet for registering split files as a package.

If the number of split files exceeds the maximum number, an error indicated by the return code 12 occurs.

Note that if the cabinet you are going to register the package with already has some packages, the maximum number of split files decreases by the number of the registered packages.

Specify the package name within 46 single-byte characters (23 double-byte characters). And specify the package ID between 1 and 40 characters.

If the dcmpack command abnormally terminates with one of the return codes 3 to 14, or with 32, follow the procedure below to delete the temporary files and the package, and then re-execute the dcmpack command.

Deleting the temporary files:

Delete the files that remain under the folder specified in the /tempdir argument.

Deleting the package:

Delete the packages with the package name of package-specified-by-the-/p-value-argument-or-package_name-in-the-parameter-file.serial-number that are registered with the cabinet specified in the parameter file or the command argument. For details about how to delete the package, see 7.4.5 Deleting cabinets and packages or 14.12 dcmpkrm.exe (deleting a package).

The version/revision and generation number of the package to be registered are not incremented automatically. When \increment-value[:start-value] is specified for the /v argument, /G argument, or version_revision and generation in the parameter file with the /split argument specified, the value specified in:start-value is used. If :start-value is omitted, 0 is used.

More than one package with a sequence number starting from 001 added to each package is registered with the package name (package_name parameter in the parameter file or /p value command argument) and package ID (packageid parameter in the parameter file or /I value command argument). The following table lists the installation of which package in the value specified in the parameter file or command argument is followed by the operation:

Parameter

Applicable argument

Operational timing

external_program_executed_before_installation

/b

An external program is executed after the first package of the split packages is installed.

external_program_executed_after_installation

/a

An external program is executed after the last package of the split packages is installed.

external_program_error_handler

/e

An external program is executed when errors occurred during the installation of all the split packages.

reboot

/reboot

The restart is executed after the last package of the split packages is installed.

Note that when the installation script is packaged and distributed after distribution, as described in 7.6.14 (2) Example of distributing a large Windows 10 update, use the installation script for restart, without using the reboot parameter in the parameter file or /reboot command argument.

If you want to use the installation script for restart, do not set the Monitoring time to 0 (not monitored).

The setting to indicate whether to restore at upgrading (the restore parameter in the parameter file or the /R command argument) is disabled. Even if you specify Y to restore parameter or /RY in the command argument, a program product or software is not restored when it is upgraded.

Example

The following example shows use of this command to package the files stored under the directory C:\Finance\data0401, by using the package name and cabinet name described below.

Package name

Finance Data 2003 4

Name of the storage-destination cabinet

FCAB01

Creating the parameter file

Create the following parameter file:

** dcmpack Parameter File Sample

PACKAGING_SOURCE{
file_path=FD200304.dat
base_fullpath= C:\Finance\data0401
}
PACKAGING_INFORMATION
{
package_name=Finance Data 2003 4
package_id=FD200304
version_revision=000001
generation=0000
cabinet_name=FCAB01
cabinet_id=F1
package_code=P
}
SYSTEM_CONDITIONS{
condition=H:c>=300
directory=C:\Finance
}
USER_PROGRAM_INSTALLATION_CONDITIONS
{
external_program_executed_after_installation = C:\Dmbat\app\normal_exit.exe
}

Executing the command

When the created parameter file is stored as C:\Dmbat\para.txt, specify the command as follows:

dcmpack.exe /i C:\Dmbat\para.txt

14.10 dcmpkget.exe (making a backup of a package)

This section describes the dcmpkget command, which makes a backup of a package.

Function

This command makes a backup of a specified package.

Format

dcmpkget.exe /i parameter-file /o output-destination-directory
             [/of output-file-name]

Arguments

/i

In the argument /i, specify the full path name of the parameter file.

You can also use the output file output by the dcmpack command as the parameter file. Note, however, that the package_name parameter in the PACKAGING_INFORMATION tag is ignored.

/o

In the argument /o, specify the full path name of the output-destination directory. If the specified directory is not found, the directory is created automatically. You cannot specify a network drive as the output-destination directory.

/of

In the argument /of, specify the name of the file to be created in the output-destination directory. The default of the file name is dcmpkget. A backup file name is created by adding a string of package attributes (cabinet ID, package ID, version number, and generation number) to the file name specified in this argument. The backup file name has an extension of .dpf, .pkg, .sci, or .xml. If the version number includes the character /, the character is replaced with $ in the backup file name.

You can specify a backup file name that has a maximum of 256 single-byte characters (or 128 double-byte characters). The final backup file name with the string of package attributes added might exceed the maximum number of characters. If this occurs, the backup file name you specified is shortened so that the final backup file name does not exceed the maximum number of characters.

For the argument /of, you can use reserved words, such as \CY, \CM, \CD, \CH, \CN, \CS, \VERSION, and \PKGID. When \VERSION or \PKGID is specified in the argument /of, the dcmpack command references the corresponding value in the definition of the package specified first, or ignores the reserved word if the definition is not found. For details about reserved words, see 14.21 How to specify reserved words.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The table below shows the specification contents of the parameter file and the command arguments corresponding to them.

If a specification item is specified in both a parameter file and a command argument, only the specification in the command argument is effective (the specification in the parameter file is ignored). Note, however, that, if you specify only some of the package attributes by using command attributes, only the first package information specified under the PACKAGING_INFORMATION tag in the parameter file is effective.

Table 14‒9: Correspondence between parameter file contents and command arguments (dcmpkget command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

PACKAGING_INFORMATION#1

package_name

Package name

N

--

package_id

Package ID

Y#2

/I value

version_revision

Version/revision

Y#2

/v value

generation

Generation number

Y#2

/G value

cabinet_name

Cabinet name

N

--

cabinet_id

Cabinet ID

Y

/C value

package_code

Code type

Y/N

/KW or /KP

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

For this command, you cannot use a reserved word for any parameter in the PACKAGING_INFORMATION tag.

#2

You can omit this parameter when you intend to specify only a cabinet ID. When only a cabinet ID is specified, this command backs up all the packages in the specified cabinet.

Command format without using any parameter file

The following shows the command format to be used when you specify only command arguments without using a parameter file.

dcmpkget.exe /I package-ID /v version/revision /G generation-number
             /C cabinet-ID [/KW|/KP] /o output-destination-directory
             [/of output-file-name]

Return codes

The following table lists the return codes that are output when the dcmpkget command is executed:

Code

Meaning

Action to be taken

0

The backup file was output successfully.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the path name and specification format of the parameter file.

2

An invalid value was specified in a command argument or the parameter file.

Check the values specified in command arguments and the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The specified package was not found.

Check whether the specified package exists on the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

14

The output file or output-destination directory could not be created.

Check the path names of the output-destination directory and output file.

Notes

If a specified package is not found when this command with multiple packages specified is executed, this command skips backing up of the unfound package, and then backs up other specified packages. When a specified package is not found, this command returns return code 4.

If backing up of a package fails during execution of this command with multiple packages specified, this command cancels backup processing. Then, this command deletes all the backup files it has created before canceling the backup processing, and returns a return code indicating an error.

If you back up a UNIX-version package that is created without a script file specified, no SCI file is output.

Example

The following example shows use of this command to create a backup of a package (stored in the cabinet with cabinet ID 01) whose package ID is 0100, version/revision is 0100, and generation number is 0000.

Creating the parameter file

Specify the package to be backed up and the cabinet containing the package as shown below, and then save the parameter file under any name.

** dcmpkget Parameter File Sample

PACKAGING_INFORMATION{
package_id=0100
version_revision=0100
generation=0000
cabinet_id=01
package_code=P
}

Executing the command

To store the created parameter file as C:\Dmbat\dcmpkget.txt and create a backup under C:\Dmbat\backup, specify the command as follows:

dcmpkget.exe /i C:\Dmbat\dcmpkget.txt /o C:\Dmbat\backup /of BackupFile

14.11 dcmpkput.exe (recovering a package by using a backup

This section describes the dcmpkput command, which recovers a package by using a backup. Note that this command does not use a parameter file.

Function

This command recovers a package by using a backup file, and stores the package in a specified cabinet.

Format

dcmpkput.exe [/C cabinet-ID] /i input-source-directory
             [/of input-file-name] [/f]

Arguments

/C

In the argument /C, specify the ID of the cabinet in which to store the package recovered by using a backup. If the specified cabinet is not found, the cabinet is created automatically. When no cabinet ID is specified, the package is stored in its original cabinet.

/i

In the argument /i, specify the full path name of the output-destination directory specified for the dcmpkget command. You cannot specify a network drive as the input-source directory.

/of

In the argument /of, specify the name of a backup file that has been created by the dcmpkget command. You can use a wildcard character (*) for the argument /of. When this argument is omitted, this command uses all the backup files whose name begins with dcmpkget.

When the directory specified in the argument /i contains multiple backup files, you can specify all the backup files under the directory as follows:

dcmpkput.exe /i C:\temp\pkg /of *

/f

When the argument /f is specified, if a package that is the same as the recovered package exists in the specified cabinet, this command overwrites the existing package with the recovered package. When the argument /f is omitted, this command does not overwrite the existing package, but returns the return code 5.

Return codes

The following table lists the return codes that are output when the dcmpkput command is executed:

Code

Meaning

Action to be taken

0

The package was recovered successfully.

None

1

The output file output by the dcmpkget command cannot be opened, or its file format is incorrect.

Check the path name and the file format of the output file.

2

An invalid value was specified in a command argument.

Check the values set in command arguments.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The specified backup file was not found.

Check the path name of the backup file.

5

The package already exists, or no more packages can be added to the cabinet.

Connection to the JP1/IT Desktop Management 2 service failed.

Check the names and number of the packages stored in the cabinet.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Notes

If package recovery fails during execution of this command with multiple packages specified, the dcmpkput command cancels package recovery processing. Then, this command returns a return code indicating an error.

When you restore a backup of a UNIX-version package, specify the restoration destination as an existing cabinet that was created by specifying UNIX for Cabinet type. You cannot restore backups of UNIX-version packages if existing cabinets were created by specifying Windows for Cabinet type or there are no existing cabinets.

Example

The following example shows use of this command to recover a package by using a backup file made by the dcmpkget command.

To recover packages by using all the backup files stored under C:\Dmbat\backup, and store them in the cabinet that has a cabinet ID of 01, specify the command as follows:

dcmpkput.exe /C 01 /i C:\Dmbat\backup /of *

14.12 dcmpkrm.exe (deleting a package)

This section describes the dcmpkrm command, which deletes a package.

Function

This command deletes a specified package from a specified cabinet in the managing server.

Format

dcmpkrm.exe /i parameter-file-name

Arguments

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can use also the output file output by the dcmpack command as the parameter file.

Specification contents of parameter file

The table below shows the specification contents of the parameter file for the dcmpkrm command. The contents of the parameter file for this command cannot be specified by using command arguments.

Table 14‒10: Specification contents of parameter file (dcmpkrm command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

PACKAGING_INFORMATION

package_name

Package name

N

--

package_id

Package ID

Y

--

version_revision

Version/revision

Y

--

generation

Generation number

Y

--

cabinet_name

Cabinet name

N

--

cabinet_id

Cabinet ID

Y

--

package_code

Code type

Y

--

Legend:

Y: The parameter must be specified.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

Note

For this command, you cannot use a reserved word for any parameter in the PACKAGING_INFORMATION tag.

Return codes

The following table lists the return codes that are output when the dcmpkrm command is executed:

Code

Meaning

Action to be taken

0

The command ended normally.

None

1

The parameter file was not found, or its file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

14.13 dcmrmgen.exe (deleting a job definition)

This section describes the dcmrmgen command, which deletes a job definition.

Function

This command deletes the job definition specified in the parameter file.

Format

dcmrmgen.exe /i parameter-file-name

Arguments

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can use also the output file output by the dcminst command (with /s specified) as the parameter file.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file, and their corresponding command arguments.

Table 14‒11: Correspondence between parameter file contents and command arguments (dcmrmgen command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator#1

Job name

Y#2

/j

jobno

Job number

N

--

job_folder

Path name of job storage folder

Y#2

/f

unsuspended

Whether to distribute during suspension

N

--

Legend:

Y: The parameter must be specified.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

When specifying multiple job names, separate them by a semicolon (;).

#2

In the parameter file, write one or both of the job_generator and job_folder parameters.

When both the job_generator and job_folder parameters are written, this command searches job definitions in the specified folder, and then deletes the job definition detected first.

When only the job_generator parameter is written, this command searches job definitions in the root folder. When only the job_folder parameter is written, this command deletes the folder (all the job definitions in the folder) specified in the job_folder parameter.

When using command arguments for specification, you must specify both the arguments /j and /f.

Command format without using any parameter file

The following shows the command format to be used when you specify only command arguments without using a parameter file:

dcmrmgen.exe /j job-name /f path-name-of-job-storage-folder

When specifying multiple job names in /j job-name separate them by a semicolon (;).

Always specify both /j job-name and /f path-name-of-job-storage-folder. Omitting either argument causes an error.

Return codes

The following table lists the return codes that are output when the dcmrmgen command is executed:

Code

Meaning

Action to be taken

0

The specified job was deleted, or the specified job was not found.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Note

You cannot delete all the job storage folders and job definitions together by this command by specifying only the root folder.

Example

The following example shows use of this command to delete the Collect-slip-file-0001 job stored in the batch-definition folder in the managing server.

Creating the parameter file

Specify the folder storing the job definition to be deleted and the name of the job as shown below in a parameter file, and then save the parameter file under any name.

** dcmjexe Parameter File Sample

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
job_folder= \batch-definition
}

Executing the command

When the created parameter file is stored as C:\Dmbat\dcmjexe.txt, specify the command as follows:

dcmrmgen.exe /i C:\Dmbat\dcmjexe.txt

14.14 dcmrtry.exe (re-executing a job)

This section describes the dcmrtry command, which re-executes a job.

Function

This command re-executes a job specified in the parameter file on the managing server.

Format

dcmrtry.exe [retry-key]
            /i parameter-file-name /o output-file-name

Arguments

retry-key

In this argument, specify the status of the job to be re-executed. Specify a retry key immediately after the command name. You can also specify retry keys, such as ERROR, WAIT, and PENDING, in any combination. When specifying multiple keys in a combination, separate them by a space. The default of the retry key is ERROR.

ERROR

Re-executes a job that has resulted in an error.

WAIT

Re-executes a job that is waiting for execution.

PENDING

Re-executes a job that has temporarily caused a communication error.

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can use also the output file output by the dcmcoll command (without /s specified), dcminst command (without /s specified), dcmjexe command, or dcmsusp command (without /s specified) as the parameter file.

/o

In the argument /o, specify the full path name of the output file. When this command ends normally, the data that is the same as the contents of the specified parameter file is output to the specified output file.

Specification contents of parameter file

The table below shows the specification contents of the parameter file for the dcmrtry command. The contents of the parameter file for this command cannot be specified by using command arguments.

Table 14‒12: Specification contents of parameter file (dcmrtry command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

N

--

jobno

Job number

Y

--

job_folder

Path name of job storage folder

N

--

unsuspended

Whether to distribute during suspension

N

--

Legend:

Y: The parameter must be specified.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

Return codes

The following table lists the return codes that are output when the dcmrtry command is executed:

Code

Meaning

Action to be taken

0

Re-execution of a job started.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file cannot be opened.

Check the specification of the output file.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Notes

In the parameter file, specify the job number that was output to the output file by the dcmcoll command (without /s specified), dcminst command (without /s specified), dcmjexe command, or dcmsusp command (without /s specified).

If the job number of the job to be re-executed is unknown, you cannot execute the dcmrtry command. In such a case, in the Job Status window of the managing server, re-execute the job that has the job name of the job to be deleted.

Example

The following example shows use of this command to re-execute those jobs executed by the dcminst command which have been waiting for execution or resulted in an error.

Creating the parameter file

Specify the job number output to the output file by the dcminst command in the parameter file as shown below.

If the output file output by the dcminst command has been stored, you can specify the stored file as the parameter file.

JOB_ATTRIBUTE{
job_generator= NETM_INSTALL_2003_12_11_13_34_36
jobno= JB03121113315383
job_folder= \
}

Executing the command

When the output file output by the dcminst command is stored as the file C:\Dmbat\out.txt, specify the command as follows:

dcmrtry.exe WAIT ERROR /i C:\Dmbat\out.txt /o C:\temp\retryout.txt

14.15 dcmstat.exe (acquiring job execution status)

This section describes the dcmstat command, which acquires the execution results of jobs.

Function

This command acquires (on the managing server) the status of the jobs specified in a parameter file. Job status is indicated by the return code output by this command.

Job execution status

Return code

All jobs have ended normally.

0

Some jobs have resulted in an error.

30

Jobs are being executed.

31

Jobs are being executed, and some jobs have resulted in an error.

32

Jobs are being deleted, and some jobs are waiting for the completion of deletion.

33

On the managing server of JP1/IT Desktop Management 2 - Manager, specify job execution status in this command to check the number of hosts that are in the specified job execution status. The number of hosts in the specified execution status is obtained by subtracting 10,000 from the value of the return code.

Format

dcmstat.exe [job-execution-status] /i parameter-file-name

Arguments

job-execution-status

In this argument, specify job execution status to check the number of hosts that are in the specified job execution status. Specify one or more values of job execution status among those listed below immediately after the command name. This command returns a return code of which the value is the sum of 10,000 and the total number of hosts in the specified job execution status.

The following table lists the specifiable values of job execution status:

Job execution status

Description

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 the agent 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 or for other reasons.

SUSPENDED

A suspension instruction was issued.

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, the hosts in the corresponding status are excluded from the total number of the hosts in the specified job execution status even when you specify this value.

When you do not specify any job execution status, this command checks the execution status of the job specified in the parameter file, and returns a return code (0 to 33) corresponding to the execution status.

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can use also the output file output by the dcmcoll command (without /s specified), dcminst command (without /s specified), dcmjexe command, or dcmsusp command (without /s specified) as the parameter file.

Specification contents of parameter file

The table below shows the specification contents of the parameter file for the dcmstat command. The contents of the parameter file for this command cannot be specified by using command arguments.

Table 14‒13: Specification contents of parameter file (dcmstat command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

N

--

jobno

Job number

Y

--

job_folder

Path name of job storage folder

Y/N#

--

unsuspended

Whether to distribute during suspension

N

--

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#

If this parameter is omitted, this command searches all the folders or files under the root folder to find the specified job, and then displays its execution status.

Return codes

The following table lists the return codes that are output when the dcmstat command is executed:

Code

Meaning

Action to be taken

0

All jobs have ended normally.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in the parameter file.

Check the values specified in the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

30

At least some jobs have resulted in an error.

None

31

Jobs are being executed, and no job error has been detected.

None

32

Jobs are being executed, and some jobs have resulted in an error.

None

33

Jobs are being deleted, and some jobs are waiting for the completion of deletion.

None

When you specify job execution status, this command returns a return code of which the value is the sum of 10,000 and the total number of hosts in the specified job execution status.

Notes

In the parameter file, specify the job number that was output to the output file by the dcmcoll command (without /s specified), dcminst command (without /s specified), dcmjexe command, or dcmsusp command (without /s specified).

If the job number of the job of which to acquire job status is unknown, you cannot execute the dcmstat command. In such cases, in the Job Status window of the managing server, check the status of the job that has the job name of the job of which to acquire job status.

Example

The following example shows use of this command to acquire the status of the Collect-slip-file-0001 job executed by the dcmjexe command.

Creating the parameter file

Specify the job number output to the output file by the dcmjexe command in the parameter file as shown below.

If the output file output by the dcmjexe command has been stored, you can specify the stored file as the parameter file.

** dcmjexe output -> dcmstat input

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
jobno= JB03121113315383
job_folder= \batch-definition
}

Executing the command

When the output file output by the dcmjexe command is stored as the file C:\Dmbat\out.txt, specify the command as follows:

dcmstat.exe /i C:\Dmbat\out.txt

You can use the dcmstat command to check the number of hosts that are in a specific status. For example, when you want to check the number of hosts that failed to start a job, or received a job suspension instruction, specify the command as follows:

dcmstat.exe CLT_NOTREADY SUSPENDED /i C:\Dmbat\out.txt

14.16 dcmstsw.exe (monitoring job execution status)

This section describes the dcmstsw command, which monitors the execution status of a job.

Function

This command monitors (on the managing server) the execution status of a job specified in a parameter file or on the command line, and starts a specified external program when the job enters specified execution status.

Format

dcmstsw.exe [monitoring-interval] [monitoring-condition] /i parameter-file-name

Arguments

monitoring-interval

In this argument, specify the interval of monitoring job execution status in seconds. The default monitoring interval is 900 seconds (15 minutes).

monitoring-condition

In this argument, specify the timing of starting a specified external program.

When ALL is specified, the external program is started when the job enters the specified execution status at all job destinations.

When this argument is omitted, the external program is started when the job enters the specified execution status at one or more job destinations.

/i

In the argument /i, specify the full path name of the parameter file to be used.

You can use also the output file output by the dcmcoll command (without /s specified), dcminst command (without /s specified), or dcmjexe command as the parameter file.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file available for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file, and their corresponding command arguments.

Table 14‒14: Correspondence between parameter file contents and command arguments (dcmstsw command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

N

--

jobno

Job number

Y

/jn value

job_folder

Path name of job storage folder

Y/N#1

/l value

unsuspended

Whether to distribute during suspension

N

--

USER_PROGRAM_INSTALLATION_CONDITIONS

external_program_executed_before_installation

External program to be started before installation (collection)

N

--

external_program_executed_after_installation

External program to be started after installation (collection)

N

--

external_program_error_handler

External program to be started at installation error

N

--

external_program_handler

External program to be started

Y

/ep value

exit

How to report the processing result of external program

N

--

action

Action to take when processing result is error

N

--

wait

Monitoring method

N

--

timeout

Maximum execution period

Y/N#2

/wt value

wait_code

Monitoring code

Y/N#3

/wc value

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

If this parameter is omitted, this command searches all the folders or files under the root folder to find the specified job, and then monitors the job's execution status

#2

Specify a value larger than the monitoring interval. The default maximum monitoring period is 86,400 seconds (1 day).

#3

Specify the job execution status or a maintenance code. For details about the value to be specified, see USER_PROGRAM_INSTALLATION_CONDITIONS (specifying external programs). When this parameter is omitted, the specified external program is started when a job execution error occurs.

Command format without using any parameter file

The following shows the command format to be used when you specify only command arguments without using a parameter file.

dcmstsw.exe [monitoring-interval] [monitoring-condition]
            /jn job-number [/l path-name-of-job-storage-folder]
            /ep external-program-to-be-started [/wt maximum-execution-period] [/wc monitoring-code]

Return codes

The following table lists the return codes that are output when the dcmstsw command is executed:

Code

Meaning

Action to be taken

0

The command ended normally.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value was specified in a command argument.

Check the values set in command arguments.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The specified external program is not found.

Check the path name of the external program.

5

The maximum execution period passed. The job has not ended.

Connection to the JP1/IT Desktop Management 2 service failed.

Check the execution status of the job.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Possible causes are a system error, a syntax error in a command argument, or rejection of processing.

Notes

In the parameter file, specify the job number that was output to the output file by the dcmcoll command (without /s specified), dcminst command (without /s specified), or dcmjexe command.

This command is terminated when one of the following conditions is met:

The external program is started.

The time specified as the maximum execution period has passed.

All the jobs being monitored end normally when a value other than NORMAL is specified as the monitoring code.

The job being monitored is deleted.

The managing server stops.

Do not specify ALL as the monitoring condition when an ID group job is specified as the job to be monitored. Specifying ALL as the monitoring condition causes an error (indicated by the return code 2).

Example

The following example shows use of this command to execute the external program C:\aaa.exe when all the jobs executed by the local managing server end normally. Assume that the monitoring interval is 5 minutes and the maximum execution period is 1 hour.

Creating the parameter file

Specify the job number output to the output file by the dcmjexe command in the parameter file as shown below.

If the output file output by the dcmjexe command has been stored, you can specify the stored file as the parameter file.

** dcmstsw Parameter File Sample

JOB_ATTRIBUTE{
job_generator= Collect-slip-file-0001
jobno= JB02100720481602
job_folder= \batch-definition
}

Executing the command

When the output file output by the dcmjexe command is stored as C:\DMbat\para\.txt, specify the command as follows:

dcmstsw.exe 300 ALL /i C:\DMbat\para.txt /ep C:\aaa.exe /wt 3600 /wc NORMAL

14.17 dcmsusp.exe (suspending and resuming file transfer)

This section describes the dcmsusp command, which suspends or resumes file transfer.

Function

This command connects to the managing server on the local host, and suspends or resumes file transfers between a specified relay system or management relay server and the systems directly under them. This command suspends or resumes also the file transfer between the connected managing server and the lower systems directly connected to the relay system.

Format

dcmsusp.exe [processing-key] [/s] /i parameter-file-1 [parameter-file-2]
            [/o output-file-name]

Arguments

processing-key

This argument specifies the type of processing to be executed. Specify one of the processing keys listed below immediately after the command name. When this argument is omitted, specification of NETM_SUSPEND is assumed.

NETM_SUSPEND

When the processing key is NETM_SUSPEND, this command executes a Suspend file transfer job to suspend file transfers between a specified relay system or management relay server and the systems directly under them. In a parameter file (or command argument), specify the job destination (an agent that is under a relay system or management relay server and has the same name as the relay system or management relay server).

NETM_RESUME

When the processing key is NETM_RESUME, this command executes a Resume file transfer job to resume file transfers between a specified relay system or management relay server and the systems directly under them. In a parameter file (or command argument), specify the job destination (an agent that is under a relay system or management relay server and has the same name as the relay system or management relay server).

NETM_MANSUSP

When the processing key is NETM_MANSUSP, this command suspends the file transfer between the connected managing server and the lower systems directly connected to the managing server. When this processing key is specified, all the arguments other than the processing key are ignored.

NETM_MANRESU

When the processing key is NETM_MANRESU, this command resumes the file transfer between the connected managing server and the lower systems directly connected to the managing server. When this processing key is specified, all the arguments other than the processing key are ignored.

/s

When the argument /s is specified, this command creates a job, and then stores it without execution. When the processing key is NETM_MANSUSP, or NETM_MANRESU, this argument is ignored even if specified.

When the parameters for job registration date and time, job execution date and time, and job expiration date are specified, this command stores also the specified schedule information.

/i

In the argument /i, specify one or two full path names of the parameter files to be used. When specifying two full path names, separate them by a space. Specifying three or more full path names causes this command to fail.

/o

In the argument /o, specify the full path name of the output file. Always specify this argument when the processing key is NETM_SUSPEND or NETM_RESUME. When the processing key is NETM_MANSUSP or NETM_MANRESU, this argument is ignored even if specified.

When this command ends normally with NETM_SUSPEND or NETM_RESUME specified as the processing key, the items listed below are output to the specified output file. If the output file already contains data, the data is overwritten.

Job name

Job number

Path name of job storage folder

When the argument /s is specified, the output file can be used as a parameter file for the dcmjexe command. When the argument /s is not specified, the output file can be used as a parameter file for the dcmjbrm, dcmrtry, and dcmstat commands.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file available for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file, and their corresponding command arguments.

Table 14‒15: Correspondence between parameter file contents and command arguments (dcmsusp command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

JOB_ATTRIBUTE

job_generator

Job name

Y/N#1

/j value

jobno

Job number

N

--

job_folder

Path name of job storage folder

Y/N

/l value

unsuspended

Whether to distribute during suspension

N

--

JOB_DESTINATION

group

Host group name

Y#2

/g value

host_name

Host name

Y#2

/h value

JOB_DESTINATION_ID

destination_id

ID name

Y#2

/X value

JOB_SCHEDULE

job_entry_date

Job registration date and time

Y/N

/jst value

job_execution_date

Job execution date and time

Y/N

/jsx value

job_expiration_date

Job expiration date

Y/N

/jsp value

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

When the job_generator parameter (or the argument /j) is omitted, "processing key and job execution date and time" is automatically set as the job name. Therefore, if multiple commands with the same processing key are executed concurrently, their job names might be duplicated, and their jobs might not be executed correctly. We recommend that, when executing multiple commands with the same processing key concurrently, you specify different job names for the commands by using job_generator (or /j).

#2

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag. Also, you cannot specify /g and /h together with /X. You must specify only either JOB_DESTINATION or JOB_DESTINATION_ID, or either /g and /h or /X. You can specify either the group parameter (/g) or host_name parameter (/h), or both.

Return codes

The following table lists the return codes that are output when the dcmsusp command is executed:

Code

Meaning

Action to be taken

0

The managing server started the job, or changed its own suspended status.

None

1

The parameter file cannot be opened, or the file format is incorrect.

Check the specification of the parameter file or its description format.

2

An invalid value is set in a command argument or the parameter file.

Check the values specified in command arguments and the parameter file.

3

Connection to the database failed.

Check database settings in the setup of the managing server.

4

The output file cannot be opened.

Check the specification of the output file.

5

Connection to the JP1/IT Desktop Management 2 service failed.

Check whether the service of JP1/IT Desktop Management 2 - Manager has started.

12

Restoration of one or more archive files failed.

Reference the event log.

Possible causes are a system error, a syntax error in a command argument, or rejection of processing because of specification (in the parameter file) of a value not defined in the connection-destination managing server.

Notes

When you specify the host_name parameter under the JOB_DESTINATION tag or the argument /h, note the following:

When a host name or IP address is specified in the host_name parameter or argument /h, the job is executed while assigning the specified host name or IP address to a host ID.

Assume that the node having the host name or IP address specified in the host_name parameter or argument /h does not exist in the system configuration. Then, the job is executed by using the specified destination name. In such a case, even when the job ends normally, you cannot check the suspended status of the destination node by Remote Install Manager or other tool because the destination node does not exist in the system configuration.

Assume that multiple nodes having the same host name or IP address specified in the host_name parameter or argument /h exist in the system configuration (multiple nodes of the same name with different host IDs exist). Then, the job is executed on all the relay systems or management relay servers corresponding to these nodes. When you want to execute the job only for some of the nodes of the same name, register the destinations for which to execute the job as a host group, and execute the job for the host group.

Note the following point when you specify the job_folder parameter under the JOB_ATTRIBUTE tag or the argument /1.

When you execute the dcmcoll command specifying the path name of a folder not defined in the Job Definition window as the path name of job storage folder, the specified folder is created. The created job storage folder remains without being deleted even after command execution. If you do not use the created folder, delete it after the job is complete.

When you execute a command, do not specify the same destination more than once. It will execute the same jobs at a destination for multiple times.

Notes on execution of the command

If you pause the command by pressing of the (Ctrl + C, or else) keys during the execution, the job definitions that the command has created might not be deleted.

If you pause the command, check the job definition window on the remote install manager and delete job definitions if necessary.

14.18 catAndValidatePackagingFile.exe (combining split files)

This section describes the catAndValidatePackagingFile command, which combines files that are split.

Function

This command combines files split by the dcmpack command into one file. If a folder is split, it checks if all the files in the folder exist.

Format

catAndValidatePackagingFile.exe /d name-of-the-folder-where-split-files-are-stored

Arguments

/d

Specify the full path, within 255 characters, to the folder where split files are stored.

If the folder name contains a single-byte space character, enclose the path in double quotation marks ("). The combined file is stored in the folder where the split files are stored. When the command ends, the split files are deleted automatically.

Return codes

The following table lists the return codes that are output when the catAndValidatePackagingFile command is executed:

Code

Meaning

Action to be taken

0

The command ended normally.

None

11

An error was found in an argument.

Check the value set in the argument.

21

No split files exist, or no read access permissions are assigned.

Check that the file for the package created by the dcmpack command exists in the folder where split files are stored.

If the file does not exist, re-execute the remote installation job for the applicable package.

32

An error occurred when the combined file was output.

Check the existence of the folder where split files are stored, the access permissions, and the free space of the folder.

33

An error occurred when the combined file was verified.

Re-execute the remote installation job.

150

The command execution was interrupted due to another error.

Collect maintenance data, and then contact the system administrator.

14.19 dcmcsvu.exe (exporting to a CSV-formatted file)

This section explains how to use the dcmcsvu command, which exports inventory information to a text file in CSV format or in the parameter file format.

Function

This command connects the managing server running on the local machine and exports the current inventory information to a text file in CSV format or in the parameter file format. In addition, the results of detecting hosts in which JP1/Software Distribution is not installed or the results of searching for hosts on the network can be output to CSV-formatted files. Note that you can output a CSV file in Unicode, in which case the only supported encoding is UTF-8.

The template by which inventory information can be output is the same as the template used in the CSV output utility Information is output for the items included in the specified template (the columns in the template). If you use a parameter file to specify this command, you can set details about the output items or filter the output information. For output of information on hosts on which JP1/Software Distribution is not installed, host information that is specified as outside the range of detection cannot be output.

Format

dcmcsvu.exe /i parameter-file-name /o result-output-file-name

Arguments

/i

In parameter-file-name, specify the full pathname of the parameter file.

/o

In result-output-file-name, specify the full pathname of the result output file. If you do not specify a full pathname, the result output file is created in the current directory.

Correspondence between the specification contents of parameter file and command arguments

You can also use command arguments to specify the template used for exporting and output file format instead of specifying these parameters in a parameter file. The table below shows the correspondence between the contents of aparameter file and the command arguments.

Table 14‒16: 6Correspondence between parameter file contents and command arguments (dcmcsvu command)

Specification content of parameter file

Content

Whether to specify

Command argument

Tag

Parameter

OUTPUT_CONSTRAINTS

template

Template used for exporting

Y

template-key

format

Output file format

Y/N#1

/par or /csv

group_membership

Membership group

Y/N

--

row

Item (row) you

want to output

Y/N#2

--

condition

Comparison condition

Y/N

--

Legend:

Y: The parameter must be specified.

Y/N: The parameter can be omitted.

N: The parameter is not necessary (is ignored even when specified).

--: The content cannot be specified by using a command argument.

#1

The default is to output the inventory information to a file in CSV format.

#2

The row parameter takes effect only when you export inventory information to a file in CSV format. If you specify the row parameter when exporting to a file in the parameter file format, the row parameter is ignored.

Command format without using any parameter file

The following shows the format of the command when you specify the command by using arguments only instead of using a parameter file.

dcmcsvu.exe template-key [/par|/csv] /o result-output-file-name

For details about available template keys, see Table 14-23 Export file formats and templates that can be specified in 14.20.14 OUTPUT_CONSTRAINTS (specifying the output information). The items that you can output with each template are the same as those you output with the CSV output utility. For details about the items that are output, see 11.1.1 Items eligible for output to a CSV-formatted file in the manual Administrator's Guide Volume 1.

With respect to the output file format, specify format=par (or csv) for a parameter file. Note however, that you must specify dcmcsvu.exe /par (or /csv), in which a slash (/) is inserted at the beginning for the command argument.

When you use command arguments instead of using a parameter file, you cannot specify details of the output items or filter the output information.

Return codes

The following table lists the return codes that are output when the dcmcsvu command is executed:

Code

Meaning

Action to be taken

0

The file output was successfully completed.

None

1

The command cannot open the specified parameter file or the format of the specified parameter file is incorrect.

Check the pathname or format of the parameter file.

2

An invalid value is specified in a command argument or in the parameter file.

Check the values of command arguments or the values of the parameters in the parameter file.

3

An error occurred during connection or access to the managing server.

Check that the managing server and database server are running and that their settings are correct.

4

The results output file cannot be opened.

Check the status of the results output file, because it may have been opened by another application or there may be insufficient space for the file.

5

The operating environment is incorrect.

Ensure that the operating environment settings for the managing server or database server are correct.

10

The command could not output the information because the number of rows to be written to the parameter file exceeded the maximum when /par was specified.

Check the information that will be output and reduce the number of rows to be output.

11

The information to be written to the output file does not exist, so the command did not create the output file.

None.

12

Other errors occurred.

Check the event log.

Example 1

The following is an example in which the execution status of a job is waiting for installing/ collecting, and in which the job execution status for a host whose job destination name is dmp4* is output to the JOB_DESTINATION tag using the parameter file format:

Creating a parameter file

Create the following parameter file and save it with any name:

OUTPUT_CONSTRAINTS{
template = J_STAT
condition = result=Waiting for installing/collecting AND dstname = dmp4* ;
}

Executing the command

When you created the parameter file with the name C:\temp\in.txt and you want to export the result to the C:\temp\parmjob.txt file, specify the following command:

dcmcsvu.exe /i C:\temp\in.txt /o C:\temp\parmjob.txt /par

Checking the result output file

After the command terminates normally, the result is output to the JOB_DESTINATION tag in the C:\temp\parmjob.txt file in the parameter file format:

JOB_DESTINATION{
host_name = dmp410; dmp4200; dmp4system
}

Example 2

The following is an example in which the execution status of a transferred job is waiting for installing/collecting and in which job name, job execution date/time at the server, and job destination name on a host whose job destination name is dmp4* are output to a CSV-formatted file. In this example, the status item, instead of the job status item, is used to refine the specification of the job execution status.

Creating a parameter file

Create the following parameter file and save it with any name:

OUTPUT_CONSTRAINTS{
template = J_STAT
row = jname; execdate; dstname
condition = status=2000B0 AND dstname = dmp4*;
}

Executing the command

When you created the parameter file with the name C:\temp\in.txt and you want to export the result to the C:\temp\jobout.csv file, specify the following command:

dcmcsvu.exe /i C:\temp\in.txt /csv /o C:\temp\jobout.csv

Example 3

The following is an example in which installed package information on the following host is output to a CSV-formatted file: a host on which a package with a package name *OFFICE and whose first-digit value of the latest version is 6 or less is installed.

Creating a parameter file

Create the following parameter file and save it with any name:

OUTPUT_CONSTRAINTS{
template = INSTLD_PKG
condition = pname = *OFFICE;
condition = newver < 6;
}

Executing the command

When you created the parameter file with the name C:\temp\in.txt and you want to export the result to the C:\temp\inspack.csv, specify the following command:

dcmcsvu.exe /i C:\temp\in.txt /csv /o C:\temp\inspack.csv

14.20 Creating a parameter file

A parameter file is used to specify the information (about, for example, the package to be distributed and the distribution destination) required to execute a command. The information is called a tag. In a parameter file, you must write the tags required by the type of command to be executed.

14.20.1 Types of tags

The following table shows the types of tags and the specification contents of the tags.

Table 14‒17: Types of tags

No.

Tag

Content

1

FILE_COLLECTION

Specifies the file to be remotely collected.

2

FILE_PROPERTIES

Specifies whether to restore the file access permission.

3

INSTALLATION_METHOD

Specifies the installation mode.

4

JOB_ATTRIBUTE

Sets job attributes.

5

JOB_CLIENT_CONTROL

Specifies client control.

6

JOB_DESTINATION

Specifies the job destination (a host or host group).

7

JOB_DESTINATION_ID

Specifies the job destination (ID).

8

JOB_SCHEDULE

Specifies the job schedule.

9

JOB_SPLIT_DELIVERY

Specifies the split distribution of a package.

10

OPTION

Specifies options.

11

OUTPUT_CONSTRAINTS

Specifies the output information

12

PACKAGING_INFORMATION

Sets package attribute information.

13

PACKAGING_SOURCE

Specifies the file to be packaged.

14

SCHEDULE

Specifies the schedule of remote installation or remote collection.

15

SOFTWARE_CONDITIONS

Specifies a package condition.

16

INSTALLSOFTWARE_CONDITIONS

Specifies a software condition.

17

SYSTEM_CONDITIONS

Specifies a system condition.

18

USER_PROGRAM_INSTALLATION_CONDITIONS

Specifies external programs.

14.20.2 Format of parameter file

You can write multiple tags in a parameter file. The following figure shows the format of the parameter file.

Figure 14‒5: Format of parameter file

A tag consists of multiple statements. A statement consists of a parameter indicating setting information written on the left side, and a corresponding setting written on the right side.

Rules and notes on creating a parameter file are as follows:

Only one statement can be written on a line.

One statement must not be written over multiple lines.

Characters { and } are handled as data-separating characters, and, therefore, must not be used for other purposes.

One line must not exceed 4,096 bytes.

A comment must begin with an asterisk (*). Null lines and lines containing only comments are ignored.

A tag name must consist of uppercase alphabetic characters and underscore (_). A parameter name must consist of lowercase alphabetic characters and underscore (_).

Necessary tags can be written in random order in a parameter file. Note, however, that writing two or more tags of the same name in a parameter file causes a file format error (indicated by the return code 1).

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag.

Only Shift-JIS character encoding is supported. If characters other than the Shift-JIS range are used, they might be garbled.

14.20.3 How to specify tags

The following subsections describe how to specify tags in a parameter file.

Note that the dcmcoll, dcminst, dcmpack, dcmpkget, dcmrmgen, dcmstsw, and dcmsusp commands allow you to specify the contents of a parameter file also by using command arguments. The following subsections also show the correspondence between parameters and command arguments. Most rules on specifying command arguments and their settings are the same as those on specifying parameters and their settings, except some rules unique to the specification using command arguments. For the input rules unique to command arguments, see 14.2.4 Command input format.

You can specify reserved words in parameters and command arguments. For details about how to specify reserved words, see 14.21 How to specify reserved words.

14.20.4 FILE_COLLECTION (specifying the file to be collected)

In the FILE_COLLECTION tag, specify the file to be collected and the directory to store collected files. This tag is used for the dcmcoll command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

source_path

Name of file to be collected

/y name-of-file-to-be-collected

dmz_path

Storage folder for collected file

/z storage-folder-for-collected-file

unarc_path

Storage folder for unarchived file

/r storage-folder-for-unarchived-file

(1) Format

FILE_COLLECTION{
source_path=file-or-folder-to-be-collected
dmz_path=storage-folder-for-collected-file
unarc_path=storage-folder-for-unarchived-file
}

(2) Description

source_path=file-or-folder-to-be-collected

Specify the full path name of the file or folder to be collected. The full path name must not exceed 256 bytes.

When specifying multiple files or folders, separate their path names by a semicolon (;), or write multiple source_path parameters. You can specify a maximum of 100 files or folders in a source_path parameter.

The value specified in this statement can include a space. Entering a space before or after a separator (;), however, causes an error (indicated by the return code 2). Also, do not enclose a specified value in double quotation marks (""). Note that, when you use a command argument for specification, a value that includes a space must be enclosed in double quotation marks ("").

dmz_path=storage-folder-for-collected-file

When collecting a file (when the processing key NETM_COLLECT is specified in the dcmcoll command), specify the full path name of the folder to store the collected file or folder. Only one path name can be specified. Specify the storage folder so that the path name of the collected file will not exceed 259 bytes. For how to set the storage destination of the collected file, see 9.1.1(2) Setting up the Collect File page.

When unarchiving an archive file (when the processing key NETM_UNARC is specified in the dcmcoll command), specify the full path name of the archive file (with the extension dmz) to be unarchived or the folder storing the archive file. The full path name must not exceed 256 bytes. In this case, you can specify multiple files or folders by separating their path names by a semicolon (;) or writing multiple dmz_path parameters.

unarc_path=storage-folder-for-unarchived-file

When unarchiving an archive file (when the processing key NETM_UNARC is specified in the dcmcoll command), specify the path name (path from the drive) of the folder to store the unarchived file or folder. Only one path name can be specified. Specify the storage folder so that the path name of the unarchived file will not exceed 259 bytes. For how to set the storage destination of the unarchived file, see 9.1.2 Restoring collected files.

14.20.5 FILE_PROPERTIES (restoring the file access permission)

In the FILE_PROPERTIES tag, specify whether to restore the permissions to access remotely installed files or directories. This tag is used for the dsmpack command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

permission

Whether to restore the file access permission

/qY or /qN

(1) Format

FILE_PROPERTIES{
permission=whether-to-restore-file-access-permission
}

(2) Description

permission=whether-to-restore-file-access-permission

Specify one of the following two values to indicate whether to restore the permission to access the installed file or directory.

S

Restores the access permission for the directory on the packager for the installation directory.

T

Does not restore the access permission. Files are created according to the access permission for the installation directory.

When using a command argument for specification, write Y or Y/N immediately after /q. The default is Y (restoring the access permission). When distributing files to UNIX computers, specify N (not restoring the access permission).

14.20.6 INSTALLATION_METHOD (specifying the installation mode)

In the INSTALLATION_METHOD tag, specify the installation mode.

This tag is used for the dcmpack command. The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

installation_mode

Installation mode

/mB or /mG

(1) Format

INSTALLATION_METHOD{
installation_mode=installation-mode
}

(2) Description

installation_mode=installation-mode

Specify the installation mode for package installation. When using a command argument for specification, write G or B immediately after /m. The default is B (background installation mode).

G (GUI installation mode)

Sets the installation mode in which a special installer (for example, an interactive installer) is used. Even if the installer does not have a GUI, use this installation mode when you use a graphic device interface (API).

B (background installation mode)

Sets the installation mode in which no special installer is used. Use this installation mode when installation can be performed simply by copying files. In this installation mode, even if the user who installed the agent has not logged in to the local computer, remote installation is executed if Windows has started.

14.20.7 JOB_ATTRIBUTE (setting job attributes)

In the JOB_ATTRIBUTE tag, specify the job attributes of a specified job. This tag is used for the dcmcoll, dcminst, dcmjbrm, dcmjexe, dcmrmgen, dcmrtry, dcmstat, dcmstsw, and dcmsusp commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

job_generator

Job name

/j job-name

jobno

Job number

/jn job-number

job_folder

Path name of job storage folder

/l path-name-of-job-storage-folder

unsuspended

Whether to distribute during suspension

/uns whether-to-distribute-during-suspension

(1) Format

JOB_ATTRIBUTE{
job_generator=job-name
jobno=job-number
job_folder=path-name-of-job-storage-folder
unsuspended=whether-to-distribute-during-suspension
}

(2) Description

job_generator=job-name

Specify the name of a job defined in the managing server. When no value is specified, a string consisting of processing-key and execution-date-and-time (processing-key is the one specified in the dcmcoll, dcminst, or dcmsusp command) is assumed as the job name.

For the dcmjexe command, always specify this parameter.

jobno=job-number

Specify the job ID automatically assigned to the job by the managing server.

job_folder=path-name-of-job-storage-folder

Specify the path name of a folder in the managing server. The folder name must begin with the character \., which indicates that the folder is a root folder. If the path name of the folder has a hierarchical structure, separate the hierarchical levels by \. You can specify a path name of a maximum of four hierarchical levels.

The following shows an example of specifying a folder name:

job_folder=\folder1\folder2\folder3\folder

When this parameter is omitted, the command searches job names in the root folder and subordinate folders in this order to find the specified job name, and then assumes the job found first as the processing target. If different folders contain a job of the same name, specify the path name of the folder that contains the target job.

Note that, when using multiple parameter files for the dcmcoll or dcminst command, specify this parameter so that the same folder name is not included in different parameter files. For example, avoid specifying this parameter as shown below.

Specification in parameter file A

job_folder=\folder1\folder2\folder3

Specification in parameter file B

job_folder=\folder1\folder2

unsuspended=whether-to-distribute-during-suspension

Write Y or N to specify whether to distribute the package even while file transfer is suspended.

Y

Distributes the package even while file transfer is suspended.

N

Suspends distribution while file transfer is suspended.

When no value is specified in this parameter, N is set automatically.

Note that you can specify this parameter only for the dcminst command. Specifying this command in a parameter list for other than the dcminst command causes an error.

(3) Specifiable reserved words

The reserved words that can be specified in this tag vary depending on the command as described below.

Reserved words that can be specified for the dcmcoll command

\CY, \CM, \CD, \CH, \CN, \CS, \HOST, \GROUP, \ZDIR

Reserved words that can be specified for the dcminst command

\CY, \CM, \CD, \CH, \CN, \CS, \VERSION, \HOST, \GROUP, \DSTID, \PKGID

Reserved words that can be specified for the dcmsusp command

\CY, \CM, \CD, \CH, \CN, \CS, \HOST, \GROUP, \DSTID

14.20.8 JOB_CLIENT_CONTROL (specifying client control)

In the JOB_CLIENT_CONTROL tag, specify how to control the client. This tag is used only for the dcminst command. Even if this tag is specified for other commands, this tag is ignored.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

client_wake_up

Whether to start the client

/WWU

client_shutdown

Whether to shut down the client

/WUS

(1) Format

JOB_CLIENT_CONTROL {
client_wake_up=whether-to-start-the-client
client_shutdown=whether-to-shut-down-the-client
}

(2) Description

client_wake_up=whether-to-start-the-client

Write Y or N to specify whether to start the client.

Y

Starts the client.

N

Does not start the client.

When no value is specified in this parameter, N is set automatically.

client_shutdown=whether-to-shut-down-the-client

Write Y or N to specify whether to shut down the client.

Y

Shuts down the client.

N

Does not shut down the client.

When no value is specified in this parameter, N is set automatically. Note that this parameter is invalid for agents for UNIX.

14.20.9 JOB_DESTINATION (specifying the job destination)

In the JOB_DESTINATION tag, specify the destination of a job. This tag is used for the dcmcoll, dcminst, and dcmsusp commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

group

Host group name

/g host-group-name

host_name

Host name

/h host-name

(1) Format

JOB_DESTINATION{
group=host-group-name
host_name=host-name
}

(2) Description

group=host-group-name

Specify a host group name defined in the managing server by using a path from the root directory. The following shows an example of specifying a host group name:

group=\group1\group2\group

When specifying multiple host group names, separate them by a semicolon (;). You can specify multiple host group names also by writing group= on multiple lines. You can add host group names until the total number of host group names and host names specified in the group and host_name parameters reaches 200.

host_name=host-name

Specify the host name of the managed computer defined in the managing server. To specify a host, use the path to the corresponding managed computer or the host ID of the host in place of the host name.

When specifying the destination as the path to a target computer, begin the path name with a backslash (\) and separate the names of relay systems or management relay servers with \ as follows:

host_name=\Submanager1\host1

When specifying the path to a destination for a job specifying a relay system or management relay server as the destination, specify the name of the relay system or management relay server as both the path and the destination as follows:

host_name=\Submanager1\Submanager1

When specifying multiple host names, separate them by a semicolon (;). You can specify multiple host group names also by writing host_name= on multiple lines. You can add host names until the total number of host group names and host names specified in the group and host_name parameters reaches 200.

If IP addresses are used to manage computers, use IP addresses to specify host names.

(3) Notes

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag. Also, when using command arguments, you cannot specify /g and /h together with /X.

When host names are used as the ID keys for operations, you cannot use the host_name parameter in the following cases:

Use Network in Windows is selected as the method of address resolution on the Settings for Address Resolution panel for the setup of JP1/IT Desktop Management 2 - Manager. Or, Use Network in Windows is selected in Settings of the ID key for operations under Relay system settings for agent configuration. However, address resolution fails

Use the system configuration information for IT Desktop Management 2 is selected as the method of address resolution on the Settings for Address Resolution panel for the setup of JP1/IT Desktop Management 2 - Manager. Or, Use the system configuration information for IT Desktop Management 2 is selected in Settings of the ID key for operations under Relay system settings for agent configuration.

14.20.10 JOB_DESTINATION_ID (specifying an ID group)

In the JOB_DESTINATION_ID tag, specify the name of an ID group as the job destination. This tag is used for the dcmcoll, dcminst, and dcmsusp commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

destination_id

ID group name

/X ID-group-name

(1) Format

JOB_DESTINATION_ID{
destination_id=ID-group-name
}

(2) Description

destination_id=ID-group-name

Specify a created ID group name. You can also specify an ID-management relay computer to restrict the relay systems or management relay servers on which to execute the ID group job. When specifying the name of an ID-management relay computer, begin the name with a backslash (\). Also, begin the ID group name with \, and the character % immediately before the ID name.

If you do not specify an ID-management relay computer, the job is executed on all the ID-management relay computers that are registered in the specified ID group.

The following shows an example of specifying an ID group name.

destination_id=\dmp202\%ID0001

Note that the name of an ID-management relay computer must be specified according to the ID key for operations defined for that ID-management relay computer.

When specifying multiple ID groups, separate their names by a semicolon (;).You can specify multiple ID groups also by writing destination_id= on multiple lines. You can specify a maximum of 200 ID groups.

(3) Notes

You cannot specify the JOB_DESTINATION tag together with the JOB_DESTINATION_ID tag. Also, when using command arguments, you cannot specify /g and /h together with /X.

When a parameter file is used for the dcmcoll or dcmsusp command, you cannot specify an ID-management relay computer in the parameter file. If you execute these commands with an ID-management relay computer specified, an error will result.

When you specify an ID-management relay computer, make sure that the length of the destination name (including the ID group name) is no more than 256 bytes.

If a command is executed with a nonexistent relay system or management relay server specified, a job is created but is not executed.

The dcmcoll and dcmsusp commands handle the ID group specified in the destination_id parameter, and create a normal job for the destinations registered in the ID group.

14.20.11 JOB_SCHEDULE (specifying a job schedule)

In the JOB_SCHEDULE tag, specify the date and time of job registration, date and time of job execution, and the date of job expiration as schedule information. This tag is used for the dcmcoll, dcminst, dcmjexe, and dcmsusp commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

job_entry_date

Job registration date and time

/jst value

job_execution_date

Job execution date and time

/jsx value

job_expiration_date

Job expiration date

/jsp value

(1) Format

JOB_SCHEDULE{
job_entry_date=job-registration-date-and-time
job_execution_date=job-execution-date-and-time
job_expiration_date=job-expiration-date
}

(2) Description

job_entry_date=job-registration-date-and-time

Specify the date and time of job registration in the YYMMDDhh:mm format.

YY: Last two digits of year (00 to 99)

MM: Month (01 to 12)

DD: Day (01 to 31)

hh: Hour (00 to 23)

mm: Minute (00 to 59)

When this parameter is omitted, the date and time at which the job is executed is assumed to be the date and time of job registration.

job_execution_date=job-execution-date-and-time

Specify the date and time of job execution in the YYMMDDhh:mm format.

The values of job execution date and time use the same format as that for the job_entry_date parameter.

When this parameter is omitted, the target job is executed immediately. Note that you can omit this parameter only when you omit both of the job_entry_date and job_expiration_date parameters.

job_expiration_date=job-expiration-date

Specify the date and time of job expiration in the YYMMDDhh:mm format.

The values of job expiration date use the same format as that for the job_entry_date parameter.

When this parameter is omitted, the job expiration date is indefinite.

(3) Notes

An error occurs when the values of the job_execution_date, job_entry_date, and job_expiration_date parameters do not meet the following condition:

When the job registration date and time, job execution date and time, or job expiration date is specified for a job, a job definition is stored in the server. If the stored job definition is deleted before the job is created (that is, before the specified job registration date and time), the job cannot be created.

When the job registration date and time, job execution date and time, or job expiration date is specified for a job, the command will end normally even with a nonexistent destination, host group, or destination ID specified, but the job will not be executed.

The values for the last two digits of year have the following meanings:

70 to 99: Years in the 1900s

00 to 69: Years in the 2000s

14.20.12 JOB_SPLIT_DELIVERY (specifying the split package distribution)

In the JOB_SPLIT_DELIVERY tag, specify the split distribution of a package. This tag is used only for the dcminst command. This tag is ignored when it is specified for other commands.

The following table shows the parameters that can be specified and their corresponding command arguments:

Parameter

Content

Command argument

split_size

Split size

/sds value

wait_time

Distribution interval

/sdt value

(1) Format

JOB_SPLIT_DELIVERY {
split_size=split-size
wait_time=distribution-interval
}

(2) Description

split_size=split-size

Specify the split size of package in the range from 1 to 2,097,151 in kilobytes. The default is 1,024 kilobytes.

wait_time=distribution-interval

Specify the interval of split distribution in the range from 1 to 1,440 in minutes. The default is 60 minutes.

When you specify either the split_size or wait_time parameter, split package distribution will be executed. The split size and distribution interval are determined as described below after the values specified in the parameters are compared with the values set for the setup of the package transfer destination.

As for the split size, the value specified in the split_size parameter is compared with the value set for the setup of the package transfer destination, and the value smaller than the other is applied as the split size.

As for the distribution interval, the value specified or set together with the smaller split size described above is applied. When the two values of the split size are the same, the value of distribution interval set at the package transfer destination is applied.

14.20.13 OPTION (specifying options)

In the OPTION tag, specify the options for remote installation. This tag is used for the dcminst and dcmpack commands.

The following table shows the parameters that can be specified and their corresponding command arguments:

Parameter

Content

Command argument

compress

Whether to compress

/uY or /uN

compress_type

Compression mode

/ctN or /ctH

restore

Whether to restore at upgrading

/RY or /RN

reboot

Computer restart after installation

/reboot

processing_dialog

Whether to display processing message during installation

/procS, /procY, or /procN

(1) Format

OPTION{
compress=whether-to-compress
compress_type=compression-mode
restore=whether-to-restore-at-upgrading
reboot=computer-restart-after-installation
processing_dialog=whether-to-display-processing-message-during-installation
}

(2) Description

compress=whether-to-compress

Write Y or N to specify (for the dcmpack command) whether to compress software at packaging or (for the dcmcoll command) whether to compress files at collection.

When using a command argument for specification, write Y or N immediately after /u. When no value is specified in this parameter, N (do not compress) is set automatically.

Y

Compresses packages at packaging or files at file collection.

A compressed package is automatically decompressed when it is installed remotely. Compressing packages shorten the time required for file transfer, and enables you to save the space to store packages in the cabinet. Note, however, that compression and decompression require an extra time at packaging and remote installation, respectively.

N

Does not compress packages at packaging or files at file collection.

compress_type=compression-mode

For the dcmpack command, specify a compression mode as H (Windows only mode) or N (UNIX shared mode). You cannot specify this parameter for the dcmcoll command.

To specify this parameter as a command argument, specify N or H immediately after /ct. If you omit this parameter, H (Windows only mode) is set automatically.

H

Compresses files in Windows only mode. This mode can compress files more than UNIX shared mode. Use this mode when distributing files to Windows computers. You cannot use this mode when distributing files to UNIX computers.

N

Compresses files in UNIX shared mode. You can use this mode to distribute files to UNIX computers as well.

restore=whether-to-restore-at-upgrading

Write Y or N to specify whether to restore software when it is upgraded. You cannot specify this parameter for the dcmcoll command.

When using a command argument for specification, write Y or N immediately after /R. When no value is specified in this parameter, N (do not restore) is set automatically.

Y

Restores software when it is upgraded. When software is upgraded, the previous version of the software installed at a remote installation destination is backed up. If the remote installation of upgraded version of the software fails, the previous version of the software is restored by using the backup.

N

Does not restore software when it is upgraded.

reboot=computer-restart-after-installation

Write Y or N to specify whether to automatically restart the agent after a package is installed. You cannot specify this parameter for the dcmcoll command. When no value is specified in this parameter, N (do not restart) is set automatically.

Y

Displays a confirmation dialog box (on the agent) to ask whether to restart the agent after a package is installed. Clicking OK in the dialog box on the agent restarts the agent.

N

Does not restart the agent after a package is installed.

When using a command argument for specification, specify /reboot to restart the agent or omit the argument not to restart.

Among all computers in this system, only agent computers can be restarted automatically. Relay systems and management relay servers cannot be restarted automatically even when restart is specified for the package installed.

For the notes on automatically restarting the computer and the cases disabling automatic restart, see 7.2.9 Options page.

processing_dialog=whether-to-display-processing-message-during-installation

Write SETUP, Y, or N to specify whether to display the dialog boxes indicating the progress of processing during installation of a package on the agent. The dialog boxes to be displayed are the dialog box indicating that a package is being downloaded and that indicating that a package is being installed. You cannot specify this parameter for the dcmcoll command.

When using a command argument for specification, write S, Y, or N immediately after /proc. When no value is specified in this parameter, SETUP (follow the setting on the agent) is set automatically. (When the command argument /proc is used, the default is /procS.)

SETUP

Determines the operation of the dialog boxes indicating the progress of processing according to the settings specified in Display settings for dialog boxes indicating that a job is being progressed under Job settings for agent configuration. The setting of this parameter might differ between the dialog box indicating the progress of downloading and the dialog box indicating the progress of installation. Even in such as case, the dialog boxes are operated according to the settings specified in Display settings for dialog boxes indicating that a job.

Y

Displays the dialog boxes indicating the progress of downloading and the progress of installation regardless of the settings in Display settings for dialog boxes indicating that a job is being progressed under Job settings for agent configuration.

N

Does not display the dialog boxes indicating the progress of packaging and installation regardless of the settings in Display settings for dialog boxes indicating that a job is being progressed under Job settings for agent configuration.

The following table shows whether the dialog boxes indicating the progress of processing are displayed according to the setting of the processing_dialog parameter and the settings in Display settings for dialog boxes indicating that a job is being progressed:

Display settings for dialog boxes indicating that a job is being progressed

processing_dialog parameter setting for package

SETUP

Y

N

Display

Yes

Yes

--

Do not display

--

Yes

--

Legend:

Yes: The dialog boxes are displayed.

--: The dialog boxes are not displayed.

Assume that display of the dialog boxes indicating the progress of processing is specified for a package. Then, whether to display the dialog box indicating the progress of installation in the foreground follows the corresponding setting in Display settings for dialog boxes indicating that a job is being progressed.

14.20.14 OUTPUT_CONSTRAINTS (specifying the output information)

In the OUTPUT_CONSTRAINTS tag, you can specify the kinds and comparison condition for the information you want to output. You can use this tag in the dcmcsvu command only.

The following table shows the parameters that can be specified and their corresponding command arguments:

Parameter

Content

Command argument

template

Template used for exporting

template-key

format

Format of the output file

csv or par

row

Item (row) to be output

--

group_membership

Group to which the targets belongs

--

condition

Comparison condition

--

Legend: --: Do not specify as a command argument.

Use a template provided by JP1/Software Distribution to specify the items you want to output. This template is the same as the template that the CSV output utility uses. Information is output for the items included in the specified template (the columns in the template). For some templates, you can also perform the following operations:

Exporting only the specified information items (valid only when exporting information to a file in CSV format)

Extracting the output information by specifying the comparison condition expression or host group

(1) Format

OUTPUT_CONSTRAINTS{
template = template-key
format = export-file-format (csv or par)
row = items-to-be-output (row)
group_membership = group-of-the-host
condition = condition
}

(2) Description

template=template-key

In template-key, specify the template key for the template you want to use for exporting the inventory information. The items you can export with the template are the same as the items that the CSV output utility outputs to a CSV-formatted file.

You can specify any template when exporting inventory information in CSV format. However, some templates cannot be specified when you export inventory information in the parameter file format. The following shows the templates and the export formats that can be specified.

Table 14‒18: Export file formats and templates that can be specified

Template key

Corresponding template

CSV format

Parameter file format

HOST_ATTR

Host attributes

Y

Y

PKG_INFO

Package attributes

Y

Y

PKG_FILES

Package contents

Y

N

INSTLD_PKG

Installed package information

Y

Y

J_STAT

Job status

Y

Y

Legend:

Y: Specifiable

N: Not specifiable

format=export-file-format

Specify either of these keywords as the export format of the output file:

csv

Exports the inventory information to the result output file in CSV format.

par

If you specify this keyword, the command exports the inventory information to the result output file in the parameter file format.

When you export the inventory information to a file in the parameter file format, the tag information to be output differs depending on the template you use. The following shows the template keys and the tags that are displayed.

Table 14‒19: Tags to be output to a file in the parameter file format

Template key

Parameter file format

HOST_ATTR (host attribute)

JOB_DESTINATION

PKG_INFO (package attribute)

PACKAGING_INFORMATION

INSTLD_PKG (installed package information)

JOB_DESTINATION

J_STAT (job status)

JOB_DESTINATION

If you specify the export format in both a command argument and the parameter file, the command argument prevails. If you specify the export format in neither a command argument nor the parameter file, csv is used by default.

row=items-to-be-output (row)

To output inventory information to a CSV-formatted file, individually specify the items (rows) in the template that are to be output. Use a semicolon (;) to separate each item. The spaces before and after semicolons are ignored.

The following shows the format of the row parameter:

row = item-1;item-2;item-3...

If you do not specify the row parameter, the command outputs the information for all items. The output item specification by the row parameter is valid only when you use any of the following templates to export the inventory information to a file in the CSV format:

HOST_ATTR (host attribute)

INSTLD_PKG (installed package information)

J_STAT (job status)

When you use a template other than the preceding to export the inventory information to a file in CSV format, you cannot specify the items you want to output. The command outputs the information for all items. If you export the inventory information to a file in the parameter file format, the row parameter is ignored.

Tables 14-20 to 14-22 list the items you can specify in the row parameter in each template.

Table 14‒20: Items that can be specified in the row parameter with the HOST_ATTR (host attribute) template

Items that can be specified in the row parameter

Explanation

host

Host name

ipaddr

IP address

hid

Host ID

macaddr

MAC address

type

Type

route

Route

group

Group to which the host belongs

holdrep

Notification hold

suspended

File transfer suspended at relay system

cmnt

Comment

cdate

Creation date/time

date

Update date/time

pkgupdate

Installed package information last update date

Table 14‒21: Items that can be specified in the row parameter with the INSTLD_PKG (installed package information) template

Items that can be specified in the row parameter

Explanation

host

Host name

ipaddr

IP address

pname

Package name

pid

Package ID

install

Installation

newver

New version

newgen

New generation

date

Installation or software search date/time

Table 14‒22: Items that can be specified in the row parameter with the J_STAT (job status) template

Items that can be specified in the row parameter

Explanation

folder

Folder name

jname

Job name

jattr

Job attribute

execdate

Execution date/time at the server

execsch

Scheduled execution date/time at the server

sduedate

Execution time limit at the server

sregdate

Scheduled registration date/time at the server

dstname

Job destination name

jtype

Job type

dexecdate

Job execution date/time by destination

pname

Package name

pid

Package ID

cabid

Cabinet ID

dmcode

DM ID code

pver

Version

pgen

Generation

cexecdate

Installation date/time at the client

result

Result

status

Status

group_membership=group-of-the-host

In group-of-the-host, specify the group to which the target host belongs as a condition for extracting the information to be output. You can specify one of the group types: relay manager/system, host group, and ID group. You can specify more than one group of the same type. When you specify more than one group, use a semicolon (;) to separate each of the groups or write more than one group_membership parameter line. The specified groups are evaluated with the OR condition. The following shows the format of the group_membership parameter:

group_membership = [relay-manager/systems | host-groups | ID-groups]

relay-manager/systems

In relay-manager/systems, specify one or more relay managers/systems. You can specify paths consisting of names delimited by backslashes (\).

host-groups

In host-groups, specify one or more host group names that begin with a backslash (\). You can specify paths consisting of names delimited by backslashes (\).

ID-groups

In ID-groups, specify an ID group name that begins with \%.

The templates that allow you to use the group_membership parameter for extracting information differ depending on the export file format. The following shows the export file formats for which the template supports the group_membership parameter.

Table 14‒23: Templates supporting the group_membership parameter

Template key

Corresponding template

CSV format

Parameter file format

HOST_ATTR

Host attributes

O

O

PKG_INFO

Package attributes

X

X

PKG_FILES

Package contents

X

--

INSTLD_PKG

Installed package information

O

X

J_STAT

Job status

X

X

Legend:

O: Can specify the group_membership parameter.

X: Cannot specify the group_membership parameter.

--: Template that cannot be used in parameter file format.

condition=condition

In condition, specify a comparison condition expression for limiting the range of values you want to output. You can use items (rows) of the template as the keys for extracting information to create a comparison condition expression.

The templates that allow you to use the condition parameter differ depending on the export file format. You can use the condition parameter for all the templates available for exporting to a file in the parameter file format. The table below shows the export file formats for which the template supports the condition parameter.

Table 14‒24: Templates supporting the condition parameter

Template key

Corresponding template

CSV format

Parameter file format

HOST_ATTR

Host attributes

X

O

PKG_INFO

Package attributes

X

O

PKG_FILES

Package contents

X

--

INSTLD_PKG

Installed package information

O

O

J_STAT

Job status

O

O

Legend:

O: Can specify the condition parameter.

X:Cannot specify the condition parameter.

--: Template that cannot be used in parameter file format.

The following shows the format of the condition parameter:

condition = condition [{AND|OR} condition [{AND|OR} condition] ]...

Use the AND and/or OR operators to combine operands to create a condition expression. The conditional expression AND is executed first. The following shows examples of expressions:

X AND Y AND Z

The program extracts the information that satisfies all of the conditions X, Y, and Z.

X AND Y OR Z

The program extracts the information that satisfies both the conditions X and Y, and extracts the information that satisfies the condition Z.

X OR Y AND Z

The program extracts the information that satisfies both the conditions Y and Z, or the condition X.

X OR Y OR Z

The program extracts the information that satisfies any of the conditions X, Y, and Z.

When you use more than one comparison condition, remember the following points:

When writing more than one condition statement line, use AND operators to combine them.

You can write up to 15 condition statement lines.

The table below shows the formats of the comparison conditions you can use.

Table 14‒25: Formats of comparison conditions

Comparison condition

Explanation

A=X

The value of the item A is equal to the condition value X.

A<X

The value of the item A is less than the condition value X.

A>X

The value of the item A is greater than the condition value X.

A<=X

The value of the item A is less than or equal to the condition value X.

A>=X

The value of the item A is greater than or equal to the condition value X.

A<>X

The value of the item A is not the condition value X.

A: X1-X2

The value of the item A is within the range of the condition values X1 to X2.

A: X1, X2, ... Xn

The value of the item A is any of the condition values X1, X2, ... and Xn.

A=[*]X*

The value of the item A includes the character string X. An asterisk (*) stands for an indefinite number of characters. A question mark (?) stands for a single character (1 byte).

Examples:

dmp60?: Information such as dmp600, dmp601, and dmp602 is output.

dmp?00: Information such as dmp100, dmp300, and dmp600 is output.

dmp60*: Information such as dmp600, dmp6000, and dmp60000 is output.

A<>X1-X2

The value of the item A is not within the range from the condition values X1 to X2.

A<>X1, X2, ... Xn

The value of the item A is not any of the condition values X1, X2, ... and Xn.

A<>[*]X*

The value of the item A does not include the character string X. An asterisk (*) stands for an indefinite number of characters. A question mark (?) stands for a single character (1 byte).

<>dmp60?: Information other than strings such as dmp600, dmp601, and dmp602 is output.

<>dmp60*: Information other than strings such as dmp600, dmp6000, and dmp60000 is output.

Notes

The value A in the comparison condition indicates an item used as a key for extracting information. For the items that can be specified in the condition parameter, see tables below.

If a required entry is missing or there is a conflict in the condition expression, the program returns a syntax error and outputs an error message to the event log.

You can place 0 or more spaces between a value and an operator (=, >, etc.).

You can use wildcards only when the comparison condition is in an A =[*]X* or A <>[*]X* format.

If you want to use an asterisk (*) as a wildcard in a condition expression, always append a semicolon (;) to the expression. You can write a comment after the semicolon. If you do not append a semicolon, the program skips the portion after an asterisk, assuming the portion to be a comment.

If you want to use =, <, >, :, -, AND, or OR as a character string in a condition expression, prefix a backslash (\) to them.

For example, if you want to use a host with the name AND as a condition, specify:

host=\AND

The items that can be specified in the condition expression of a condition parameter differ depending on the export file format (the CSV format or parameter file format). If you use an item that cannot be used as a comparison condition, an error occurs and a return code 2 is returned.

Tables 14-26 to 14-27 list the items you can specify in the condition parameter when exporting information to a file in CSV format.

Table 14‒26: Items that can be specified in the condition parameter with the INSTLD_PKG (installed package information) template when exporting to a file in CSV format

Item

Explanation

Setting the values and conditions

host

Host name

Inclusion of , or > causes a syntax error.

ipaddr

IP address

Inclusion of , or > causes a syntax error.

The number of periods is not checked

pname

Package name

Inclusion of , or > causes a syntax error.

pid

Package ID

Inclusion of , or > causes a syntax error.

newver

New version

Inclusion of , or > causes a syntax error.

newgen

New generation

Inclusion of , or > causes a syntax error.

date

Installation or software search date/time

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

#:

In YYYY (year), specify a value in the range from 1970 to 3000. If you do not specify a value within this range, an error occurs and the return code 2 is returned. You can omit the portions other than YYYY. The omitted portions are set to their minimum values. If you specify a single-digit value, prefix a 0 to align the digits. If you do not align the digits, an error occurs. The following examples show you how to use date representation correctly:

200

Error

2022

0:00 on January 1, 2022

2022101

Error

20221010

0:00 on October 10, 2022

202201010101

1:01 on January 1, 2022

202212312359

23:59 on December 31, 2022

If you use a date/time representation in the following comparison conditions, an error occurs: A=X, A<>X, A:X1,X2,... Xn, A=[*]X*, A<>X1,X2,... Xn, or A<>[*]X*.

Table 14‒27: Items that can be specified in the condition parameter with the J_STAT (job status) template when exporting to a file in CSV format

Item

Explanation

Setting the values and conditions

jname

Job name

Inclusion of , or > causes a syntax error.

execdate

Execution date/time at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

execsch

Scheduled execution date/time at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

sduedate

Execution time limit at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

sregdate

Scheduled registration date/time at the server.

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

dstname

Job destination name

Inclusion of , or > causes a syntax error. Use ! or \ for hierarchical representation.

dexecdate

ob execution date/time by destination

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

pname

Package name

Inclusion of , or > causes a syntax error.

pid

Package ID

Inclusion of , or > causes a syntax error.

cabid

Cabinet ID

Inclusion of , or > causes a syntax error.

pver

Version

Inclusion of , or > causes a syntax error.

pgen

Generation

Inclusion of , or > causes a syntax error.

status

Status

You can specify the first 1 to 6 characters of the maintenance code for Remote Installation Manager. You can use * or ? in the condition. If you include , or >, a syntax error occurs. The following comparison conditions cannot be specified: A:X1-X2, A:X1,X2,... Xn, A<>X1 - X2, and A<>X1,X2,... Xn.

#

For details about how to represent the date/time and examples of date/time representation, see Table 14-26.

Tables 14-28 to 14-31 list the items you can specify in the condition expression of a condition parameter when exporting to a file in the parameter file format. Unlike when the CSV output utility is used, when you use a command to output a file in parameter file format, you can use the Host attributes and Package attributes template to narrow the conditions.

Table 14‒28: Items that can be specified in the condition parameter with the HOST_ATTR (host attribute) template when exporting to a file in the parameter file format

Item

Explanation

Setting the values and conditions

host

Host name

Inclusion of , or > causes a syntax error.

ipaddr

IP address

Inclusion of , or > causes a syntax error.

The number of periods is not checked

cmnt

Comment

Inclusion of , or > causes a syntax error.

cdate

Creation date/time

Use only numbers to represent the date/time in the YYYYMMDDhhmm format.#

date

Update date/time

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

pkgupdate

Installed package information last update date

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

#

For details about how to represent the date/time and examples of date/time representation, see Table 14-26.

Table 14‒29: Items that can be specified in the condition parameter with the PKG_INFO (package attribute) template when exporting to a file in the parameter file format

Item

Explanation

Setting the values and conditions

pname

Package name

Inclusion of , or > causes a syntax error.

pid

Package ID

Inclusion of , or > causes a syntax error.

cabid

Cabinet ID

Inclusion of , or > causes a syntax error.

dmcode

DM ID code#

Specify PC or WS. Any other specification causes an error.

pver

Version

Inclusion of , or > causes a syntax error.

pgen

Generation

Inclusion of , or > causes a syntax error.

cabname

Cabinet name

Inclusion of , or > causes a syntax error.

#

The template does not include this item, but it can be specified in the condition parameter.

Table 14‒30: Items that can be specified in the condition parameter with the INSTLD_PKG (installed package information) template when exporting to a file in the parameter file format

Item

Explanation

Setting the values and conditions

host

Name of the host where the package is installed

Inclusion of , or > causes a syntax error.

ipaddr

IP address of the host where the package is installed

Inclusion of , or > causes a syntax error. The number of periods is not checked.

pname

Package name

Inclusion of , or > causes a syntax error.

pid

Package ID

Inclusion of , or > causes a syntax error.

install

Installation

Inclusion of , or > causes a syntax error.

newver

New version

Inclusion of , or > causes a syntax error.

newgen

New generation

Inclusion of , or > causes a syntax error.

date

Installation or software search date/time

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

#

For details about how to represent the date/time and examples of date/time representation, see Table 14-26.

Table 14‒31: Items that can be specified in the condition parameter with the J_STAT (job status) template when exporting to a file in the parameter file format

Item

Explanation

Setting the values and conditions

folder

Folder name

Inclusion of , or > causes a syntax error.

jname

Job name

Inclusion of , or > causes a syntax error.

jattr

Job attribute

Inclusion of , or > causes a syntax error.

execdate

Execution date/time at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

execsch

Scheduled execution date/time at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

sduedate

Execution time limit at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

sregdate

Scheduled registration date/time at the server

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

dstname

Job destination name

There are no restrictions. Use ! or \ for hierarchical representation.

jtype

Job type

Inclusion of , or > causes a syntax error.

dexecdate

Job execution date/time by destination

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

pname

Package name

Inclusion of , or > causes a syntax error.

pid

Package ID

Inclusion of , or > causes a syntax error.

cabid

Cabinet ID

Inclusion of , or > causes a syntax error.

dmcode

DM ID code

Specify PC or WS. Any other specification causes an error.

pver

Version

Inclusion of , or > causes a syntax error.

pgen

Generation

Inclusion of , or > causes a syntax error.

cexecdate

Installation date/time at the client

Use numbers only to represent the date/time in the YYYYMMDDhhmm format.#

result

Result

Inclusion of , or > causes a syntax error.

status

Status

You can specify the first 1 to 6 characters of the maintenance code for Remote Installation Manager. You can use * or ? in the condition.

If you include , or >, a syntax error occurs. The following comparison conditions cannot be specified: A:X1-X2, A:X1,X2,... Xn, A<>X1-X2, and A<>X1,X2,... Xn

#

For details about how to represent the date/time and examples of date/time representation, see Table 14-26.

14.20.15 PACKAGING_INFORMATION (setting package attribute information)

In the PACKAGING_INFORMATION tag, sets the information to identify a package. This tag is used for the dcminst, dcmpack, dcmpkget, and dcmpkrm commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

package_name

Package name

/p package-name

package_id

Package ID

/I package-ID

version_revision

Version/revision

/v version/revision

generation

Generation number

/G generation-number

cabinet_name

Cabinet name

/c cabinet-name

cabinet_id

Cabinet ID

/C cabinet-ID

package_code

Code type

/KW or /KP

(1) Format

PACKAGING_INFORMATION{
package_name=package-name
package_id=package-ID
version_revision=version/revision
generation=generation-number
cabinet_name=cabinet-name
cabinet_id=cabinet-ID
package_code=code-type
}

(2) Description

package_name=package-name

Specify the name of the user program and data to be packaged. A package name can consist of a maximum of 50 single-byte characters (or 25 double-byte characters). You cannot use the character \ and space in a package name.

package_id=package-ID

Assign a unique ID to each package. JP1/IT Desktop Management 2 identifies packages with their package IDs. A package ID must consist of 1 to 44 characters. You can use single-byte alphanumeric characters (alphabetic characters are limited to uppercase letters), hyphen (-), and underscore (_).

version_revision=version/revision

Set the version/revision number in this parameter. The version/revision number can consist of a maximum of six digits, and single-byte alphanumeric characters (alphabetic characters are limited to uppercase letters) and forward slash (/) can be used for the number. When \increment [:start-value] is specified, the version/revision number can be incremented automatically when the dcmpack command is executed. In that case, you can write a single-byte alphanumeric character string immediately before \. Note, however, that the total size of the character string and the number set in \increment must not exceed six digits.

Automatic incrementing starts with the specified start value, and increments the version/revision number by the value of increment until the package is registered successfully. (In other words, incrementing continues until the version/revision number becomes unique among those of already registered packages). If the start value is not specified, incrementing starts with 0. If the value exceeds six digits, an error occurs.

When automatic incrementing is specified in the parameter file, the current start value immediately after : is overwritten with a next start value (registered value + increment) each time packaging is executed by the dcmpack command. When the start value exceeds six digits, it is reset to 0. When automatic incrementing is specified by using a command argument, the start value is reset to the initial value each time a package is registered.

generation=generation-number

Assign a generation number in addition to the version/revision number. The packages of the same version/revision can be classified by using the generation number.

A generation number must be a string of single-byte alphanumeric characters (alphabetic characters are limited to uppercase letters) of up to four digits. When \increment [:start-value] is specified, the generation number can be incremented automatically when the dcmpack command is executed. In that case, you can write a single-byte alphanumeric character string immediately before \. Note, however, that the total size of the character string and the number set in \increment must not exceed four digits.

Automatic incrementing starts with the specified start value, and increments the generation number by the value of increment until the package is registered successfully. (In other words, incrementing continues until the generation number becomes unique among those of already registered packages). If the start value is not specified, incrementing starts with 0. If the value exceeds six digits, an error occurs.

When automatic incrementing is specified in the parameter file, the current start value immediately after : is overwritten with a next start value (registered value + increment) each time packaging is executed by the dcmpack command. When the start value exceeds four digits, it is reset to 0. When automatic incrementing is specified by using a command argument, the start value is reset to the initial value each time a package is registered.

For packages to be distributed to UNIX computers, you must specify a four-digit value. If you do not specify a four-digit value, packaging will succeed, but an error will occur during remote installation.

cabinet_name=cabinet-name

Specify a unique cabinet name. You can specify a cabinet name that consists of a maximum of 32 single-byte characters (or 16 double-byte characters). You cannot use \, /, *, ", :, ;, and space character in a cabinet name.

cabinet_id=cabinet-ID

Specify a two-digit string of single-byte alphanumeric characters (alphabetic characters are limited to uppercase letters) as a unique ID for each cabinet.

package_code=code-type

Specify P (for Windows) or W (for UNIX) to indicate the type of package to be installed remotely. To specify this parameter as a command argument, specify P or W immediately after /K.

If you omit this parameter when executing the dcminst command, specification of P (for Windows) is assumed, but packages can also be remotely installed on UNIX computers. Note that when you remotely install packages created in the UNIX version of JP1/IT Desktop Management 2 - Agent, you must specify W (for UNIX). When this parameter is not specified for the dcmpkget command, specification of P (for Windows) is assumed. For the dcmpkrm command, this parameter must always be specified. For the dcmpack command, this parameter is invalid even when specified.

P

Indicates that the package is intended for Windows.

W

Indicates that the package is intended for UNIX.

(3) Specifiable reserved words

The reserved words that can be used in this tag are \CY, \CM, \CD, \CH, \CN, \CS, \BY, \BM, \BD, \BH, \BN, \BS, \VERSION, \PKGID, \FILE, \SIZE, and \BASE. Note, however, that there are the following restrictions placed on the usage of the reserved words.

The reserved words can be used only when this tag or arguments are used for the dcmpack command. The reserved words cannot be used for the dcminst, dcmpkget, and dcmpkrm commands.

\VERSION and \PKGID cannot be used for the package_id parameter (argument /I).

\VERSION cannot be used for the version_revision parameter (argument /v).

\increment and a reserved word cannot be specified together in the version_revision parameter (argument /v) and generation parameter (argument /G).

(4) Notes

To specify multiple packages for the dcminst or dcmpkget command, you can specify the package information parameters for multiple packages in one PACKAGING_INFORMATION tag. In that case, enclose the package information on each tag in curly brackets ({ }). The following shows an example of specifying multiple packages in one PACKAGING_INFORMATION tag.

PACKAGING_INFORMATION{
{* Information on package 1
package_name=PACKAGE1
package_id=PACK01
       :
}
{* Information on package 2
package_name=PACKAGE2
package_id=PACK02
       :
}
}

When automatic incrementing is required for a package for which <, <=, >, or >= is specified in place of an equal sign in the package condition for comparison purposes, specify the start value of the following parameters as shown below.

Version/revision

100,000 or more (Specify a value in this range so that there are six significant digits.)

Generation number

1,000 or more (Specify a value in this range so that there are four significant digits.)

14.20.16 PACKAGING_SOURCE (specifying the file to be packaged)

In the PACKAGING_SOURCE tag, specify the file or directory to be packaged. This tag is used for the dcmpack command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

file_path

Name of packaging-target file

/P name-of-packaging-target-file

base_fullpath

Path name of packaging base directory

/B path-name-of-packaging-base-directory

(1) Format

PACKAGING_SOURCE{
file_path=name-of-packaging-target-file
base_fullpath=path-name-of-packaging-base-directory
}

(2) Description

file_path=name-of-packaging-target-file

Specify the path name of the file or directory to be packaged. The path name must indicate the relative path from the directory specified in the base_fullpath parameter to the file or directory to be packaged. For packages to be distributed to UNIX computers, however, you must use forward slashes (/) rather than backslashes (\) to separate each level. When the package is installed, the directory structure from the directory specified in base_fullpath to the package is restored under the installation-target directory in JP1/IT Desktop Management 2 - Agent.

To specify multiple files or subdirectories under the same directory (for example, a root directory), separate the path names of the files or subdirectories by a semicolon (;) or write multiple file_path parameters.

The value specified in this statement can include a space. Entering a space before or after a separator (;), however, causes an error (indicated by the return code 2). Also, do not enclose a specified value in double quotation marks (""). Note that, when you use a command argument for specification, a value that includes a space must be enclosed in double quotation marks ("").

When the file_path parameter is omitted, all the files under the directory specified in the base_fullpath parameter are packaged. If a file is specified in the base_fullpath parameter, only the specified file is packaged.

base_fullpath=path-name-of-packaging-base-directory

Specify the full path name of the directory that serves as a base for the file or directory to be packaged.

To specify a drive in this parameter, write the drive's path name up to the colon (:). For example, to package all contents of a DVD-R in drive A, write the path name as follows:

  base_fullpath = A:

Writing the path name as shown below causes an error:

  base_fullpath = A:\

14.20.17 SCHEDULE (specifying the schedule of remote installation)

In the SCHEDULE tag, specify the schedule of remote installation. This tag is used for the dcmcoll and dcmpack commands.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

expiration_date

Expiration date of package storage on relay computer

/x expiration-date-of-package-storage-on-relay-computer

expiration_days

The relay computer holds relayed packages for

/ed

the-relay-computer-holds-relayed-packages-for

installation_date_and_time

Installation date and time

/d installation-date-and-time

installation_timing

Execution timing

/tS or /tN

(1) Format

SCHEDULE{
expiration_date=expiration-date-of-package-storage-on-relay-computer
expiration_days=the-relay-computer-holds-relayed-packages-for
installation_date_and_time=installation-date-and-time
installation_timing=execution-timing
}

(2) Description

expiration_date=expiration-date-of-package-storage-on-relay-computer

Specify the expiration date of package storage on the relay system or management relay server in the YYMMDD format.

YY: Last two digits of year (00 to 94)

MM: Month (01 to 12)

DD: Day (01 to 31)

When the expiration date specified in this parameter is reached, the package stored on the relay system or management relay server is deleted automatically. If a package that has already expired or expires on the current day is distributed, the package will be deleted on the following day.

In actual operations, a relay system or management relay server must store a package until it is successfully installed on all the computers under the relay system or management relay server. For example, if three weeks are required for the distribution and installation of a package, specify a date at least three weeks after.

When this parameter is omitted, the sum of the date of packaging and the number of days set for The relay computer holds relayed packages for on the Packager is set as the expiration date.

Example:

Condition 1 Date of packaging: 010822 (August 22, 2001)

Condition 2 Setting of The relay computer holds relayed packages for: 10 days

In this case, the value to be set in this parameter is 010901 (September 1, 2001)

If no value is set for The relay computer holds relayed packages for on the Packager, the date 90 days after the packaging date is set as the expiration date.

expiration_days=the-relay-computer-holds-relayed-packages-for

Write a numerical value to specify the number of days of package storage. The value can be specified in the range from 1 to 32,000. If the specified value indicates a date after January 1, 2095, the number of days of package storage is always set to the number indicating December 31, 2094.

When the expiration_days parameter is specified together with the expiration_date parameter, the expiration_date parameter takes priority, and the expiration_days parameter is ignored.

When neither the expiration_date parameter nor the expiration_date parameter is specified, the number of days set as the default on the Packager is applied. If the default is not set on the Packager, the date 90 days after packaging is set.

If a value outside the specifiable range is specified in this parameter, an invalid command value error error occurs, and then the Event Viewer outputs a message.

installation_date_and_time=installation-date-and-time

Specify the date and time to remotely install the package in the YYMMDDhh:mm format.

YY: Last two digits of year (00 to 99)

MM: Month (01 to 12)

DD: Day (01 to 31)

hh: Hour (00 to 23)

mm: Minute (00 to 59)

installation_timing=execution-timing

Write S (at system startup) or N (during system operation) to specify the timing of collecting files (for the dcmcoll command) or the timing of installing packages (for the dcmpack command). When using a command argument for specification, write S or N immediately after /t. The default is N (during system operation).

S (at system startup)

Collects files or installs packages when the agent system starts. When the installation date and time are specified, packages are installed at the first system startup at or after the specified date and time.

N (during system operation)

Collects files or installs packages while the agent system is operating. When the installation date and time are specified, packages are installed at the specified date and time. If, however, the agent system is not operating at the specified date and time, packages will be installed at the next system startup.

14.20.18 SOFTWARE_CONDITIONS (specifying a package condition)

In the SOFTWARE_CONDITIONS tag, specify a package condition as a precondition for remote installation. This tag is used for the dcmpack command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

condition

Package condition

/l package-condition

(1) Format

SOFTWARE_CONDITIONS{
condition=package-condition
}

(2) Description

condition=package-condition

Specify the package condition to be a precondition for remote installation in the following format:

package-ID equal-sign version/revision-to-be-compared:generation-number-to-be-compared

package-ID

Specify the package ID to be a precondition for remote installation. Specify the ID specified in the package_id parameter in the PACKAGING_INFORMATION tag.

equal-sign

Specify =, >, >=, <, <=, or <>.

version/revision-to-be-compared

Specify the version/revision number to be compared. The number must not exceed eight digits.

generation-number-to-be-compared

Specify the generation number to be compared. The number must not exceed four digits.

(3) Notes

You cannot specify this tag for packages to be distributed to UNIX computers.

You can specify multiple package conditions. When multiple conditions are specified, the conditions are connected by logical OR. The package is installed when at least one of the specified conditions is met.

When using a command argument (/1) to specify a package condition, you can add package conditions until the total number of package conditions and system conditions (specified by /O) reaches 10.

The elements of a package condition are compared by character comparison beginning with the top of each element.

The magnitude correlation between specifiable characters is: single-byte alphabetic characters (A to Z) > single-byte numeric characters (0 to 9) > forward slash (/) > single-byte space ( ).

Therefore, when <, <=, >, or >= is specified as the equal sign and the version/revision and generation number to be compared are specified, adjust the digits of version/revision and generation number to those of the comparison-target software. For example, in an environment where the software PROGRAM with a version/revision of 0300 and a generation number of 0000 has been installed, do not specify PROGRAM>2:0 but specify PROGRAM>0200:0000 by adjusting the number of digits.

(4) Examples of specification

condition=P-2412-3554>0500:0000

Installation is executed when the software that has a version number larger than 05-00, a generation number larger than 0000, and a package ID of P-2412-3554 has been installed.

condition=P-2412-3554<>0510:0000

Installation is executed when the software that has a version number different from 05-10, a generation number different from 0000, and a package ID of P-2412-3554 has been installed.

14.20.19 INSTALLSOFTWARE_CONDITIONS (specifying a software condition)

In the INSTALLSOFTWARE_CONDITION tag, specify a software or updated program condition as a precondition for remote installation. This tag is used for the dcmpack command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

condition

Software condition

--

Legend:

--: The content cannot be specified by using a command argument.

(1) Format

INSTALLSOFTWARE_CONDITIONS{
condition=software-condition
}

(2) Description

condition=software-condition

Specify a software or updated program condition to be a precondition for remote installation. You can specify multiple software conditions. When multiple conditions are specified, the software is installed when one of the specified conditions is met.

Condition

Write Y (installed) or N (not installed) to specify the installation status of the software or updated program to be a precondition for remote installation.

Type

Write S (software) or U (updated program) to specify whether software or updated program is to be the precondition.

Software name

Specify the name of the software or update program to be a precondition for remote installation. Enclose the name in square brackets ([ ]). If the name includes a right square bracket (]), add another right square bracket to the existing one (]]).

Example: How to specify the software condition when the software name is Soft[sample]abc

[Soft[sample]]abc]

Equal sign

Specify a sign that matches the condition among =, >, >=, <, <=, and <>.

Version

Specify the version to be the comparison target. When condition is N (not installed) or type is U (updated program), version is ignored even if specified.

(3) Notes

You cannot specify this tag for packages to be distributed to UNIX computers.

You cannot specify an equal sign when the Type is set to U (updated program).

14.20.20 SYSTEM_CONDITIONS (specifying a system condition)

In the SYSTEM_CONDITIONS tag, specify the installation-target directory for remote installation and the computer system condition to be a precondition for installation. This tag is used for the dcmpack command.

The following table shows the parameters that can be specified, and their corresponding command arguments:

Parameter

Content

Command argument

directory

Installation-target directory

/D installation-target-directory

condition

System condition

/O system-condition

(1) Format

SYSTEM_CONDITIONS{
directory=installation-target-directory
condition=system-condition
}

(2) Description

directory=installation-target-directory

Specify the path name of the installation-target directory. You cannot specify a path name that includes a double quotation mark ("). The following shows an example of specification:

Example 1: When the distribution destination is a Windows computer

directory=C:\temp\data

Example 2: When the distribution destination is a UNIX computer

directory=/temp/data

When this parameter is omitted, specification of the path name of the packaging base directory (the directory set in the base_fullpath parameter of the PACKAGING_SOURCE tag or in the command argument /B) is assumed.

condition=system-condition

Specify the system condition of the distribution-destination computer. You can specify this parameter when the distribution destination is a Windows computer. Items (3) and (4) below describe how to specify different system conditions.

(3) When setting the free space of the hard disk as the condition

The following describes how to specify the system condition when setting a size of free space of the hard disk as the condition.

condition= H:drive-name equal-sign size

drive-name

Specify a single-byte alphanumeric character that indicates a drive.

equal-sign

Specify >=.

size

Specify a value in the range from 0 to 32,767 in megabytes.

Example of specification

The following shows specification of the condition when the drive C has a free space of 1 gigabytes or more.

condition=H:C>= 1024

(4) When setting a real memory size as the condition

The following describes how to specify the system condition when setting a real memory size as the condition.

condition=size-type equal-sign size

size-type

R: Real memory size

equal-sign

Specify a sign that matches the condition among =, >, >=, <, and <=.

size

Specify a size in megabytes.

Example of specification

The following shows specification of the condition when the real memory size is 16 gigabytes or more:

condition=R>=16

(5) When setting a version of the OS as the condition

The following describes how to specify the system condition when setting a version of the OS as the condition.

condition= O equal-sign OS

equal-sign

Specify a sign that matches the condition among =, >, >=, <, and <=.

OS

Specify a value that matches the condition among Windows11, WindowsServer2022, WindowsServer2019, WindowsServer2016, Windows10, Windows8.1, Windows8, WindowsServer2012, WindowsServer2012R2, Windows7, WindowsServer2008, WindowsServer2008R2, WindowsVista, WindowsServer2003, WindowsXP, and Any. Any means any Windows OS.

Example of specification

The following shows specification of the condition when the OS is Windows 7:

condition=O=Windows7

(6) Notes

Note the following when creating a package for UNIX:

You cannot specify system conditions. Directory specification is enabled, but any drive specification is ignored.

Specify an installation target directory by using no more than 64 single-byte characters (including a drive name and colons). If you specify more than 64 single-byte characters for a directory, the distributed package will be installed directly under the root directory.

You can specify multiple system conditions. When multiple conditions are specified, the conditions are connected by logical AND. The package is installed when all the conditions are met.

When using a command argument (/O) to specify a system condition, you can add system conditions until the total number of system conditions and package conditions (specified by /l) reaches 10.

14.20.21 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_executed_before_installation#1

External program to be started before installation

/b external-program-to-be-started-before-installation

external_program_executed_after_installation

External program to be started after installation

/a external-program-to-be-started-after-installation

external_program_error_handler#2

External program to be started at installation error

/e external-program-to-be-started-at-installation-error

external_program_handler

External program to be started

/ep external-program-to-be-started

exit#2

How to report the processing result of external program

/rbR, /rbM, /raR, /raM, /reR, /reM

action#2

Action to take when processing result is error

/ybC, /ybS, /yaC, /yaS

wait#2

Monitoring method

/wbU, /wbT, /wbG, /waU, /waT, /waG, /weU, /weY

timeout

Monitoring time

Maximum execution period (for the dcmstsw command)

/n monitoring-time

/wt maximum-execution-period (for the dcmstsw command)

wait_code

Monitoring code

/wc monitoring-code

#1

For packages to be distributed to UNIX computers, this parameter is ignored if you specify the installation_date_and_time parameter for the SCHEDULE tag at the same time.

#2

For packages to be distributed to UNIX computers, this parameter is ignored even if it is specified.

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.

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

14.21 How to specify reserved words

You can specify reserved words in parameters of the JOB_ATTRIBUTE and PACKAGING_INFORMATION tags, and their corresponding command arguments. Each command executes processing while replacing reserved words with actual values.

14.21.1 Reserved words available for the commands of JP1/IT Desktop Management 2

The following table shows the reserved words available for the commands of JP1/IT Desktop Management 2, and their values after replacement.

Table 14‒32: Reserved words available for the commands of JP1/IT Desktop Management 2

Reserved word

Value after replacement

\CY

Last two digits of year value at the time of command execution

\CM

Two digits of month value at the time of command execution

\CD

Two digits of day value at the time of command execution

\CH

Two digits of hour value at the time of command execution

\CN

Two digits of minute value at the time of command execution

\CS

Two digits of second value at the time of command execution

\BY

Last two digits of year value at the time of last update of the value specified in base_fullpath

\BM

Two digits of month value at the time of last update of the value specified in base_fullpath

\BD

Two digits of day value at the time of last update of the value specified in base_fullpath

\BH

Two digits of hour value at the time of last update of the value specified in base_fullpath

\BN

Two digits of minute value at the time of last update of the value specified in base_fullpath

\BS

Two digits of second value at the time of last update of the value specified in base_fullpath

\VERSION

First value in version_revision in the PACKAGING_INFORMATION tag

\GROUP

First value in group in the PACKAGING_INFORMATION tag. This reserved word is ignored when group is null. If the character string after replacement includes \, the character string is replaced further with a character string excluding \.

\HOST

First value in host_name in the JOB_DESTINATION tag. This reserved word is ignored when host_name is null. If the character string after replacement includes periods (.), the character string is replaced with a character string excluding the first period and subsequent part.

\DSTID

First value in destination_id in the JOB_DESTINATION_ID tag. This reserved word is ignored when destination_id is null.

\PKGID

First value in package_id in the PACKAGING_INFORMATION tag

\FILE

File name, or that first value in file_path in the PACKAGING_SOURCE tag which excludes the relative path of directory, period (.), and subsequent part. This reserved word is ignored when file_path is null.

\SIZE

Size of the file indicated by the first value in file_path in the PACKAGING_SOURCE tag. This reserved word is ignored when file_path is null. If a nonexistent file is specified in file_path, the command fails.

\BASE

File name, or that value in base_fullpath in the PACKAGING_SOURCE tag which excludes the relative path of directory, period (.), and subsequent part

\ZDIR

File name, or that value in dmz_path in the FILE_COLLECTION tag which excludes the relative path of directory, period (.), and subsequent part

14.21.2 Notes on the use of reserved words

This subsection describes some notes on using reserved words in a parameter file and command arguments.

Specify reserved words in a parameter (or argument) so that the length of the character string after replacement does not exceed the maximum number of digits that can be specified in the parameter (or argument). If the character string after replacement exceeds the maximum number of digits of the parameter, the character string after replacement will be truncated in units of reserved word or character string.

Example:

Assume that \PKGID-is-distributed-to-\HOST-relay-system is specified as a job name. In this case, the length of the job name always exceeds 32 bytes after the reserved words are replaced with the actual information. (This is because the length is 34 bytes even when the reserved words are replaced with a single character.) If 32 bytes is reached before the end of the -relay-system part, the job name is truncated at the end of the string with which the \HOST reserved word was replaced. If 32 bytes is reached before the end of the string with which the \HOST reserved word is replaced, the job name is truncated before that reserved word (up to ...-is-distributed-to-).

Specify reserved words in a parameter (or argument) so that, after replacement of reserved words, the character string will exclude prohibited characters defined for the parameter (or argument).

14.21.3 Examples of using reserved words

This subsection shows examples of parameter files using reserved words.

(1) Example of parameter file for the dcminst command

JOB_ATTRIBUTE{
job_generator=\PKGID and others are distributed to departments
      *If the job name exceeds 32 bytes after the reserved word is replaced, "and" and subsequent part are cut off.
      *If the job name has already been defined in the job storage folder, the job will fail.
job_folder=\distribution\CMmonth\CDday\CHhour
      *In this example, the job folder is created (in one hierarchical layer) under the root folder.
      *When storage (/s) is not specified, the folder is deleted from the newly created hierarchical layer after the job is executed.
}
JOB_DESTINATION{
      * Specify destinations in the JOB_DESTINATION or JOB_DESTINATION_ID tag.
host_name=host1;host2;host3
host_name=host4;host5;host6
group=\whole company\sales division;\whole company\material department;\whole company\engineering division
group=\whole company\personnel division
}

PACKAGING_INFORMATION{      *3 Example of distributing three packages
{
      *You can write the PACKAGING_INFORMATION tag to a different file separately from other tags.
      *
      *Or, execute the dcmpack command in advance, you can specify its output file as a parameter file.
package_name=1
package_id=1
version_revision=1
generation=1
cabinet_name=CAB01
cabinet_id=01
package_code=P
}
{
package_name=2
package_id=2
version_revision=2
generation=2
cabinet_name=CAB01
cabinet_id=02
package_code=P
}
{
package_name=3
package_id=3
version_revision=3
generation=3
cabinet_name=CAB01
cabinet_id=03
package_code=P
}
}

(2) Example of parameter file for the dcmpack command

PACKAGING_SOURCE{
file_path= pack1.txt;pack2.txt;pack 3.txt;pack4.txt
base_fullpath=C:\dir1
}
PACKAGING_INFORMATION
{
package_name=\FILE\SIZEbytes\CMmonth\CDday\CHhour\CNminute
package_id=\BASE-\BM\BD\BH\BM
version_revision=V0\10:0
generation=G\1
cabinet_name=\PKGID
cabinet_id=\CD
}
INSTALLATION_METHOD{
installation_mode=G
}
USER_PROGRAM_INSTALLATION_CONDITIONS{
{
external_program_executed_before_installation="C:\test B.exe" "-B" bbb
exit=R
action=C
wait=T
}
{
external_program_executed_after_installation=C:\testA.exe -c "a aa"
exit=R
action=C
wait=T
}
{
external_program_error_handler="C:\test E.txt" -c "e e"
exit=R
wait=Y
}
timeout=404
}
SYSTEM_CONDITIONS{
directory=C:\DestDir
condition=H:c>=1000
}
OPTION{
compress=Y
restore=Y
}
FILE_PROPERTIES{
permission=N
}
SCHEDULE{
expiration_date=001231
installation_date_and_time=04020100:50
installation_timing=S
}

(3) Example of parameter file for the dcmcoll command

JOB_ATTRIBUTE{
job_generator=Collect \FILE from \HOST and store it in \ZDIR.
      *If the job name has already been defined in the job storage folder on the server, the job will fail.
job_folder=\\GROUP\\CM\\CD\\CH
      *In this example, folders are created (in four hierarchical layers) under the root folder.
      *When storage (/s) is not specified, the folder is deleted from the newly created hierarchical layers after the job is executed.
}
JOB_DESTINATION{
host_name=dmp492.soft.hitachi.co.jp
      *\HOST in the JOB_ATTRIBUTE tag is replaced with dmp492. host_name=dmp491
group = \group\grp1
      *\GROUP in the JOB_ATTRIBUTE tag is replaced with "group grp1."
group = \group\grp2;\group\grp3
}
SCHEDULE{
installation_timing = S
}
OPTION{
compress=Y
}
USER_PROGRAM_INSTALLATION_CONDITIONS{
      *Always enclose the character string that includes a space in double quotation marks (" ").
external_program_executed_before_installation = "C:\test B.exe"
external_program_executed_after_installation = C:\testA.exe -x "a aa"
external_program_error_handler = "C:\test E.exe"
}
FILE_COLLECTION{
source_path= C:\tmp\SDerror.dir
      *\FILE in the JOB_ATTRIBUTE is replaced with "SD error."
source_path= C:\tmp\SDerror2.dir;C:\tmp\SD error3.dir
dmz_path=  C:\
      *\FILE in the JOB_ATTRIBUTE tag is replaced with "ROOT."
}

15 Troubleshooting

This chapter describes how to check information about problems that occur during the use of the distribution functions that uses Remote Install Manager, and how to handle such problems.

15.1 Taking action if a problem occurs

Take the following actions if a problem occurs while using JP1/IT Desktop Management 2:

Check whether a message is displayed.

If a job caused an error, you can use the Detailed Information dialog box to check details about the error. See 15.2 Troubleshooting jobs and take action according to the instructions.

If a problem occurs, JP1/IT Desktop Management 2 acquires log data. Check the logs, and then take action. For details about how to check JP1/IT Desktop Management 2 - Manager logs, see 15.3.1 Checking log files. For details about how to check JP1/IT Desktop Management 2 - Agent logs, see 15.4.1 Checking log files.

Check whether a problem described in Actions to be taken if normal operation is disabled applies.

For details about problems in JP1/IT Desktop Management 2 - Manager, see 15.3.2 Actions to be taken if normal operation is disabled. For details about problems in JP1/IT Desktop Management 2 - Agent, see 15.4.2 Actions to be taken if normal operation is disabled. Then, take action according to the instructions.

If the problem cannot be solved after actions in steps 1 and 2 are taken, collect maintenance data, and then contact the system administrator.

Log files might contain messages about temporary errors that do not cause problems in operation. For details about messages you are recommended to check, see the manual JP1/IT Desktop Management 2 Messages.

Note:

When you perform GUI operations or execute a command, if a message or dialog box which indicates a disconnection from the server is displayed or output, or GUI operations are terminated, the startup process of the server might be still running after the server PC is started.

15.2 Troubleshooting jobs

This section describes how to check detailed information if a job executed in JP1/IT Desktop Management 2 causes an error, and how to take action.

15.2.1 Checking error job detailed information

If a job executed in JP1/IT Desktop Management 2 causes an error, you can use the Detailed Information dialog box displayed from the Job Status window of Remote Install Manager to check detailed information about the error.

The Job Status window displays job information for each level. To open the Detailed Information dialog box, display the lowest-level information in the Job Status window, select a job in the right pane, and then click View, and then Display Job Detailed Information. Alternatively, double-click the job in the right pane.

For example, for a job related to remote installation, double-click the package (which is the lowest-level information) to open the Detailed Information dialog box.

Figure 15‒1: Job Status window

Figure 15‒2: Detailed Information dialog box

Information in the Description column includes the cause of the error and how to take action. The cause of the error is displayed as a maintenance code.

In the Description field, UNIX might appear in Error function, and a number might appear in Error reason, respectively. In such a case, this 4-digit number indicates the message ID posted by the UNIX version or the Mac version of JP1/IT Desktop Management 2 - Agent. For details about message IDs, see the JP1/IT Desktop Management 2 - Agent Description and User's Guide (For UNIX Systems).

15.2.2 Checking error jobs efficiently

You can use the Job Status window to display only jobs in a specific status. The following describes how to display error jobs only:

In the Job Status window, click View, and then All Job Details.

In the Job Status window, click View, and then Filter.

The Filter dialog box appears.

Figure 15‒3: Filter dialog box

Under Job status, select the Error check box only.

This setting allows the Job Status window to only display error information for jobs under the selected level. Thus, you can check error jobs more easily.

Double-click an error job to open the Detailed Information dialog box, in which you can check details about the error.

15.3 Troubleshooting JP1/IT Desktop Management 2 - Manager

This section describes how to check information if a problem occurs in JP1/IT Desktop Management 2 - Manager, and how to take action.

15.3.1 Checking log files

JP1/IT Desktop Management 2 - Manager acquires log data for each event that occurred. Users can check the following two types of logs:

Windows event log

MAIN.LOG file

Use the Windows Event Viewer to check the Windows event log. Use a text editor to check the MAIN.LOG file, which is stored in JP1/IT Desktop Management 2 - Manager-installation-directory\mgr\log. The following describes each log file.

(1) Checking the Windows event log

You can use the Event Viewer to check the event log data acquired while using JP1/IT Desktop Management 2 - Manager.

In the Log menu of the Event Viewer, you can select Select Computer to check events of other hosts running Windows. For details about how to use the Event Viewer, see the Windows documentation or Help.

Numbers (event IDs) displayed in the event column in the Event Viewer are equivalent to message IDs. The following describes the meanings of the numbers.

Table 15‒1: Event IDs and their meanings (for JP1/IT Desktop Management 2 - Manager)

Event ID

Description

0 to 999

Windows interface-related

1000 to 1999

TCP/IP-related

7000 to 7999

Installation-related

In the Event Viewer window, double-click an event to display a detailed description of that event. For example, if a system error occurred due to insufficient disk space on the managing server, relay system, or management relay server, a message indicating insufficient disk space is output to the Event Viewer system log. In this case, free up enough disk space by, for example, deleting unnecessary files, and then retry the operation.

Depending on the event, memory dump information might be output in event details. If you contact us about JP1/IT Desktop Management 2 errors, also please provide us with this memory dump information also.

For details about event log messages output by JP1/IT Desktop Management 2, see the manual JP1/IT Desktop Management 2 Messages.

(2) Checking the MAIN.LOG file

JP1/IT Desktop Management 2 acquires log data also in the MAIN.LOG file. The following shows the file format.

Figure 15‒4: MAIN.LOG file format

The meanings of the message type and function type displayed in the MAIN.LOG file are as follows.

Table 15‒2: Message types in the Main.LOG file (for JP1/IT Desktop Management 2 - Manager)

Message type

Meaning

Informational

Information message

Warning

Warning message

Error

Error message

Table 15‒3: Function types in the Main.LOG file (for JP1/IT Desktop Management 2 - Manager)

Function type

Meaning

TCP/IP

Interface with TCP/IP

System

Interface with Windows

Server

JP1/IT Desktop Management 2 event

15.3.2 Actions to be taken if normal operation is disabled

While you are using JP1/IT Desktop Management 2 - Manager, normal operation might be disabled or an error might occur. The following describes possible problems and actions to be taken:

(1) Job execution does not proceed

If the job execution does not proceed, the possible reasons are as follows:

(a) The local host name of the agent does not match the destination specified on the managing server

If the agent name is different from the name specified for the system configuration or destination of the managing server, remote installation does not terminate. In this case, JP1/IT Desktop Management 2 - Manager and JP1/IT Desktop Management 2 - Agent cannot output an error to their logs because the products cannot determine whether the intended destination is specified when the job is executed. The executed jobs are displayed in Job Status. Check Job Status to see if an intended destination is specified for the executed job or if the name of the agent is correct.

(b) Destinations with the same name and different host IDs exist

The products cannot determine whether the intended destination is specified when the job is executed. If destinations with different host IDs but the same host name exist, the job might be executed for a non-existent destination. Check Job Status to see if an intended destination was specified when the job was executed.

Also, if agents with the same name exist, the job might not terminate because a different destination is specified for the job.

In this case, execute the resetnid command on the agents that have the same name. For details about this command, see 6.1.5 Example of maintenance of system configuration information.

(c) The user has not logged on to the computer

Even if the computer is running, a job in GUI installation mode is not executed unless the user has logged on. In this case, the job status in Remote Install Manager goes up to 70% but stops there. The user might have not logged on to the terminal where the agent is located. Check if the user has logged on to that terminal.

(d) An external program monitoring time is not set

If an external program monitoring time is not set, the job waits endlessly because control does not return from the external starting program. If the executed external program does not return any response, the agent continues to wait for the response. You can look at USER_CLT.LOG of the agent to see if it received any response. If a KDSF0094-I message is not followed by a KDSF0095-I message, the agent is waiting for a response from the external program.

Set the external program monitoring time on the External Program page in the JP1/ITDM2 Packaging dialog box.

(e) Settings in the file for connection destinations or the information file for higher connection destinations are not correct

If the settings in the file for connection destinations or the information file for higher connection destinations are not correct, job results cannot be reported because JP1/IT Desktop Management 2 - Agent cannot connect to a higher server. In this case, the agent fails to connect to JP1/IT Desktop Management 2 - Manager, and therefore JP1/IT Desktop Management 2 - Manager cannot log the result. Look at USER_CLT.LOG of the target agent to see if the agent can communicate with the destination. If necessary, revise the settings in the file for connection destinations or the information file for higher connection destinations.

(f) ITDM-compatible distribution is being performed on an agent

A job cannot be executed at the same time with ITDM-compatible distribution on an agent. Therefore, if ITDM-compatible distribution is being performed on the agent, the status of the job might remain as Waiting for transmission. In this case, you cannot notice the status even when you see the JP1/IT Desktop Management 2 - Manager log. So go to the Tasks window of the Distribution (ITDM-compatible) module to check that the relevant agent is not running any task.

(g) Processing after remote installation or processing of an AIT file does not terminate normally

If processing after remote installation or AIT file processing does not terminate normally, installation on the agent is placed in the endless wait state.

If remote installation does not complete, RegisterWindowMessage might not have been issued when the AIT file processing ended. In this case, because JP1/IT Desktop Management 2 - Manager does not receive the result of the job, you cannot see the result even if you check the JP1/IT Desktop Management 2 - Manager log. Look at USER_CLT.LOG of the target agent to see if the installation process is being performed.

(h) A user program started before or after installation has not terminated

If installation has completed on the agent but the job progress indicates 70% on the managing server, it is assumed that a user program, started before or after installation, has not terminated yet. As with (d) An external program monitoring time is not set, look at USER_CLT.LOG of the agent to check the situation.

(2) A job fails

If a remote installation job causes an error, the cause of the error is displayed as a maintenance code. In the Job Status window, open the Detailed Information dialog box to check the maintenance code.

(3) The relay system contains a job but does not contain a package

Packages stored in the relay system are automatically deleted when a certain period of time has passed. If you do not specify the expiration date during packaging or job creation, a package is deleted the next day of the remote installation. Even if you specify the expiration date, the package is deleted if the next day of the remote installation is a holiday or if the agent has not been turned on for several days. This results in a situation where the relay system contains a job but does not contain a package.

To prevent such a problem, specify the expiration date of a package with due consideration during packaging or job creation. However, specifying an expiration date that is too long causes memory compression.

The following maintenance code is displayed.

Maintenance code: 300097030000

(4) A space character will be added at the end of the package or not

When a package information is notified from an agent other than by the execution of Install package jobs, there are two cases that a space character will be added at the end of the package or not.

To resolve the above symptom, execute Update Device Details to all agents.

(5) Space characters contained in the package name of Hitachi Program Product which is installed on an agent might be deleted

Space characters contained in the package name of Hitachi Program Product, which is installed on an agent, might be deleted.

Space characters in the package name will be deleted and the package name is stored when the following conditions are all met:

Execute packaging of the Hitachi program product without changing the package name but with the default name.

Distribute (ITDM-compatible) the package by using the Install package job from the Manager.

To resolve the above symptom, execute Update Device Details to all agents.

15.4 Troubleshooting JP1/IT Desktop Management 2 - Agent

This section describes how to check information if a problem occurs in JP1/IT Desktop Management 2 - Agent, and how to take action.

15.4.1 Checking log files

If a problem occurs, JP1/IT Desktop Management 2 - Agent acquires log data. Check the logs, and then take action. You can view the log contents for each PC.

JP1/IT Desktop Management 2 - Agent collects the following three types of log data about the distribution function, by using Remote Install Manager:

Agent basic log (USER_CLT.LOG file)

Log data for the entire JP1/IT Desktop Management 2 - Agent system (MAIN.LOG file)

Log data relating to automatic change of connection destinations (USER.LOG file)

Use a text editor to check log files because they are stored in JP1/IT Desktop Management 2 - Agent-installation-directory\log.

The following describes each log file:

(1) Agent basic log

Basic log messages about agent operations are output to the USER_CLT.LOG file for each PC. We recommend that you first view this file to check the agent operation. This file contains simple messages indicating that each process has started or stopped. If a process fails, the cause of the error is also output to this file.

The following operations cause data to be output to the USER_CLT.LOG file:

Starting and stopping products and processes

Logon and logoff

Receiving a job execution request

Polling

Receiving and executing jobs

Downloading packages

Uploading a file

Automated registration of system configuration information

Registration in and unregistration from an ID group

Packaging

Internal error and application exception

For details about the file format and messages, see the manual JP1/IT Desktop Management 2 Messages.

(2) Log data for the entire JP1/IT Desktop Management 2 - Agent

Log data for the entire JP1/IT Desktop Management 2 - Agent system is collected in the MAIN.LOG file.

(a) Checking the MAIN.LOG file

For each PC, JP1/IT Desktop Management 2 - Agent acquires log data also in the MAIN.LOG file. The following shows the file format.

Figure 15‒5: MAIN.LOG file format

The meanings of message type and function type displayed in the MAIN.LOG file are as follows.

Table 15‒4: Message types in the Main.LOG file (for JP1/IT Desktop Management 2 - Agent)

Message type

Meaning

Informational

Information message

Warning

Warning message

Error

Error message

Table 15‒5: Function types in the Main.LOG file (for JP1/IT Desktop Management 2 - Agent)

Function type

Meaning

Package

During packaging (error in JP1/IT Desktop Management 2 - Agent)

Install

During installation (error in JP1/IT Desktop Management 2 - Agent)

Setup

During installation in GUI installation mode (error in JP1/IT Desktop Management 2 - Agent)

TCP/IP

Interface with TCP/IP

System

Interface with Windows

User

User log (output from the LogFile function of the installation script)

Server

During relay (error in JP1/IT Desktop Management 2 - Agent)

(3) Log data relating to automatic change of connection destinations

If the connection destination of an agent is automatically set or changed based on the file for connection destinations or information file for higher connection destinations, log data for each PC is collected in the USER.LOG file. The following shows the format of the USER.LOG file.

Figure 15‒6: USER.LOG file format

The following shows the meaning of message text displayed in the message is as follows:

Message text

Meaning

Match [smallest-ID-address]-[largest-ID-address]:Change [old-connection-destination:product-type-of-old-connection-destination]->[new-connection-destination:product-type-of-new-connection-destination]

The connection destination of the agent was changed normally.

If the connection destination is the management server specified in the ITDM section of the file for connection destinations, the displayed product type is itdm.

If the connection destination is the higher distribution system (using Remote Install Manager) specified in the DM section of the file for connection destinations or information file for higher connection destinations, the displayed product type is netmdm or netmdmw.

Match [smallest-ID-address]-[largest-ID-address]:No Changed [existing-connection-destination:type-of-existing-connection-destination]#

The connection destination that has already been set matches the definition in the information file for higher connection destinations. The connection destination does not change.

No Match IP Address List, No Changed [existing-connection-destination: product-type-of-existing-connection-destination]

The IP address of the agent is not found in the range defined in the file for connection destinations or the information file for higher connection destinations. The connection destination does not change.

If the connection destination is the management server specified in the ITDM section of the file for connection destinations, the displayed product type is itdm.

If the connection destination is the higher distribution system (using Remote Install Manager) specified in the DM section of the file for connection destinations or information file for higher connection destinations, the displayed product type is netmdm or netmdmw.

Section is not available:"[specified-value]" :LineNo[line-number]

In the line [line-number] in the file for connection destinations, an invalid section is specified. The definition of this line is invalid.

Not exist No.[order-of-the-item] Value: LineNo[line-number]

In the line [line-number] in the file for connection destinations or the information file for higher connection destinations, the nth item (n is indicated by order-of-the-item) is not specified. The definition of this line is invalid.

IP Address is not available:"[specified-value]" :LineNo[line-number]

In the line [line-number] in the file for connection destinations or the information file for higher connection destinations, an invalid IP address is specified. The definition of this line is invalid.

Higher manager value is over 64 character:"[specified-value]" :LineNo[line-number]

In the line [line-number] in the DM section of the file for connection destinations or in the information file for higher connection destinations, more than 64 single-byte characters are specified as the connection destination. The definition of this line is invalid.

Higher manager value is over 255 character:"[specified-value]" :LineNo[line-number]

In the line [line-number] in the ITDM section of the file for connection destinations, more than 255 single-byte characters are specified as the connection destination. The definition of this line is invalid.

Connection type value is not "netmdm" or "netmdmw":"[specified-value]" :LineNo[line-number]

In the line [line-number] in the DM section of the file for connection destinations or in the information file for higher connection destinations, a value other than netmdm and netmdmw is specified as the device type of the connection destination. The definition of this line is invalid.

Match [smallest-ID-address]-[largest-ID-address]:Change Multicast IP Address [old-multicast-address]->[new-multicast-address]

The multicast address of the agent was changed normally.

Match [smallest-ID-address]-[largest-ID-address]:No Changed Multicast IP Address [multicast-address]#

The multicast address that has already been set matches the definition in the information file for higher connection destinations. The multicast address does not change.

Multicast IP Address is not available:"[multicast-address]":LineNo[line-number]

In the line [line-number] in the DM section of the file for connection destinations or in the information file for higher connection destinations, an invalid multicast address is specified. The definition of this line is valid, except for the multicast address setting.

Multicast IP Address is under 224.0.0.0:"[specified-value]":LineNo[line-number]

In the line [line-number] in the DM section of the file for connection destinations or in the information file for higher connection destinations, a multicast address smaller than 224.0.0.0 is specified. The definition of this line is valid, except for the multicast address setting.

Multicast IP Address is over 239.255.255.255:"[specified-value]":LineNo[line-number]

In the line [line-number] in the DM section of the file for connection destinations or in the information file for higher connection destinations, a multicast address greater than 239.255.255.255 is specified. The definition of this line is valid, except for the multicast address setting

Use Option "MultiBoard Environment": Not Execution

Automatic change of connection destinations is disabled because the network adapter has been configured during setup of the agent.

Match [smallest-ID-address]-[largest-ID-address]:Clear SubHostName [registry-number]#

The connection destination that has already been set and that does not match the definition in the information file for higher connection destinations was deleted from the registry.

Match [smallest-ID-address]-[largest-ID-address]:Clear SubServiceName [registry-number]#

For the connection destination that has already been set, the device type that does not match the definition in the information file for higher connection destinations was deleted from the registry.

Match [smallest-ID-address]-[largest-ID-address]:Changed Multi Server Option [YES|NO]

Settings to perform polling for multiple higher systems were changed normally.

If polling to multiple higher systems is performed, YES is displayed. If not, NO is displayed.

#

This message is not output for changes made by using the file for connection destinations.

15.4.2 Actions to be taken if normal operation is disabled

While you are using JP1/IT Desktop Management 2 - Agent, normal operation might be disabled or an error might occur. The following describes possible problems and actions to be taken:

(1) Communication with a higher system is disabled

If a job causes an error, the agent might not be able to communicate with a higher system normally. Use the following methods to make sure that the communication environment has been set up correctly:

Use a ping command to check whether communication with the higher system is possible.

To check the current TCP/IP communication environment settings, execute the IPCONFIG /ALL command from the command prompt.

To check only the host name, execute the HOSTNAME command from the command prompt.

(2) Installation or packaging fails

If an attempt to install a package or perform packaging fails, check whether there is sufficient disk space. For details about the disk space requirement, see the JP1/IT Desktop Management 2 Overview and System Design Guide.

(3) Jobs cannot be executed

Jobs can be executed only for managed devices. Use window operation to confirm that the device for which you want to execute a job is a managed device.

16 Remote Installation Using an AIT File

When JP1/IT Desktop Management 2 remotely installs software onto computers, user response to the installer can be automated by using an AIT file. This chapter describes the AIT file and how to perform remote installation by using the AIT file. The chapter also gives some cautionary notes on creating and using AIT files.

16.1 What is the AIT file?

An AIT file contains a script that automatically responds to a software installer. If you package an AIT file together with the software you want to distribute, and then perform remote installation of the package, the software will automatically be installed on the destination computers. Users at the destination computers do not need to respond to the installer.

An AIT file is needed when you want to remotely install third party's software or a user program that requests the users at the clients to respond to the installer. You can create an AIT file by using the Automatic Installation Tool, which is a component of JP1/IT Desktop Management 2.

The following figure shows an overview of the remote installation by using an AIT file.

Figure 16‒1: Remote installation using an AIT file

16.2 Procedure for remote installation using an AIT file

The following figure shows the procedure for using an AIT file for remote installation.

Figure 16‒2: Procedure for remote installation using an AIT file

16.2.1 Creating an AIT file and a program product ID file

To create the AIT file for the software you want to distribute, you need to check the procedure for installing the software. Based on the procedure you checked, create the AIT file that has the system automatically responding to the installer. AIT files are created in the AIT language specific to the Automatic Installation Tool.

When you create an AIT file, you must also create a program product ID file, which contains information that associates the AIT file with the software to be distributed. The program product ID file must be named PPDEFAIT.DMP and must be stored in the predefined location.

For details about how to create an AIT file and a program product ID file, see Chapter 17. Creating an AIT File and subsequent chapters.

16.2.2 Storing the created files

Place the program product ID file in the following directory at the Packager PC:

Packager-installation-directory\DMPRM\PPDEFAIT.DMP

If using a user-created AIT file, place it in the directory at the Packager PC specified when setting the program product ID file.

16.2.3 Packaging

After placing the AIT file and program product ID file in the appropriate locations, use the Packager to package the software that you want to distribute.

During packaging, the values defined in the AIT file and program product ID file are displayed for Package ID, Version, and Product on the Packaging Information page in the JP1/ITDM2 Packaging dialog box. You cannot change the values of these items in this dialog box.

The JP1/ITDM2 Packaging dialog box also displays other information defined in the AIT file as shown below. You can change the values of this information during packaging or remote installation.

Installation directory

Organization

User name

Serial number

Icon group

If the user at a target computer responds to the dialog box, or uses the keyboard or mouse during installation, the information displayed in the installer window might differ from the information expected by the AIT file. As a result, remote installation based on the AIT file might stop. You can set a time-out to cancel the remote installation forcibly if a length of time elapses after the installer begins to wait for a user response.

Typically, you should set the time period about three times longer than that required to install software to be distributed.

For details about packaging, see 7.1 Packaging method and 7.2 Specifying package details.

16.2.4 Executing remote installation

Use the Remote Install Manager to create and execute a job to distribute software. For details about how to use the Remote Install Manager, see the 7.3 Performing remote installation.

Important

In UNIX systems, a remote installation job using an AIT file results in an error.

16.3 Notes on creating and using AIT files

This section gives notes on creating and using AIT files.

AIT files do not support Web pages and software created in Java or ActiveX.

If API functions that manipulate the registry key HKEY_CURRENT_USER are defined in an AIT file, the user of each computer on which remote installation is to be performed must have logged on as a member of the Administrators group.

Such a user only can access HKEY_CURRENT_USER. If the client user is not a member of the Administrators group, the target registry key of the API functions is automatically changed to HKEY_USERS\.DEFAULT. This change may cause installation to fail.

However, if the change of the target registry key does not affect any operations of the software being installed, the installation will continue.

You might want to use an AIT file to remotely install a package that requires restarting the target computer after installation. In this case, use an AIT file that is set to terminate the installer without restarting the target computer. For remote installation to end successfully, the target computer must be restarted by the package settings.

If you specify 64-bit-related data (registries, folders, or files) in the following categories of API arguments and perform operations in the following operating systems, the target data for APIs might be changed (redirected) to the corresponding 32-bit-related data: the 64-bit edition of Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008 R2.

Registry operations

Directory operations

File operations

INI file operations

When you perform a remote installation by AIT, the API of AIT for window operation might not be able to set a focus on the application. To work around this symptom, execute either of AIT_Exec() and AIT_ExecCommand() first and then use AIT_PlayKey(), which is a recorder operation API, to simulate the pressing of the Alt + Tab keys to move the focus from the desktop.

17 Creating an AIT File

The Automatic Installation Tool provides an integrated environment for creating an AIT file. This chapter describes how to use the Automatic Installation Tool to create an AIT file.

17.1 Overview of the Automatic Installation Tool

This section gives an overview of the functionalities of the Automatic Installation Tool, and explains how to start and terminate it.

17.1.1 Functionalities of the Automatic Installation Tool

The Automatic Installation Tool provides the following functionalities for creating AIT files:

The Edit window for creating and editing an AIT file. This window provides cut, copy, paste, indentation, and other text editing functionalities.

The Window Properties tool for acquiring the properties of installer windows. You can copy the acquired properties on the Clipboard, and can use them as arguments for the API functions used in the AIT file.

The Recorder functionality for recording the installation operations you actually performed. This functionality lets you automatically generate the AIT file that simulates your operations on the installer.

The Syntax Check functionality for checking whether the AIT file meets the AIT language specifications. If this functionality detects errors, it displays them on a window.

The Execute functionality for replaying the script in the AIT file after conducting a syntax check.

The Debug functionality for helping detect and correct syntax errors. In the debug mode, you can stop executing the script in the AIT file at each breakpoint you set or at each statement. Moreover, you can check the values set in variables and update them during execution of the AIT file.

The API (Application Programming Interface) specific to the Automatic Installation Tool. This API allows you to perform various operations such as replay of the installation script, and operations on the registry, files, and text.

Functionality for creating a program product ID file, which associates an AIT file with the software to be distributed.

17.1.2 Starting and terminating the Automatic Installation Tool

To start the Automatic Installation Tool, from the Start menu, select JP1_IT Desktop Management 2 - Agent, Administrator Tool, and then Automatic Installation Tool. The following JP1/ITDM2 Automatic Installation Tool window appears.

Figure 17‒1: JP1/ITDM2 Automatic Installation Tool window

To terminate the Automatic Installation Tool, from the File menu, choose Exit.

Note that to perform recording in JP1/IT Desktop Management 2 - Agent, you must open the JP1/ITDM2 Automatic Installation Tool window with the necessary permissions to execute the program. This restriction applies to JP1/IT Desktop Management 2 - Agent for any of the following OSs: Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008 R2.

Furthermore, these versions of JP1/IT Desktop Management 2 - Agent allow you to open multiple instances of the JP1/ITDM2 Automatic Installation Tool window at the same time. However, when recording or debugging, use a single window.

17.2 Structure of an AIT file, and procedure for creating it

Normally, you use the following procedure to create an AIT file. In most cases, you will need to repeat this procedure several times to complete the desired AIT file.

Figure 17‒2: Procedure for creating an AIT file

After you use the Recorder to record installation operations, if you use the Package Information tool to generate the PACKAGE_INFO section, an AIT file with the structure shown in the following figure is automatically generated. You can use this file as a model file to create a new AIT file. Normally, you modify the shaded portions in this file to complete the AIT file.

Figure 17‒3: Structure of an AIT file

As shown in Figure 16-3, the AIT file consists of four sections. All the sections are required. You cannot change the order of the sections. The following gives an overview of these sections.

PACKAGE_INFO section

This section contains the package information and setup information for the software to be distributed. You can manually complete this section, but you can also use the Package Information tool that automatically generates this section.

DEFINE section

This section defines and initializes the variables that may be used in the MAIN and ERROR sections. No variables can be defined in sections other than the DEFINE section. If you want to add variables in the MAIN and ERROR sections or want to change initial values of variables in the MAIN and ERROR sections, you have to modify this section.

MAIN section

This section contains the operations on the windows output by the installer. You must manually modify this section automatically generated by the Recorder to code the operations on all the installer windows. You can also set return codes for the results of installation.

ERROR section

If an internal error occurs during execution of the AIT file, control over the execution moves to this section. If you want to change the behavior when an error has occurred, modify this section.

You can write comments in the AIT file. The AIT language is not case sensitive. For details about AIT files, see Chapter 18. AIT Language Reference.

Although you can manually create a program product ID file, you can also use the Package Information tool to conveniently create the program product ID file. This is possible because the tool can generate the file when the PACKAGE_INFO section is generated.

The program product ID file generated by the Package Information tool is assigned the name PPDEFAIT.DMP and stored in JP1/IT-Desktop-Management-2-installation-folder\DMPRM.

17.3 Checking the sequence and properties of installer windows

Start the installer of the software you want to distribute to check the installation procedure. You have to check the process of installation in each OS for the following items, and record the installation procedures on paper:

Sequence and properties of installer windows

Properties of dialog boxes

To view those attributes, you can conveniently use the Window Properties tool of the Automatic Installation Tool. The Window Properties tool allows you to obtain the following GUI properties of windows and controls:

Window property

Description

Window text

Caption of the window or control

Class name

Class name of the window or control

Module name

Application that opened the window

Control ID

ID of the window or control

Control type

Type of the control such as window and button

Associated label

The associated label of a control is the text that immediately precedes that control in the tab order. If no such text exists, the control does not have an associated label.

Enabled

Identifies whether the window or control is enabled.

Visible

Identifies whether the window or control is visible.

You can pass these properties to the API functions used in the AIT file in order to identify windows and controls.

17.3.1 Items you should check

Check the operations that the installer requests you to perform, including the sequence of them. Manually install the software to identify the installation procedure, and create a list of the items shown below.

Note that the installation operations may differ depending on the installation method and the status of the target PC (such as the OS type, free hard disk space, available memory, and installed software). Conduct checks carefully.

There are some programs that require the user to restart the operating system during installation. However, the AIT file does not support operations after a system restart. Therefore, you only have to check the installation operations before the operating system is restarted.

Window text

Write down the window text you checked using the Window Properties tool.

Class name

Write down the class name you checked using the Window Properties tool.

Control ID

Write down the control ID you checked using the Window Properties tool.

Control type

Write down the control type you checked using the Window Properties tool.

Operations

Write down the operations (including clicking the OK button) on the dialog box.

Note

Write down a comment or note.

The following is an example of the results of checking the procedure for installing Adobe Reader 6.0. N/A in the Control ID column indicates that no control ID is used.

Table 17‒1: Results of checking the Adobe Reader 6.0 installation procedure

#

Window text

Class name

Control ID

Control type

Operations

Note

1

Adobe Reader 6.0 - Setup

MsiDialogNoCloseClass

N/A

Window

The Next button is clicked.

When the Next button exists.

2

Adobe Reader 6.0 - Setup

MsiDialogNoCloseClass

N/A

Window

The Install button is clicked.

When the Install button exists.

3

Adobe Reader 6.0 - Setup

MsiDialogNoCloseClass

N/A

Window

When the window appears for the first time, the Browse button is clicked.

When the window appears next, the Next button is clicked.

When the Change Destination Folder button exists.

4

Adobe Reader 6.0 Installer Information

MsiDialogNoCloseClass

N/A

Window

The No button is clicked on the dialog box for restart confirmation.

-

Legend:

-: Not applicable

17.3.2 Acquiring properties of installer windows

The following explains how to use the Window Properties tool to acquire the properties of the installer windows.

(1) Acquiring the properties of a window or control

From the Tools menu, choose Window Properties.

The Window Properties dialog box appears.

Activate the software for which you want to acquire the properties.

Make sure that both the window you want to check and the Window Properties dialog box are displayed on the desktop.

Drag and drop the Finder icon () onto the window or control you want to check.

The Window Properties dialog box displays the properties of the window or control.

Figure 17‒4: Window Properties dialog box

You can copy the properties displayed in the Window Properties tool to the Clipboard. To copy them, click in the Window Properties dialog box. The attributes are copied as follows:

Window text: Adobe Reader 6.0 - Setup

Class name: MsiDialogNoCloseClass

Module name: _MSIEXEC.EXE

Control ID: N/A

Control type: Window

Associated label: N/A

Enabled: Yes

Visible: Yes

(2) Displaying properties of associated windows and controls

You can use toolbar buttons on the Window Properties dialog box to display properties of the parent window and its first child window, and of the foreground and background windows. You can also change the display mode of the Window Properties dialog box. The following gives the toolbar buttons on the Window Properties dialog box.

Toolbar button

Description

Jump to Parent Window: Displays the properties of the parent window of the window or control for which you acquired the properties.

Jump to First Child Window: Displays the properties of the first child window of the window or control for which you acquired the properties.

Jump to Preceding Window: Displays the properties of the previous window of the window or control for which you acquired the properties.

Jump to Next Window: Displays the properties of the window following the window or control for which you acquired the properties.

Show/Hide during Find: Hides the Windows Properties dialog box while the Finder icon is being dragged and then displays the dialog box when the icon is dropped. If the dialog box is hidden when you drop the Finder icon, you can select the target control easier.

Display Always in Foreground: Always displays the Window Properties dialog box in the foreground.

17.4 Recording installation operations

Use the Recorder of the Automatic Installation Tool to record installation operations you actually perform. The Recorder records the events issued when you performed installation operations such as pressing keys, clicking mouse buttons, and operations on controls. The Recorder then automatically creates an initial AIT file for simulating user operations. By modifying the initial AIT file, you can create the desired AIT file.

The Recorder automatically generates all the sections except PACKAGE_INFO. The following figure shows an example of an AIT file that is generated when the installation operations for Adobe Reader 6.0 are recorded.

Figure 17‒5: AIT file generated automatically through recording installation operations for Adobe Reader 6.0 (1/3)

Figure 17‒6: AIT file generated automatically through recording installation operations for Adobe Reader 6.0 (2/3)

Figure 17‒7: AIT file generated automatically through recording installation operations for Adobe Reader 6.0 (3/3)

17.4.1 Procedure for recording your installation operations

This subsection explains how to use the Recorder to record the installation operations you actually perform. This recording automatically generates an initial AIT file that you will modify to create the desired AIT file that simulates the user operations.

When you use the Recorder to record installation operations, you can add the AIT_LogMesssage statement in the AIT file. This statement enables the automatic logging functionality that logs messages when recorded operations (events) are replayed. The logged messages will be helpful when you test the AIT file you created. You can test the AIT file by choosing Execute from the Build menu.

While you are recording your installation operations, do not use the mouse whenever possible. Since mouse operations depend on screen coordinates, the simulation may be unable to securely respond to the installer. The Recorder may fail to record operations using the mouse wheel. You should record events by keying-in instead of mouse operations.

Before recording, terminate all the applications other than the Automatic Installation Tool and the installer. Even if you do not carry out operations for other applications, the Recorder records all the displayed windows.

From the Tools menu, choose Recorder.

The Recorder dialog box appears.

Figure 17‒8: Recorder dialog box (start recording)

Select the Add logging check box. When the installer is not activated yet, specify the executable file of the installer in Installer name.

Installer name

In the Installer name text box, you can specify the executable file of the installer of the software for which you want to record the installation operations. When you leave this text box blank, you must activate the installer in advance.

Add logging

When this check box is selected, the AIT_LogMesssage statement is added to the AIT file. When this statement is added, the Automatic Installation Tool logs errors and informational messages while simulating the user operations based on the AIT file.

When this check box is not selected, the AIT_LogMesssage statement is not added to the generated AIT file.

Click the Start button.

The subsequent user operations will be recorded.

When you have specified the installer in Installer name in Step 2, the specified installer is activated.

Carry out actual software installation operations.

The system creates a recording sequence for simulating user operations.

While the JP1/ITDM2 Automatic Installation Tool is recording your operations, its icon is displayed in the Windows taskbar.

When you have finished performing the operations for software installation, click the JP1/ITDM2 Automatic Installation Tool icon on the Windows taskbar.

In general, always use the left mouse button to stop the recording.

In Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, or Windows Server 2008 R2, right-clicking the icon displays a Windows Jump List. Displaying a Windows Jump List is recorded as an installation operation. To prevent this problem, always use the left mouse button to click the Automatic Installation Tool icon.

The following Recorder dialog box appears. At this point of time, the recording is paused.

Figure 17‒9: Recorder dialog box (pause recording)

Click the Stop button.

The recording ends. A message box appears to confirm whether to update the package information.

If you click Yes in this message box, the Package Information dialog box appears. You can then generate the PACKAGE_INFO section. For details about the Package Information dialog box, see 17.5 Generating the PACKAGE_INFO section.

If you click No, the JP1/ITDM2 Automatic Installation Tool window opens, displaying the contents of the generated AIT file.

Figure 17‒10: JP1/ITDM2 Automatic Installation Tool window displaying the contents of an AIT file

From the File menu, choose Save As to save the automatically generated AIT file with any name you like.

The AIT file is saved with the extension .ais. This is an initial AIT file that you will modify as required to create the desired AIT file.

If a restart event occurs during recording, operations carried out by the user during the recording will be held by the Automatic Installation Tool. When you activate the Automatic Installation Tool after the PC is restarted, the Automatic Installation Tool displays a message box to confirm whether to generate the AIT file. Click Yes to generate the AIT file.

17.4.2 Pausing and resuming recording

You can pause and resume recording of installation operations.

From the Windows taskbar, select the JP1/ITDM2 Automatic Installation Tool icon.

You will see the displayed Recorder dialog box, with recording paused.

Figure 17‒11: Recorder dialog box (pause recording)

With recording paused, click the Resume button.

The recording will be resumed. Carry on installation operations.

17.4.3 Recording installation operations requesting the OS to be restarted

The recording of a sequence of installation operations that request the OS to be restarted finishes when the OS is restarted.

To display the generated AIT file, activate the Automatic Installation Tool after the OS is restarted. When the Automatic Installation Tool starts, it displays the message dialog box for selecting whether to enable the recording that was performed before the OS is restarted.

Figure 17‒12: Message dialog box for selecting whether to enable or disable the recording

When you click Yes, the Automatic Installation Tool displays the AIT file that contains the operations recorded before the OS was restarted.

17.5 Generating the PACKAGE_INFO section

Any AIT file requires the PACKAGE_INFO section in which to specify package information on software to be distributed and information necessary for setup. You can conveniently use the Package Information tool to create and verify the PACKAGE_INFO section.

An AIT file also requires a program product ID file, which associates the AIT file with the software to be distributed. You can use the Package Information tool to generate the program product ID file automatically. For details about how to edit the generated program product ID file, see Appendix F. Editing a Program Product ID File.

This section describes how to use the Package Information tool to generate the PACKAGE_INFO section and a program product ID file.

17.5.1 Procedure for generating the PACKAGE_INFO section and a program product ID file

This subsection explains how to generate the PACKAGE_INFO section and a program product ID file. For details about the PACKAGE_INFO section, see 18.2.1 PACKAGE_INFO.

To generate the PACKAGE_INFO section and a program product ID file:

From the File menu, choose Open to open the AIT file for which you want to generate the package information.

From the Tools menu, choose Package Information.

The Package Information dialog box appears.

Figure 17‒13: Package Information dialog box

If the AIT file already contains the PACKAGE_INFO section, the Package Information dialog box displays the existing values in the PACKAGE_INFO section.

Enter a value for each item.

For any items, you cannot use \n, \r, \t, and other character strings that have special meanings. In the dialog box, you must specify a value for the items marked with an asterisk (*). The following gives the meaning of each item.

Item

Description

Package ID

Specify the package ID with a value from 1 to 44 bytes. You can use upper-case alphanumeric characters, a hyphen (-) and an underscore (_).

Product

Specify the package name with a value from 1 to 50 bytes. You cannot use a backslash (\) and a semicolon (;).

Version

Specify the version or revision of the software with a value from 1 to 6 bytes. You can use upper-case letters, numbers, and a slash (/).

Installer name

Specify the name of the installer to be used to install the software with a value from 1 to 256 bytes. You cannot use the following symbols:

* " : | < > ?

Install drive

Specify the drive in which to install the software by using two characters: an alphanumeric character and a colon (:)

Install directory

Specify the path name of the directory in which to install the software. Specify the path name with a value from 1 to 128 bytes. The name must start with a backslash (\).

Icon group name

Specify the icon group name of the software with a value from 1 to 40 bytes.

Serial number

Specify the serial number of the software to be installed with a value from 1 to 64 bytes. For software for which a CD key is required during installation, enter the CD key.

English

Select this option button if the software is the English version. Specify the user name and the organization below.

User name

Specify the software owner name with a value from 1 to 40 bytes.

Organization

Specify the company name of the software owner with a value from 1 to 80 bytes.

AIT file path

Specify the full-path name, including the drive name, of the AIT file to be generated with a value from 1 to 256 bytes. You cannot use a semicolon (;).

Package file ID

Specify one or more files that constitute the software to be distributed so that the software can be uniquely identified. Specify a file name that uniquely identifies the software to be distributed with a value from 1 to 477 bytes. When specifying two or more file names, use a semicolon (;) to separate each file name.

When all of the specified files exist during packaging, the Package Information tool assumes that the software that includes the files is to be distributed by using the AIT file.

Note that if you generate the PACKAGE_INFO section without specifying either AIT file path or Package file ID, the Package Information tool does not generate a program product ID file.

For details about how to specify Installer name and Package file ID, see 17.5.2 Specifying the installer and the files for identifying the software to be distributed.

Click the Generate Package Info button.

The Package Information tool checks the length, characters, and other items to validate the specified information in the same way as the Packager. The PACKAGE_INFO section is generated or updated in the AIT file.

PACKAGE_INFO

{

PackageID = "ADOBEREADER";

Product = "Adobe Reader 6.0";

Version = "0600";

InstallerName = "AdbeRdr60_enu_full.exe";

InstallDrive = "C:";

InstallDirectory = "'\Program Files'\Adobe'\Acrobat 6.0";

}

In addition, a program product ID file is generated with the information specified in the Package Information dialog box. If a program product ID file already exists, the specified information is added to the existing file.

The generated program product ID file is assigned the file name PPDEFAIT.DMP and stored in JP1/IT-Desktop-Management-2-installation-folder\DMPRM.

From the File menu, choose Save to save the AIT file with the PACKAGE_INFO section generated or updated.

The values entered in the Package Information dialog box are displayed in the JP1/ITDM2 Packaging dialog box during packaging. Among the items displayed in this dialog box, you cannot change the values of the Package ID, Product, and Version. You can change the values of other items during packaging or remote installation.

17.5.2 Specifying the installer and the files for identifying the software to be distributed

The installer name in the AIT file and the file names (for identification) in the program product ID file must be specified with the relative paths from the packaging directory.

The following examples show how to specify the above file names in the AIT file and the program product ID file. In the following examples, suppose the files to be packaged exist at the CD-ROM drive (E:).

When the packaging directory contains no subdirectories

Packaging directory:

E:\

Installation program name you specify as package information in the AIT file:

setup.exe

File names you specify in the program product ID file:

xxx.ini;yyy.exe

When the packaging directory contains a subdirectory

Packaging directory:

E:\

Installer name you specify as package information in the AIT file:

install\setup.exe

File names you specify in the program product ID file:

xxx.ini;install\yyy.exe

When the packaging directory is a subdirectory

Packaging directory:

E:\disk1

Installer name you specify as package information in the AIT file:

setup.exe

File names you specify in the program product ID file:

xxx.ini;yyy.exe

When the packaging directory is a subdirectory that contains a subordinate directory

Packaging directory:

E:\disk1

Installer name you specify as package information in the AIT file:

install\setup.exe

File names you specify in the program product ID file:

xxx.ini;install\yyy.exe

17.6 Editing an AIT file

After an initial AIT file has been generated automatically by recording, you need to edit it. To edit an AIT file, you have to understand the API functions for window processing that are frequently used in AIT files.

This section describes the API functions for window processing, then explains required manual modifications.

17.6.1 Window processing

During remote installation, the user at a destination computer might respond to dialog boxes or use the keyboard or mouse by mistake. If so, remote installation might stop. In the MAIN section, you must code the main processing, while taking possible interruptions into consideration.

The following figure shows the window processing in an AIT file:

Figure 17‒14: Window processing in an AIT file

The AIT file is coded to repeat a loop that finds and operates windows. Therefore, if the user at the computer responds to Window A by mistake and Window B appears as a result, the Automatic Installation Tool might skip the processing for Window A and execute the processing for Window B instead.

When creating an AIT file, you check the windows displayed during installation, and list the operations on the windows. These operations are coded in a loop. This processing structure allows you to complete the processing regardless of the order of the output windows and user operations.

In an AIT file, the processing for windows must be sequentially coded in the loop. The processing of each window is coded as a set of the following processes:

Finding a window

Operating the found window

These processes are coded using the API functions listed in Tables 16-2 and 16-3.

Table 17‒2: API functions for finding a window

API

Description

AIT_FocusWindow

Finds a window, and sets the focus on the window.

AIT_CtrlSetFocus

Sets the focus on a specific control.

Table 17‒3: API functions for operating a window

API

Description

AIT_VerifyExistence

Checks whether the window contains controls such as buttons and check boxes.

AIT_VerifyEnabled

Checks whether the control is enabled.

AIT_VerifyPos

Identifies the position of the control.

AIT_PlayKey

Simulates keyboard operations such as pressing Enter.

Note on window processing

This note applies when you use an AIT file to remotely install software in any of the following OS environments: Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, or Windows Server 2008 R2. In this case, the APIs for window operations (AIT_FocusWindow and AIT_CtrlSetFocus) might not be able to set the focus in the application. In such cases, execute either of the API functions AIT_Exec and AIT_ExecCommand, which are used for recorder operations, and then use AIT_PlayKey to simulate the pressing of the Alt + Tab keys to move the focus from the desktop.

The following describes the roles of these API functions, and explains how to use them. For details about the parameters and return values for the API functions, see Chapter 19. API Function Reference.

(1) AIT_FocusWindow

AIT_FocusWindow finds a window, and sets the focus on the window. Before starting the operations on the target window, you must find it and set the focus on it.

When you find a window, you need to specify the window text and class name of the window as parameters. To identify the window text and the class name, you can conveniently use the Window Properties tool. For this purpose, you can also use the codes in the AIT file generated automatically by the Recorder.

If the target window is found, the API function returns the handle to the window; otherwise, it returns 0.

The following gives an example of using AIT_FocusWindow.

Figure 17‒15: Example of using AIT_FocusWindow

(2) AIT_CtrlSetFocus

AIT_CtrlSetFocus sets the focus on a specific control. If the window contains multiple controls, use AIT_CtrlSetFocus to set the focus on the target control, then simulate user operations.

The target control is specified with its caption or control ID, as well as the control type (such as button or list box).

The following gives an example of using AIT_CtrlSetFocus with the caption of a control specified.

Figure 17‒16: Example of using AIT_CtrlSetFocus

(3) AIT_VerifyExistence

AIT_VerifyExistence checks whether the control exists on the window.

For example, if there are windows that have the same caption, the window found by AIT_VerifyExistence is not always the target window that you want to operate. In such a case, you can use AIT_VerifyExistence to check whether the window contains the desired control, and to determine whether the window is the target to be operated.

The target control is specified with its caption or control ID, as well as the control type (such as button or list box). If the target control exists, this API function returns 1; otherwise it returns 0.

The following gives an example of using AIT_VerifyExistence with the caption of a control specified.

Figure 17‒17: Example of using AIT_VerifyExistence

(4) AIT_VerifyEnabled

AIT_VerifyEnabled checks whether the control is enabled.

For example, suppose buttons are associated with a check box, and they are enabled when the check box is selected and are disabled when it is not selected. In such a case, you can use AIT_VerifyEnabled to check whether the button is enabled. If the button is enabled, a simulation of the actions that occur when a user clicks the button is performed.

AIT_VerifyEnabled is used in combination with AIT_VerifyExistence or AIT_VerifyPos. After the existence of the target control is verified with AIT_VerifyExistence or AIT_VerifyPos, AIT_VerifyEnabled is used to check whether the control is enabled.

The target control is specified with its caption or control ID, as well as the control type (such as button or list box). If the target control is enabled, this API function returns 1; otherwise it returns 0.

The following gives an example of using AIT_VerifyEnabled with the caption of a control specified.

Figure 17‒18: Example of using AIT_VerifyEnabled

(5) AIT_VerifyPos

AIT_VerifyPos checks the tab order of the control. Similar to AIT_VerifyExistence, AIT_VerifyPos is also used to check whether the target control exists. However, if there are controls that have the same caption in the window, the target control cannot be identified by the caption only. In such a case, the target control can be identified by using AIT_VerifyPos with the tab order of the target control specified.

The target control is specified with its caption or control ID, as well as the control type (such as button or list box) and tab order. If the specified tab order matches that of the control, this API function returns 1; otherwise it returns 0.

The following gives an example of using AIT_VerifyPos with the caption of a control specified.

Figure 17‒19: Example of using AIT_VerifyPos

(6) AIT_PlayKey

AIT_PlayKey simulates a keyboard operation.

In this API function, you can specify characters to be entered or keys to be pressed. For example, when the character string abcd is specified, this API function enters it as if you typed. When {ESC} is specified, this API function simulates pressing Esc, and when %(F) is specified, it simulates pressing the Alt+F shortcut key.

The following gives an example of using AIT_PlayKey.

Figure 17‒20: Example of using AIT_PlayKey

(7) Example of automatically generated codes for window processing

In an AIT file automatically generated by the Recorder, window information and your operations on windows are recorded. The following figure shows an example of automatically generated code for window processing.

Figure 17‒21: Example of automatically generated codes for window processing

17.6.2 Automatically generated flags

Operations on different windows that have the same caption are recorded in an AIT file as operations on the same window. In the generated AIT file, the following flags are used to script the operations on windows:

Window flag AITFLAGn (n: 1 or a greater integer)

Event flag AITEVENTFLAGn (n: 1 or a greater integer)

Invalid flag AITIGNORE

The following describes these flags.

(1) Window flag (AITFLAG1n)

Window flags specify the order in which windows will be displayed. The following figure gives an example of generated window flags.

Figure 17‒22: Example of generated window flags

(2) Event flag (AITEVENTFLAGn)

Event flags specify the order in which window operations will be performed. The following figure gives an example of generated event flags.

Figure 17‒23: Example of generated event flags

(3) Invalid flag (AITIGNORE)

The invalid flag suppresses execution of the next operation until a window closes. The following figure gives an example of generated invalid flags.

Figure 17‒24: Example of generated invalid flags

17.6.3 Checking and modifying an automatically generated AIT file

After an AIT file has been generated automatically by the Recorder, you need to check and modify the generated codes in light of the following concerns:

(1) Repeat recording under changed installation conditions

The windows output by the installer vary with the hard disk's free space and OS installation conditions. All windows and events cannot be recorded by one recording cycle. To simulate operations for all windows, you have to repeat recording under changed installation conditions to generate multiple AIT files. The following gives possible installation conditions.

Installation conditions

Description

OS

The windows output by the installer may vary with the installed OS.

PC environment

The windows output by the installer may depend on the hard disk's free space, whether the prerequisite programs have been installed, whether the software is installed for the first time or for upgrading the version, and other target PC environment factors.

User operations

The windows output by the installer may vary depending on the user's operation such as changing the installation directory and canceling installation.

After multiple AIT files are generated according to different installation conditions, extract necessary codes from the AIT files, and combine the codes into one AIT file. Here, the necessary codes mean the codes for simulating operations on different windows output according to installation conditions.

The following figure shows an example of combining multiple AIT files.

Figure 17‒25: Example of combining multiple AIT files

(2) Correctly identify the end of installation operations

The Recorder automatically generates the code of normally terminating installation for the window you operated last during recording. However, the window you operated last is not always the one output at the end of installation.

Suppose that the installer opens a Readme file with Notepad after the installation. In this case, you may close the Readme file at the end of the recording. If you do this, the processing for terminating installation is generated for the operation for closing Notepad. During installation by using an AIT file generated in this way, if you close Notepad before the installation ends, the ongoing installation is terminated.

To avoid this, do not record any operations on windows that appear after the end of the installation. Alternatively, manually modify the AIT file so that Notepad is not closed until the end of the installation. The following gives an example of modifying an AIT file.

Figure 17‒26: Example of modifying an AIT file

If a dialog box that appears during installation and the dialog box that appears at the end of installation have the same caption, the Automatic Installation Tool cannot identify the end of installation correctly. In this case, additionally specify a label or button to differentiate the dialog boxes.

(3) Do not use variable text to identify a window

For identification of a window, you can use not only window text, but also the text of controls on the window as conditions for identifying. However, do not use variable text as conditions for identifying a window.

For example, suppose that a control displays the PC's free disk space in the Available disk space: 2252195 K format. As each PC has a different amount of free disk space, you cannot use the string 2252195 K to identify the window.

In an automatically generated AIT file, if text that varies depending on the PC environment or OS is used to identify a window, delete the text. Alternatively, you should only use constant text (such as Available disk space:) for window identification.

(4) Delete codes for unrelated windows

If applications other than the installer are activated during recording, the Recorder may have recorded codes for windows that are not related to the installer. If such codes have been recorded, delete them.

17.6.4 Linkage with the Packager and Remote Install Manager

During packaging or remote installation, if you change the package information such as Install directory or User name, the PACKAGE_INFO section in the AIT file is updated automatically. However, such information in the MAIN section is not updated. To prevent inconsistency between these sections, instead of hard-coding such information, use the global variables provided by JP1/IT Desktop Management 2 as needed. The following table describes the available global variables for JP1/IT Desktop Management 2.

Global variable for JP1/IT Desktop Management 2

Description

InstallerName

This is the installer name specified in the PACKAGE_INFO section. You cannot change this value during packaging or remote installation.

Note that, during remote installation, this variable contains the installer name including the path name of the installation work directory on the computer. Therefore, the value during remote installation differs from the value during AIT file debugging.

InstallDrive

This is replaced with the installation drive name specified during packaging or remote installation. The default is the installation drive name specified in the PACKAGE_INFO section.

InstallDirectory

This is replaced with the installation directory name specified during packaging or remote installation. The default is the installation directory name specified in the PACKAGE_INFO section.

InstallPoint

This is replaced with a combination of InstallDrive and InstallDirectory, that is, the installation path directory including the drive name.

JUser

This is replaced with the user name specified during packaging or remote installation.

JCompany

This is replaced with the company name specified during packaging or remote installation.

SerialNumber

This is replaced with the serial number specified during packaging or remote installation. It is used to type in the license key.

IconGroupName

This is replaced with the icon group name specified during packaging or remote installation. It is used to change the icon group.

The following figure shows an example of using global variables.

Figure 17‒27: Example of using global variables

17.6.5 Adding the coding for error handling and setting a return code

You need to add error handling to support windows output if an error occurs. Determine whether to continue or abort the installation if an error occurs, and code the error handling according to the determination.

Also, you need to add the coding for setting a return code to indicate whether or not the installation normally terminated. This coding is necessary for checking errors at the managing server. The return code is a two-digit value displayed as the ninth and tenth (from the left) digits of the maintenance code in the Details dialog box.

The following figure shows an example of coding for error handling and setting a return code.

Figure 17‒28: Example of coding for error handling and setting a return code (1/2)

Figure 17‒29: Example of coding for error handling and setting a return code (2/2)

17.6.6 Example of a completed AIT file

The following gives an example of a completed AIT file for remotely installing Acrobat Reader 6.0:

PACKAGE_INFO
{
  PackageID        = "ADOBEREADER";
  Product          = "Adobe Reader 6.0";
  Version          = "0600";
  InstallerName    = "AdbeRdr60_enu_full.exe";
  InstallDrive     = "C:";
  InstallDirectory = "'\Program Files'\Adobe'\Acrobat 6.0";
}
DEFINE
{
  integer iLoopCount = 0;
  integer iLoopMax = 60;
  integer DM_RTN;
  integer WINH;
  integer iCapsLockState;
  integer iNumLockState;
  integer iScrollLockState;
  bool bRtn;
  const integer OK_END = 0;
  const integer NG_END = -1;
  float SLEEP_TIME = 1.0;
  float SLEEP_TIME_RESTART = 10.0;
  float SLEEP_TIME_EVENTS = 0.5;
  integer DirectorySetFlag=0;
  integer InsufficientMemory=0;
  integer InvalidPath=0;
}
MAIN
{
  AIT_SetDefaultWaitTimeout(1.0);
  AIT_DMPSTRC();
  DM_RTN = NG_END;
  iCapsLockState = AIT_GetKeyState(CAPSLOCK);
  iNumLockState = AIT_GetKeyState(NUMLOCK);
  iScrollLockState = AIT_GetKeyState(SCROLLLOCK);
  bRtn= AIT_Exec(InstallerName,SW_SHOWNORMAL);
  if(bRtn == false)
      iLoopCount = iLoopMax;
  Endif;
  while(iLoopCount < iLoopMax)
      if(AIT_FocusWindow("Netopsystems FEAD Optimizer", "#32770") != 0)
          AIT_Sleep(SLEEP_TIME);
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("InstallShield Wizard", "#32770") != 0)
          AIT_Sleep(SLEEP_TIME);
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("Windows Installer", "#32770") != 0)
          AIT_Sleep(SLEEP_TIME);
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("Adobe Reader 6.0 - Setup", "MsiDialogCloseClass") != 0)
          if((AIT_VerifyExistence("&Next >",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&Next >",BUTTON_CTRL)==1))
              if (InvalidPath == 1 || InsufficientMemory == 1)
                  AIT_CtrlSetFocus("&Next >",BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("{ESC}");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              else
                  if (DirectorySetFlag == 0)
                      if((AIT_VerifyExistence("Change &Destination Folder...",BUTTON_CTRL)==1)
                      && (AIT_VerifyEnabled("Change &Destination Folder...",BUTTON_CTRL)==1))
                          AIT_CtrlSetFocus("Change &Destination Folder...",BUTTON_CTRL);
                          AIT_Sleep(SLEEP_TIME_EVENTS);
                          AIT_PlayKey("%(d)");
                          AIT_Sleep(SLEEP_TIME_EVENTS);
                      else
                          if((AIT_VerifyExistence("Re&pair",OPTIONBUTTON_CTRL)==1)
                          && (AIT_VerifyEnabled("Re&pair",OPTIONBUTTON_CTRL)==1))
                              AIT_CtrlSetFocus("Re&pair",OPTIONBUTTON_CTRL);
                              AIT_Sleep(SLEEP_TIME_EVENTS);
                              AIT_PlayKey("{ENTER}");
                              AIT_Sleep(SLEEP_TIME_EVENTS);
                          else
                              AIT_CtrlSetFocus("&Next >",BUTTON_CTRL);
                              AIT_Sleep(SLEEP_TIME_EVENTS);
                              AIT_PlayKey("%(n)");
                              AIT_Sleep(SLEEP_TIME_EVENTS);
                          Endif;
                      Endif;
                  else
                      AIT_CtrlSetFocus("&Next >",BUTTON_CTRL);
                      AIT_Sleep(SLEEP_TIME_EVENTS);
                      AIT_PlayKey("%(n)");
                      AIT_Sleep(SLEEP_TIME_EVENTS);
                  Endif;
              Endif;
          Endif;
          if((AIT_VerifyExistence("&Install",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&Install",BUTTON_CTRL)==1))
              AIT_CtrlSetFocus("&Install",BUTTON_CTRL);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_PlayKey("%(i)");
              AIT_Sleep(SLEEP_TIME_EVENTS);
          Endif;
          if((AIT_VerifyExistence("&Finish",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&Finish",BUTTON_CTRL)==1))
              AIT_CtrlSetFocus("&Finish",BUTTON_CTRL);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_PlayKey("%(f)");
              AIT_Sleep(SLEEP_TIME_EVENTS);
              iLoopCount = iLoopMax;
              if (InvalidPath == 0 && InsufficientMemory == 0)
                  DM_RTN = OK_END;
              Endif;
              continue;
          Endif;
          if((AIT_VerifyExistence("&No",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&No",BUTTON_CTRL)==1)
          && (AIT_VerifyExistence("&Yes",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&Yes",BUTTON_CTRL)==1)
          && (AIT_VerifyExistence("Are you sure you want to cancel Adobe Reader 6.0 installation?",STATIC_CTRL)==1)
          && (AIT_VerifyEnabled("Are you sure you want to cancel Adobe Reader 6.0 installation?",STATIC_CTRL) == 1))
              if (InvalidPath == 1 || InsufficientMemory == 1)
                  AIT_CtrlSetFocus("&Yes",BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("y");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              else
                  AIT_CtrlSetFocus("&No",BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("n");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              Endif;
          Endif;
          if((AIT_VerifyExistence("OK",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("OK",BUTTON_CTRL)==1)
          && (AIT_VerifyExistence("Out of Disk Space",STATIC_CTRL)==1)
          && (AIT_VerifyEnabled("Out of Disk Space",STATIC_CTRL)==1))
              AIT_CtrlSetFocus("OK",BUTTON_CTRL);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_PlayKey("{ENTER}");
              AIT_Sleep(SLEEP_TIME_EVENTS);
              InsufficientMemory = 1;
          Endif;
          if((AIT_VerifyPos("&Change...",BUTTON_CTRL,1)==1)
          && (AIT_VerifyEnabled("&Change...",BUTTON_CTRL, 1) == 1)
          && (AIT_VerifyPos("&Help",BUTTON_CTRL,2)==1)
          && (AIT_VerifyEnabled("&Help",BUTTON_CTRL, 2) == 1)
          && (AIT_VerifyPos("&Space",BUTTON_CTRL,3)==1)
          && (AIT_VerifyEnabled("&Space",BUTTON_CTRL, 3) == 1)
          && (AIT_VerifyPos("< &Back",BUTTON_CTRL,4)==1)
          && (AIT_VerifyEnabled("< &Back",BUTTON_CTRL, 4) == 1)
          && (AIT_VerifyPos("&Next >",BUTTON_CTRL,5)==1)
          && (AIT_VerifyEnabled("&Next >",BUTTON_CTRL, 5) == 1)
          && (AIT_VerifyPos("Cancel",BUTTON_CTRL,6)==1)
          && (AIT_VerifyEnabled("Cancel",BUTTON_CTRL, 6) == 1)
          && (AIT_VerifyPos("Custom Setup",STATIC_CTRL,9)==1)
          && (AIT_VerifyEnabled("Custom Setup",STATIC_CTRL, 9) == 1)
          && (AIT_VerifyPos("Feature Description",BUTTON_CTRL,18)==1)
          && (AIT_VerifyEnabled("Feature Description",BUTTON_CTRL, 18) == 0))
              AIT_CtrlSetFocus(0);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_IMESetOpenStatus(0, false);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_PlayKey("{ESC}");
              AIT_Sleep(SLEEP_TIME_EVENTS);
          Endif;
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("Adobe Reader 6.0 - Setup", "MsiDialogNoCloseClass") != 0)
          if((AIT_VerifyExistence("&Next >",BUTTON_CTRL)==1)
          && (AIT_VerifyEnabled("&Next >",BUTTON_CTRL)==1))
              AIT_CtrlSetFocus("&Next >",BUTTON_CTRL);
              AIT_Sleep(SLEEP_TIME_EVENTS);
              AIT_PlayKey("%(n)");
              AIT_Sleep(SLEEP_TIME_EVENTS);
          Endif;
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("Adobe Reader 6.0 Setup", "MsiDialogCloseClass") != 0)
          if((AIT_VerifyPos("&OK",BUTTON_CTRL,1)==1)
          && (AIT_VerifyEnabled("&OK",BUTTON_CTRL, 1) == 1)
          && (AIT_VerifyPos("&Cancel",BUTTON_CTRL,2)==1)
          && (AIT_VerifyEnabled("&Cancel",BUTTON_CTRL, 2) == 1)
          && (AIT_VerifyPos("&Look in:",STATIC_CTRL,3)==1)
          && (AIT_VerifyEnabled("&Look in:",STATIC_CTRL, 3) == 1)
          && (AIT_VerifyPos("&Look in:",COMBO_CTRL,4)==1)
          && (AIT_VerifyEnabled("&Look in:",COMBO_CTRL, 4) == 1)
          && (AIT_VerifyPos("Up One Level",BUTTON_CTRL,5)==1)
          && (AIT_VerifyEnabled("Up One Level",BUTTON_CTRL, 5) == 1)
          && (AIT_VerifyPos("Create New Folder",BUTTON_CTRL,6)==1)
          && (AIT_VerifyEnabled("Create New Folder",BUTTON_CTRL, 6) == 1)
          && (AIT_VerifyPos("&Folder name:",STATIC_CTRL,8)==1)
          && (AIT_VerifyEnabled("&Folder name:",STATIC_CTRL, 8) == 1)
          && (AIT_VerifyPos("Browse to the destination folder.",STATIC_CTRL,9)==1)
          && (AIT_VerifyEnabled("Browse to the destination folder.",STATIC_CTRL, 9) == 1)
          && (AIT_VerifyPos("Change Current Destination Folder",STATIC_CTRL,10)==1)
          && (AIT_VerifyEnabled("Change Current Destination Folder",STATIC_CTRL, 10) == 1)
          && (AIT_VerifyPos("InstallShield",STATIC_CTRL,12)==1)
          && (AIT_VerifyEnabled("InstallShield",STATIC_CTRL, 12) == 1)
          && (AIT_VerifyPos("InstallShield",STATIC_CTRL,13)==1)
          && (AIT_VerifyEnabled("InstallShield",STATIC_CTRL, 13) == 0))
              if (InvalidPath == 0)
                  AIT_CtrlSetFocus(0);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_IMESetOpenStatus(0, false);
                  AIT_PlayKey(InstallPoint);
                  AIT_PlayKey("{ENTER}");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  DirectorySetFlag = 1;
              else
                  AIT_CtrlSetFocus("&Cancel", BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("{ENTER}");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              Endif;
          Endif;
          iLoopCount=0;
      Endif;
      if(AIT_FocusWindow("Adobe Reader 6.0 Installer Information", "MsiDialogCloseClass") != 0)
          if(AIT_VerifyPos("~Error 1314.The specified path",STATIC_CTRL,1)==1)
              InvalidPath = 1;
              if((AIT_VerifyExistence("&OK",BUTTON_CTRL)==1)
              && (AIT_VerifyEnabled("&OK",BUTTON_CTRL)==1))
                  AIT_CtrlSetFocus("&OK",BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("{ENTER}");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              Endif;
          Endif;
          if(AIT_VerifyExistence("~You must restart",STATIC_CTRL)==1)
              if((AIT_VerifyExistence("&No",BUTTON_CTRL)==1)
              && (AIT_VerifyEnabled("&No",BUTTON_CTRL)==1))
                  AIT_CtrlSetFocus("&No",BUTTON_CTRL);
                  AIT_Sleep(SLEEP_TIME_EVENTS);
                  AIT_PlayKey("n");
                  AIT_Sleep(SLEEP_TIME_EVENTS);
              Endif;
          Endif;
          iLoopCount=0;
      Endif;
      iLoopCount = iLoopCount + 1;
      AIT_Sleep(SLEEP_TIME);
  loop;
  WINH = AIT_RegisterWindowMessage("ITM_REC_QUIT");
  if(WINH != 0)
      AIT_PostMessage(HWND_BROADCAST,WINH,DM_RTN,0);
  Endif;
}
ERROR
{
  DM_RTN = NG_END;
  WINH = AIT_RegisterWindowMessage("ITM_REC_QUIT");
  if(WINH != 0)
      AIT_PostMessage(HWND_BROADCAST,WINH,DM_RTN,0);
  Endif;
}

17.7 Debugging an AIT file

Once you created an AIT file, repeat syntax checks, execution, and debugging to finish a complete AIT file that can simulate user operations correctly. You do not need to compile AIT files.

Note that, depending on the JP1/IT Desktop Management 2 - Agent version, you must open the JP1/ITDM2 Automatic Installation Tool window as a user with Administrator permissions when debugging an AIT file for a program that requires Administrator permissions. This restriction applies to JP1/IT Desktop Management 2 - Agent for any of the following OSs: Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, and Windows Server 2008 R2. If the program can be executed with non-Administrator user permissions, you can debug the AIT file with either type of permissions.

The following figure shows the flow of debugging an AIT file:

Figure 17‒30: Flow of debugging an AIT file

When you open an AIT file with the Automatic Installation Tool, the Build and Debug menus for debugging are enabled.

The Build menu allows you to detect syntax errors in the AIT file and to execute the active (currently opened) AIT file.

The Debug menu allows you to set breakpoints at which you can stop execution of the AIT file. You can use the Watch window to view and update variable values.

These facilities can be used only for the AIT files that have the extension .ais.

Notes on debugging

In the PACKAGE_INFO section, the installer name is specified in InstallerName with a relative path from the packaging directory. During debugging, in the MAIN section, you have to replace the relative path temporarily with the absolute path. After completion of debugging, you must set the original relative path. During syntax checks, however, you do not need to replace the relative path with the absolute path. The following gives an example of replacing the value of InstallerName with the absolute path.

Figure 17‒31: Example of replacing the value of InstallerName with the absolute path

17.7.1 Syntax check and execution

The Automatic Installation Tool provides the Build menu that lets you conduct a syntax check on, or execute, an AIT file.

Syntax Check

This functionality lets you check the syntax of the active (currently opened) AIT file. At the bottom of the Automatic Installation Tool window, a window called the output window appears to display any syntax errors and warning messages.

Execute

This functionality lets you execute the active AIT file. When no syntax errors are detected in the active AIT file, execute it. After the AIT file is executed, the output window displays the exit code. If there were errors during execution, the output window displays the errors and warning messages.

Figure 17‒32: Output window

You can select whether to show or hide the output window by choosing Output in the View menu.

17.7.2 Debugging

To facilitate debugging an AIT file, you can stop execution of the AIT file at specific points. When execution of an AIT file is stopped, you can reference or update the values of variables in the Watch window.

You can stop execute of an AIT file:

at a breakpoint you set;

before the cursor line; or

in units of statements.

(1) Setting breakpoints

Breakpoints are the points at which the debugging process stops. You can set breakpoints in any lines, and can enable or disable them. Breakpoints are marked with circles displayed on the left of the Edit window. Colored circles indicate enabled breakpoints and white circles indicate disabled breakpoints. You can remove unnecessary breakpoints. All breakpoints you set will be cleared when you close the AIT file.

You can add, remove, enable or disable breakpoints by using the Breakpoints Setup or Add/Remove Breakpoint menu.

(a) Using the Breakpoints Setup dialog box to set breakpoints

The following procedure shows how to use the Breakpoints Setup dialog box to add, remove, enable or disable breakpoints.

To use the Breakpoints Setup dialog box to set breakpoints:

Open the AIT file. Then, from the Debug menu, choose Breakpoints Setup.

The Breakpoints Setup dialog box appears.

Figure 17‒33: Breakpoints Setup dialog box

Breakpoint line no.

In this text box, type in the line number of a line where you want to add a breakpoint, and click the Add button. A breakpoint is set on the specified line.

Breakpoints

This list box lists all the breakpoints set in the active AIT file. Breakpoints are indicated with line numbers. When the check box of a breakpoint is selected, the breakpoint is enabled. When the check box of a breakpoint is not selected, the breakpoint is disabled.

Remove button

Clicking this button removes the breakpoints at the lines selected in the Breakpoints list box.

Remove All button

Clicking this button removes all breakpoints you set.

Set breakpoints, then click the OK button.

Settings in the Breakpoints Setup dialog box are applied to the Edit window. The following figure shows the Edit window.

Figure 17‒34: Edit window

(b) Using Add/Remove Breakpoint to set a breakpoint

The following procedure shows how to add, remove or enable a breakpoint in the Edit window without using the Breakpoints Setup dialog box.

To use Add/Remove Breakpoint to set a breakpoint:

Open the AIT file. Then, position the cursor at a line at which you want to stop the debugging process.

From the Debug menu, choose Add/Remove Breakpoint.

The operation differs depending on the selected line.

Line without a breakpoint:

An enabled breakpoint is added.

Line with an enabled breakpoint:

The breakpoint is removed.

Line with a disabled breakpoint:

The breakpoint is enabled.

You can also press F9 as a shortcut, instead of choosing Add/Remove Breakpoint.

(2) Stopping execution of the AIT file at a specific point

You can execute the AIT file from the current point and stop at a specific point.

You can stop execution of the AIT file by:

setting a breakpoint and choosing Go from the Debug menu;

moving the cursor to a certain position, and choosing Run to Cursor from the Debug menu; or

choosing Step by Step in the Debug menu for execution in units of statements.

To terminate debugging, from the Debug menu, choose Stop Debugging.

(a) Stopping execution of the AIT file at breakpoints

You can stop execution of the AIT file at the breakpoints you set. If breakpoints are set on blank, comment, and other non-executable lines, the breakpoints will be moved forward to the nearest executable lines when the debugging starts.

The following procedure shows how to execute the AIT file and stop the execution at breakpoints.

To execute the AIT file, and stop the execution at breakpoints:

Set breakpoints at certain positions in the AIT file.

For details on how to set breakpoints, see 17.7.2(1) Setting breakpoints above.

From the Debug menu, choose Go.

The statement is executed to the first breakpoint, with the debug cursor moved to the breakpoint line.

Repeat step 2 to execute the AIT file to the next breakpoint, or select another item in the Debug menu.

(b) Stopping execution of the AIT file before the cursor line

You can stop execution of the AIT file before the cursor line.

To stop execution of the AIT file before the cursor line:

In the AIT file, move the cursor to a position at which you want to stop execution of the file.

From the Debug menu, choose Run to Cursor.

The statements before the cursor line are executed, with the debug cursor moved to the position specified in step 1.

Repeat steps 1 and 2 to execute the AIT file to the next cursor, or select another item in the Debug menu.

(c) Stopping execution of the script in units of statements

You can stop execution of the script in units of statements to the end of the AIT file or until the debug process is stopped by choosing Stop Debug.

To stop execution of the script in units of statements:

Open the AIT file.

From the Debug menu, choose Step by Step.

The current statement line is executed, with the debug cursor moved to the next statement line.

Repeat step 2 to execute the current statement line, or select another item in the Debug menu.

(3) Monitoring and changing values of variables

During debugging of an AIT file, you can use the Watch window to monitor the values of the specified variables. When execution of the AIT file stops at a specific position, the Watch window displays the current values of the variables. You can also use the Watch window to change variable values.

The following procedure shows how to monitor the specified variables in the Watch window.

To monitor variables in the Watch window:

During debugging of the AIT file, choose Display and then Watch.

The Watch window appears.

Figure 17‒35: Watch window

In the Variable column, specify a variable name, and press Enter.

You can also enter a variable name by dragging and dropping it from the Edit window to the Watch window.

The Watch window displays the values of the variables you entered. Numeric data displayed in decimal by default. This data can also be displayed in hexadecimal if you select Hexadecimal in the menu appearing by right-clicking. String data is displayed as string constants.

If you specify a variable name not defined in the AIT file, an error message appears.

Execute the AIT file to a specific position.

The current values of the variables are displayed in the Watch window.

If you want to change the value of a variable, in the Watch window, enter a new value, and press Enter.

The new value is applied to the script in the AIT file.

You can remove the name of a variable from the Watch window if you do not want to monitor it any longer. To remove a variable name, in the Watch window, select the variable name, and press Delete.

18 AIT Language Reference

This chapter describes the format of AIT files and the syntax of the AIT language.

18.1 Format of AIT files

Each AIT file consists of the following four sections:

PACKAGE_INFO

DEFINE

MAIN

ERROR

All of these sections are required. You cannot change the order of the sections.

The following shows the format of AIT files. In the AIT language, alphabetic letters are not case sensitive. You can add comments in the script.

Format of AIT files

PACKAGE_INFO
{
   // Package information
}

DEFINE
{
   // Defines and initializes variables and constants
}

MAIN
{
   // Operations on windows
}

ERROR
{
   // Error handling
}

18.2 Sections

This section explains the sections in an AIT file.

18.2.1 PACKAGE_INFO

The PACKAGE_INFO section contains the package information on the software you want to distribute, and information necessary to set up the software.

The following explains the items you can specify in this section.

(1) Format

You can specify only the following items:

PackageID = "package-ID";
Product  =  "product";
Version = "version";
InstallerName = "installer-name";
InstallDrive = "installation-drive";
InstallDirectory = "installation-directory";
IconGroupName = "icon-group-name";
SerialNumber = "serial-number";
JUser = "user-name";
JCompany = "company-name";
ScriptFileVersion = "AIT-file-version";

(2) Items to be described

The following table describes the items you can specify in the PACKAGE_INFO section. You cannot use such characters having special meanings as \n, \r, and \t.

Item

Description

Type

PackageID

Specify the package ID with a value from 1 to 44 bytes. You can use upper-case letters, numbers, hyphens (-), and underscores (_).

Required

Product

Specify the package name with a value from 1 to 50 bytes. You cannot use \.

Required

Version

Specify the version or revision of the software with a value from 1 to 6 bytes. You can use upper-case letters, numbers, and a slash (/).

Required

InstallerName

Specify the name of the installer to be used to install the software with a value from 1 to 256 bytes. You cannot use the following characters:

* " : | < > ?

Required

InstallDrive

Specify the drive in which to install the software by using two characters: an alphanumeric character and a colon (:)

Required

InstallDirectory

Specify the path name of the directory in which to install the software. Specify the path name with a value from 1 to 128 bytes. The name must start with a backslash (\).

Required

IconGroupName

Specify the icon group of the software with a value from 1 to 40 bytes.

Optional

SerialNumber

Specify the serial number of the software to be installed with a value from 1 to 64 bytes. For software which requires the CD key for its installation, enter the CD key.

Optional

JUser

Specify a value from 1 to 40 bytes for the software owner name.

Optional

JCompany

Specify a value from 1 to 80 bytes for the company name of the software owner.

Optional

ScriptFileVersion

Specify the AIT file version in the n.n.n.n format using numeric characters. You cannot specify a series of dots (.). You must specify all four n values delimited by a dot (.). If the fourth n is not specified, it is assumed to be 0. For example, 1.0.0. is assumed to be 1.0.0.0.

This information prevents the Automatic Installation Tool from executing an AIT file created by an old engine of an earlier version of the Automatic Installation Tool.

If the version of the AIT file is not specified in the PACKAGE_INFO section, the DLL version of the active engine is acquired as the AIT file version.

Optional

(3) Example of coding

PACKAGE_INFO
{
   PackageID = "D";
   Version = "1";
   Product =  "product";
   InstallerName = "installer-name";
   InstallDrive = "D:";
   InstallDirectory = "\Plan14.1";
   JUser = "package-user";
   JCompany = "package-user-company";
   SerialNumber = "package-serial-number";
   IconGroupName= "icon-group-name";
   ScriptFileVersion = "1.0.0.0";
}

18.2.2 DEFINE

The DEFINE section defines all variables and constants used in the AIT file. This section can contain only the codes for declaring and initializing variables and constants.

(1) Example of coding

DEFINE
{
    const integer OK_END = 0, NG_END = -1 ;
    string sMsgText;
    float TimeOut;
    bool sInvalidPathFlag = false;
}

(2) Notes

You cannot redefine variables.

In the AIT file, if you use a variable not declared in the DEFINE section, the output window displays a warning message upon a syntax check.

18.2.3 MAIN

The MAIN section contains the codes for installing software automatically. In this section, you can use all statements other than data type declarations.

You can also code this section to notify the agent of the return code for the result of installation.

(1) Example of coding

MAIN
{
    AIT_SetDefaultWaitTimeout(1.0);
    AIT_DMPSTRC();
    DM_RTN = NG_END;
    AIT_InitLog(InstallerName);
    bRtn= AIT_Exec(InstallerName,SW_SHOWNORMAL);
    if(bRtn == false)
        iErrorNo = AIT_GetLastError();
        strErrorTxt = AIT_GetErrorText(iErrorNo);
        AIT_LogMessage(strErrorTxt);
        iLoopCount = iLoopMax;
    else
        AIT_LogMessage("Recorder File started");
    Endif;
    while(iLoopCount < iLoopMax)
        if(AIT_FocusWindow("check", "#32770") > 0)
            AIT_LogMessage("Window - Caption: check, Class Name: #32770");
            AIT_CtrlSetFocus("check box(&C)",CHECKBOX_CTRL);
            AIT_Sleep(SLEEP_TIME_EVENTS);
            AIT_LogMessage("AIT_CtrlSetFocus('"check box(&C)'",CHECKBOX_CTRL);");
            AIT_PlayKey("{ENTER}");
            AIT_Sleep(SLEEP_TIME_EVENTS);
            AIT_LogMessage("AIT_PlayKey('"{ENTER}'");");
            iLoopCount = iLoopMax;
            DM_RTN = OK_END;
            continue;
        Endif;
        iLoopCount = iLoopCount + 1;
        AIT_Sleep(SLEEP_TIME);
    loop;
    if(DM_RTN == OK_END)
        AIT_LogMessage("Recorder File ended normally");
    else
        AIT_LogMessage("Recorder File ended Abnormally");
    Endif;
    WINH = AIT_RegisterWindowMessage("ITM_REC_QUIT");
    if(WINH != 0)
        AIT_PostMessage(HWND_BROADCAST,WINH,DM_RTN,0);
    Endif;
}

18.2.4 ERROR

The ERROR section contains the statements to be executed if the installation abnormally terminates. You can code this section to notify the agent of the return code for the result of installation.

If an error occurs during execution of an AIT file, control moves to this section.

(1) Example of coding

ERROR
{
   WINH = AIT_RegisterWindowMessage("ITM_REC_QUIT");
     if  (WINH != 0)
       AIT_PostMessage (HWND_BROADCAST,WINH,-1,0);
     endif;
}

18.3 Data types

This section explains the data types that can be used in AIT files. This system supports the basic data types shown below.

18.3.1 integer

The integer-type is a basic data type that contains a numeric character in the range from -2,147,483,648 to +2,147,483,647. Data of this type cannot include any decimals and exponents.

The keyword integer allows you to declare integer-type variables and initialize variables and constants. You can use this keyword only in the DEFINE section. When you specify two or more variables after this keyword, use a comma (,) to delimit them.

You can declare a constant by using the keyword const in combination with the keyword integer. The values of the constants declared in the DEFINE section can only be referenced, and cannot be changed in the MAIN or ERROR section.

(1) Format

DEFINE
{
   [const] integer variable_name1 [= integer_constant1] [, variable_name2 [= integer_constant2] ];
}

(2) Example of coding

DEFINE
{
    const integer OK_END = 0, NG_END = -1 ; // Enabled
    integer end_status, return_code;        // Initialized at 0
}

(3) Notes

When you initialize variables or constants, you can specify only decimal values.

An integer-type variable can be assigned only a value of type integer, bool, or float. However, if a value of type float is assigned, because the value may become inaccurate, a warning message appears in the output window upon a syntax check.

All variables are initialized at 0 by default. In the example shown in (2) above, end_status and return_code are initialized at 0.

18.3.2 float

The float type is a basic data type that can indicate a 32-bit floating-point decimal number. A float-type variable or constant can have an absolute value from +3.40282347e+38 to +1.175494351e-38.

The keyword float allows you to declare and initialize a float-type variable or constant. You can use this keyword only in the DEFINE section. When you specify two or more variables after this keyword, use a comma (,) to delimit them.

You can declare a constant by using the keyword const in combination with the keyword float. The values of the constants declared in the DEFINE section can only be referenced, and cannot be changed in the MAIN or ERROR section.

(1) Format

DEFINE
{
    [const] float variable_name1 [= float_constant1] [, variable_name2 [= float_constant2] ];
}

Floating-point values can include a decimal point or an exponential notation (using E or e). In the exponential part, you can specify E or e followed by an integer. A sign (+ or -) can be added to the integer. A constant of type float must consist of one or more digits, and must have a decimal point or exponent.

(2) Example of coding

DEFINE
{
    float DefaultTimeOut = 0.01, DefaultSleep=5.0 ; // Valid
    float SleepMax;                                 // Valid
}

(3) Notes

A constant of type float can be specified only with a decimal number.

A float-type variable can be assigned only a value of type bool, float, or integer.

A float-type variable is initialized at 0 by default. In the example shown in (2) above, SleepMax is initialized at 0.

The number of significant digits for data of type float is 11 (including a decimal point).

18.3.3 bool

The bool-type data has the value true or false. There are the following relationships between the values true and false:

The !false value has the same meaning as the true value.

The !true value has the same meaning as the false value.

The keyword bool allows you to declare and initialize a bool-type variable or constant. You can use this keyword only in the DEFINE section. When you specify two or more variables after this keyword, use a comma (,) to delimit them.

You can declare a constant by using the keyword const in combination with the keyword bool. The values of the constants declared in the DEFINE section can only be referenced, and cannot be changed in the MAIN or ERROR section.

If a comparison expression evaluates to 0, the result is assumed to be true. If a comparison expression evaluates to a non-0 value, the result is assumed to be false.

(1) Format

DEFINE
{
    [const] bool variable_name1 [= true|false] [, variable_name2 [= true|false] ] ;
}

(2) Example of coding

DEFINE
{
    bool sInvalidPathFlag, sDirectorySetFlag = true;
    bool SMemoryInsuff = false;
    bool sEndGUI = false;
}

(3) Notes

A bool-type variable can be assigned a value of type integer or float. However, if data of type integer or float is assigned, because the value may become inaccurate, a warning message appears in the output window upon a syntax check.

All variables are initialized as false by default. In the example shown in (2) above, sInvalidPathFlag is initialized as false.

18.3.4 string

The string-type is a basic data type that indicates a variable-length character string.

The keyword string allows you to declare and initialize a string-type variable or constant. You can use this keyword only in the DEFINE section. When you specify two or more variables after this keyword, use a comma (,) to delimit them.

You can declare a constant by using the keyword const in combination with the keyword string. The values of the constants declared in the DEFINE section can only be referenced, and cannot be changed in the MAIN or ERROR section.

To specify a character-string constant, you have to enclose the character string with double quotation marks ("). If you want to use a double quotation mark (") in a character string, place a single quotation mark (') immediately before the double quotation mark.

(1) Format

DEFINE
{
    [const] string variable_name1 [= "StringValue"] [, variable_name2 [= integer_constant2]] ;
}

(2) Example of coding

DEFINE
{
    string CaptionName="Setup";  // Valid
    string ErrorText;            // Valid
}

(3) Notes

The length of a string-type variable may be increased as a result of combination.

All variables that have not been assigned any value become empty. In the example shown in (2) above, ErrorText is empty.

You can write the value of a string-type variable over two or more lines by placing an underscore (_) at the end of the preceding lines. In the following example, the value of string-type variable ErrorText is Sample testing success.

Example:

DEFINE
{
   string ErrorText = "Sample_
 Testing_
 success";   // string is written over multiple lines.
}

The following characters are handled as special characters in a character string.

Character

Handled as:

\n

Line feed

\r

Return

\t

Tab character

'\

Backslash (\)

'"

Double quotation mark (")

''

Single quotation mark (')

In the following example, the character-string variable ErrorText is assigned "Sample Testing".

Example:

DEFINE
{
   string ErrorText = "'"Sample Testing'"";
          // Sample Testing is enclosed in '"...'".
}

In the following example, the character-string variable Path is assigned C:\Windows\system32.

Example:

DEFINE
{
   string Path = "C:'\Windows'\system32";
          // "C:\Windows\system32" is assigned to Path.
}

18.4 Operators

You specify operators to evaluate:

One operand (unary operator)

Two operands (binary operator)

The order in which to evaluate multiple expressions including operators is defined according to strict priority. The operator is linked with either the left or right operand. This is referred to as linking order. The operators in the same group have the same priority. They are evaluated from the left to the right unless you explicitly change the priority using parentheses (()).

The following tables list the operators supported by the AIT language.

Table 18‒1: Unary operators supported by the AIT language

Unary operator

Description

+

Unary plus sign

-

Unary minus sign

!

Unary not sign

Table 18‒2: Binary operators supported by the AIT language

Binary operator

Description

+ -

Adding operators

* / %

Multiplying operators

< <= > >= != ==

Comparison operators

& |

Bitwise operators

&& ||

Logical operators

18.4.1 Assignment

The assignment operation in the AIT language assigns the value of the right operand to the left operand. In assignment, you cannot use any constant as the left operand.

(1) Format

Assignment statement

assignment_expression END_STMT

Assignment expression

identifier assign_operand expression

(2) Description

In assignment, the value of the right operand is stored in the left operand. The left operand must neither be a function nor be a constant.

If the data type of the right operand differs from that of the left operand, type conversion is performed when possible. This type conversion depends on the specified operator, and the type of operator or operand.

The following table lists the results of type conversion in the AIT language. Warning messages and errors for data conversion are displayed upon syntax checks.

Left operand

Right operand

Result

Description

integer

integer

integer

The value of one integer-type variable is assigned to the other integer-type variable.

integer

float

integer

The truncated value is assigned to the integer-type variable. A warning message is displayed because the data may become inaccurate.

integer

bool

integer

The value true is assigned to the integer-type variable as 1. The value false is assigned to the integer-type variable as 0.

integer

string

Error

Since the string type cannot be converted to the integer type, an error message is displayed.

float

integer

float

The value of the integer-type variable is assigned to the float-type variable.

float

float

float

The value of one float-type variable is assigned to the other float-type variable.

float

bool

float

The value true is assigned to the float-type variable as 1. The value false is assigned to the float-type variable as 0.

float

string

Error

Since the string type cannot be converted to the float type, an error message is displayed.

bool

integer

bool

A non-0 value is assigned to the bool-type variable as true. 0 is assigned to the bool-type variable as false. Since the original data is lost, a warning message is displayed.

bool

float

bool

bool

bool

bool

The value of one bool-type variable is assigned to the other bool-type variable.

bool

string

Error

Since the string type cannot be converted to the bool type, an error message is displayed.

string

integer

Error

Since the integer type cannot be converted to the string type, an error message is displayed.

string

float

Error

Since the float type cannot be converted to the string type, an error message is displayed.

string

bool

Error

Since the bool type cannot be converted to the string type, an error message is displayed.

string

string

string

The value of one string-type variable is assigned to the other string-type variable

The AIT language supports multi-assignment. The multi-assignment here means assignment of a value to two variables.

(3) Example of coding

MAIN
    {
        a = 10;         // Value 10 is assigned to a.
        a = b = 20;     // Multi-assignment is coded.
                        // Value 20 is assigned to variable b,
                        // then to variable a.
    }

18.4.2 Unary plus

The unary plus is a unary operator that returns the positive value of the result of the expression.

(1) Format

+[(]expression[)]

(2) Description

The operand for the unary plus operator (+) must be arithmetic type. The unary operator is placed before an operand, linking from the right to the left.

Specifying the positive unary operator for a negative value will return a negative value. Specifying the negative operator for a negative value will return a positive value.

(3) Example of coding

const integer NG_END = +1;         // Statement in the DEFINE section
sloopcnt = +(sloopmin - sloopmax); // Statement in the MAIN section

18.4.3 Unary minus

The unary minus is a unary operator that returns the negative value of the result of the expression.

(1) Format

-[(]expression[)]

(2) Description

The operand for the unary minus operator (-) must be arithmetic type. The unary operator is placed before an operand, linking from the right to the left.

Specifying the negative unary operator for a negative value will return a positive value. Specifying the positive unary operator for a negative value will return a negative value.

(3) Example of coding

const integer NG_END = -1;           //Statement in the DEFINE section
integer sloopcnt, sloopmax, sloopmin;
sloopcnt = -(sloopmax - sloopmin);   //Statement in the MAIN section

18.4.4 Unary not

The unary not is a unary operator that logically negates the result of the expression.

(1) Format

!(expression)

(2) Description

If the negation of an operand (for example, when an operand is false) is true, the value true is returned. On the contrary, if the negation of an operand (for example, when an operand is true) is false, the value false is returned.

The unary operator is placed before an operand, linking from the right to the left.

(3) Example of coding

bool IsLastDialog;
IsLastDialog = false;
if (!IsLastDialog)
   AIT_LogMessage("Installable Software Extracting... is opened.");
else
   AIT_LogMessage("Installable Software Extracting... is not opened.");
endif;

18.4.5 Adding operators

Adding operators perform addition (+) or subtraction (-).

(1) Format

Additive expression

expression + expression

Subtractive expression

expression - expression

(2) Description

The adding operator performs normal arithmetic conversion for integer-type and float-type operands, according to the data type.

The adding operator (+) adds two operands. If the two operands are of the string type, the two character strings are combined. If only one of the two operands is the string type, this results in an error.

The subtractive operator (-) subtracts the second operand from the first operand. Both of the operands must have numeric values. If one or both of the operands are the string type, this results in an error.

(3) Example of coding

MAIN
{
         ...
         sloop_cnt = sloop_cnt+1;
         sloop_cnt = sloop_cnt-1;
         ...
         ...
}

(4) Notes

The conversion processing provided by adding operators does not handle overflow and underflow. If the result of conversion by an adding operator cannot be represented with the data type of the operand, information may be lost.

18.4.6 Multiplying operators

Multiplying operators perform multiplication (*), division (/), and remainder calculation (%).

(1) Format

Multiplicative expression

expression * expression

Divisional expression

expression / expression

Remainder calculation expression

expression % expression

(2) Description

Multiplying operators perform normal arithmetic conversion for operands, according to the data type. Both of the operands must have numeric values. If one or both of the operands are of the string type, this results in an error.

The multiplication operator (*) multiplies two operands. The operands may be integer or float type.

The division operator (/) divides the first operand by the second operand. The operands may be integer or float type. The data types of both operands may be different. While the result of division by 0 is undefined, the error message is displayed upon a syntax check or during runtime. If both of the operands are positive or unsigned, the result is rounded off to the nearest integer.

The operands subject to the remainder calculation operator (%) must have integers. The result of the calculation provides the remainder with the first operand divided by the second operand. If the calculation is indivisible, the result is determined according to the following rules:

If the right operand is 0, the result is undefined.

If both of the operands are positive or unsigned, the result is positive.

(3) Example of coding

MAIN
{
if (sloop_cnt > 10)
   AIT_Sleep(SLEEP_TIME / 2);
else
   AIT_Sleep(SLEEP_TIME * 2);
endif;
}

(4) Notes

The conversion provided by multiplying operators does not handle overflow and underflow. If the result of conversion by a multiplying operator cannot be represented with the data type of the operand, information may be lost.

If the operand is divided by 0 during runtime, control moves to the ERROR section.

18.4.7 Comparison operators

The binary comparison operator compares the first operand with the second operand to verify that the specified relationship is valid. If the comparison expression evaluates to true, 1 is returned. If the comparison expression evaluates to false, 0 is returned. The result is the bool type.

(1) Format

Comparison expression

expression < expression
expression > expression
expression <= expression
expression >= expression

Equality

expression == expression

Inequality

expression != expression

(2) Description

The following gives the relationships checked by the comparison operator.

Operator

Relation to be checked

<

The first operand is smaller than the second operand.

>

The first operand is greater than the second operand.

<=

The first operand is equal to or smaller than the second operand.

>=

The first operand is equal to or greater than the second operand.

==

The first operand is equal to the second operand.

!=

The first operand is not equal to the second operand.

You can specify an operand of type integer, float, or string. You may specify operands of different types. Comparison operators perform normal arithmetic conversion for operands of integer and float types. You can also use a combination of some operand types, and the comparison or equal operator.

The following table shows how the comparison operators evaluate the comparison results as true or false.

Operator

Meaning

True

False

<

Smaller than

expression-1 < expression-2

expression-1 >= expression-2

>

Greater than

expression-1 > expression-2

expression-1 <= expression-2

<=

Equal to or smaller than

expression-1 <= expression-2

expression-1 > expression-2

>=

Equal to or greater than

expression-1 >= expression-2

expression-1 < expression-2

==

Equal to

expression-1 == expression-2

expression-1 != expression-2

!=

Not equal to

expression-1 != expression-2

expression-1 == expression-2

The following table gives the results of comparison expressions depending on the data types of expressions.

Data types of expressions

Operation

Both expressions are numeric.

Compares the numeric values.

Both expressions are string type.

Compares the character strings.

One expression is numeric and the other expression is string type.

Results in an error.

(3) Example of coding

if (sloop_cnt < (sloop_max - 25))  // <
    AIT_LogMessage("Searching for Active windows");  //Search Active windows
    if (AIT_FocusWindow("Installable Software Extracting...", "#32770",0.0) > 0)   // >
        AIT_LogMessage("Installable Software Extracting... is opened");
        sloop_cnt= 0;
    endif;
endif;

18.4.8 Bitwise operators

Bitwise operators perform bitwise AND (&) and OR (|) operations.

(1) Format

Bitwise AND

expression & expression

Bitwise OR

expression | expression

(2) Description

Either or both of the operands for a bitwise operator must be the integer type. Bitwise operators perform normal arithmetic conversion according to the data type.

The following explains the bitwise operators.

Operator

Description

&

The bitwise AND operator compares a bit of the first operand with the corresponding bit of the second operand. If both the bits are 1, the resulting bit is set at 1. If not, the resulting bit is set at 0.

|

The bitwise OR operator compares a bit of the first operand with the corresponding bit of the second operand. If one of both the bits is 1, the resulting bit is set at 1. If not, the resulting bit is set at 0.

The bitwise AND operator compares two expressions bit by bit, and sets the resulting bit as follows:

Bits of expression 1

Bits of expression 2

Result

0

0

0

0

1

0

1

0

0

1

1

1

The bitwise OR operator compares two expressions bit by bit, and sets the resulting bit as follows:

Bits of expression 1

Bits of expression 2

Result

0

0

0

0

1

1

1

0

1

1

1

1

18.4.9 Logical operators

The logical operator provides logical AND && and OR (||).

(1) Format

Logical AND operation

expression-1 && expression-2

Logical OR operation

expression-1 || expression-2

(2) Description

Logical operators do not perform normal arithmetic conversion. Instead, it evaluates the operands in terms of whether they match 0. The result of a logical operation is true or false. The result is the bool type.

The following explains the logical operators.

Operator

Description

&&

If both the operands are true, the result is true. If one of the operands is false, the result is false. If the first operand for logical AND is false, the second operand is not evaluated.

||

If both the operands are false, the result is false. If one of the operands is true, the result is true. If the first operand for logical OR is true, the second operand is not evaluated.

The operands for logical AND and OR expressions are evaluated from the left to the right. If the operational result can be identified only by the value for the first operand, the second operand is not evaluated. This is referred to as quick evaluation.

(a) Logical AND operator (&&)

If both the expressions evaluate to true, the result is true. If one of the expressions is evaluates to false, the result is false. The following table shows how the results are evaluated.

Evaluation of expression 1

Evaluation of expression 2

Resulting evaluation

true

true

true

true

false

false

false

true

false

false

false

false

(b) Logical OR operator (||)

If one or both of the expressions evaluate to true, the result is true. The following table shows how the results are evaluated.

Evaluation of expression 1

Evaluation of expression 2

Resulting evaluation

true

true

true

true

false

true

false

true

true

false

false

false

(3) Example of coding

DEFINE
{
   float varfloat1 = 1.567e-1;
   integer varint1 = 10;
   integer varfloat2 = 0;
   integer varint2 = 0;
   bool varbool;
   integer WINH;
}
MAIN
{
   varbool = varfloat1 && varint1;
   AIT_LogMessage("The expected value of varbool is: true");
   varbool =varfloat2 && varint1;
   AIT_LogMessage("The expected value of varbool is: false");
   varbool=varfloat1 && varint2;
   AIT_LogMessage("The expected value of varbool is: false");
   varbool=varfloat2 && varint2;
   AIT_LogMessage("The expected value of varbool is: false");
}

18.4.10 Priority of operators

The priority and linking order of operators affect operand grouping and evaluation for expressions. The priority of operators is meaningful only when there are operators with different priorities in the same expression. If the expression contains a higher-priority operator, the operator is evaluated first. If operators have the same priority, the order in which to evaluate them depends on their linking order.

The following table shows the priority and linking order of the operators. The following arrangement shows the operators in descending priority order.

Symbol

Operator

Linked:

( )

Parentheses

From the left to the right

+ - !

Unary operators

From the right to the left

* / %

Multiplying operators

From the left to the right

+ -

Adding operators

From the left to the right

< > <= >=

Comparison operators

From the left to the right

== !=

Equality

From the left to the right

&

Bitwise AND

From the left to the right

|

Bitwise OR

From the left to the right

&&

Logical AND

From the left to the right

||

Logical OR

From the left to the right

=

Assignment

From the left to the right

18.5 Variables and constants

Variables and constants are typical data. The values of variables may be changed, and the values of constants cannot be changed.

To use variables or constants, you have to declare them only once in the DEFINE section in the AIT file. The name of each variable or constant can have a maximum of 64 characters and must begin with any alphabetic character (A-Z). You cannot use special characters other than an underscore (_). The alphabetic characters are not case sensitive.

You should use easy-to-understand variable and constant names that indicate the roles or meanings of them. You must not use any keywords, label names, and macro names as variable names.

18.5.1 Example of variables

integer LoopCount;
string CountryName;
bool answer;
float r_nTimeOut;
integer ABC;
integer abc;     //Disabled as the variable is redefined.

In the above example, integer means that the listed variable is the integer type. In other words, LoopCount is an integer, while CountryName is a character string.

18.5.2 Example of constants

const integer OK_END = 0;       //DM_RTN:OK_END
const integer NG_END = -1;      //DM_RTN:NG_END
const integer SET_SLEEP_TIME = 2;

18.6 Program flow control

Normally, statements are executed in sequence. However, you can move control to another statement by using the statements explained in this section.

18.6.1 goto

The goto statement provides an unconditional jump to a valid label position declared in the same section.

(1) Format

Statements

Jump statement
Label statement

Jump statement

goto identifier;

Label statement

identifier:

(2) Description

The goto statement is used to exit deeply nested loops directly. Unlike this statement, the break statement can exit only one nesting level of repetitive statements.

(3) Example of coding

//MAIN section
MAIN
{
   ...
   ...
   AIT_LogMessage("LBL030: JUMP TO LABEL");
   goto label1;
       AIT_LogMessage("LBL030: NOT DISPLAYED 1");       // Not executed

       label1:                        // The control shifts here.
          AIT_LogMessage("LBL030: JUMPING TO LABEL ");  // Executed
}

(4) Notes

For better programming, you should use the break, continue, or return statement rather than the goto statement wherever possible.

18.6.2 Label

To use the goto statement to directly jump to any other statement, you have to add a label at the destination statement.

A label is specified in the identifier: format. You may declare a label at any position in the MAIN and ERROR sections. You must specify a unique label name according to the same rules as for variables and constants. You must not reuse any variables and constants as labels.

The label has no meaning in any sections other than MAIN and ERROR. It only has meaning if it is associated with a goto statement. If a label is not associated with any goto statement, the program does not interpret the label but outputs a warning message.

(1) Format

Label statement

identifier:

(2) Example of coding

AIT_MessageBox("ss","xx");
goto label18;
   AIT_LogMessage("LBL040: NOT DISPLAYED 29");
                    // Not executed
   label18:         // The control shifts here.
   AIT_LogMessage("LBL040: INSIDE LABELLED STATEMENT");
                    // Executed
   AIT_Exit();

18.6.3 if-else-endif

The if statement allows a conditional branch to be processed.

If the condition evaluates to a value other than 0, the main part of the if statement is executed. If it is 0, the sections other than the main part are executed.

In this statement, the sections other than the main part are options. You have to enclose a condition by parentheses.

(1) Format

if (condition)
    [expression-1;]
[else
    [expression-2;]]
endif;

(2) Description

Conditions are subject to evaluation. If the condition is not 0, expression-1 in (1) is executed and, if it is 0, expression-2 is executed.

In the if-else-endif statement, the else clause is associated with the immediately preceding if statement which does not have the associated else statement.

(3) Example of coding

if(AIT_FocusWindow("Installable Software-Setup","#32770"))
                   // The following two lines are executed
                   // if the condition is true (other than 0).
   AIT_LogMessage("INSIDE Installable Software SETUP");
   AIT_PlayKey("ENTER");
else
                   // The following two lines are executed
                   // if the condition is false (0).
   AIT_LogMessage("PROBLEM IN SETUP");
   AIT_Exit();
endif;

18.6.4 while-loop

The while-loop statement executes the specified expressions repeatedly until the specified condition becomes false. You have to enclose a condition to be specified with parentheses.

(1) Format

while (condition)
    expression-1;
    expression-2;
loop;

(2) Description

Conditions are evaluated.

If the condition first becomes false, the main part of the while statement is never executed, and the control moves from the while statement to the next statement in the same program.

If the condition is true (not 0), the main part of the statement is executed, with all expressions executed repeatedly from expression-1.

When the system encounters a break statement specified in the main part of that statement, the loop ends.

When the system encounters a continue statement specified in the main part of that statement, the subsequent steps are skipped, with the condition evaluated. If the condition is true, the execution is repeated.

You should not nest more than 255 while loops.

(3) Example of coding

DEFINE
{
integer WINH,count,length;
float SLEEP_TIME=0.5;
string s1,s2;
integer i,sloop_cnt   = 0;
integer sloop_max = 30;
}
...
...
while ( sloop_cnt < sloop_max)
   AIT_LogMessage("The active window is being found");
   if (AIT_FocusWindow("Unpacking...", "#32770",0.0) > 0)
   if(AIT_FocusWindow("Unpacking software to be installed...", "#32770", 0.0) > 0)
          AIT_LogMessage("Unpacking software to be installed... is opened");
      sloop_cnt= 0;
      AIT_Sleep(SLEEP_TIME);
   endif;
   endif;
   AIT_Sleep(SLEEP_TIME);
   sloop_cnt = sloop_cnt + 1;
loop;

18.6.5 do-while

The do-while statement executes the specified expressions repeatedly until the specified end condition is evaluated as false. You have to enclose a condition to be specified with parentheses.

(1) Format

do
   expression-1
   expression-2
   ...
   ...
while (condition);

(2) Description

The main part of the do-while statement is executed.

Next, the condition is evaluated. If the condition is false, the do-while statement ends, and the control moves to the next statement in the same program. If the condition is true (not 0), the expressions are executed repeatedly from expression-1.

When the system encounters a break statement specified in the main part of that statement, the loop ends.

When the system encounters a continue statement specified in that statement, the subsequent steps are skipped, with the condition evaluated. If the condition is true, the execution is repeated.

In other words, the main part of the loop is executed at least once.

You should not specify more than 255 break or continue statements in a loop. Moreover, you should not nest more than 255 do-while statements.

(3) Example of coding

DEFINE
{
integer WINH,count,length;
float SLEEP_TIME=0.5;
string s1,s2;
integer i,sloop_cnt   = 0;
integer sloop_max = 30;
}
...
...
do
   AIT_LogMessage("Searching for Active windows");
   if (AIT_FocusWindow("Installable Software", "#32770",0.0) > 0)
        if(AIT_FocusWindow("Unpacking Installable Software...", "#32770", 0.0) > 0)
            AIT_LogMessage("Unpacking Installable Software... is opened");
            sloop_cnt= 0;
            AIT_Sleep(SLEEP_TIME);
        endif;
   endif;
   AIT_Sleep(SLEEP_TIME);
   sloop_cnt = sloop_cnt + 1;
while ( sloop_cnt < sloop_max);
...
...

18.6.6 for-next

The for-next statement executes the expression repeatedly until the condition becomes false. The optional expression supported in the for-next statement allows you to initialize or change a value during for-next statement execution.

Typically, the number of times a loop is repeated depends on the counter.

(1) Format

for ( [initialization-expression] ; [condition-expression] ; [loop-expression] )
     expression-1;
     expression-2;
next;

(2) Description

When an initialization expression is specified, it is evaluated. It specifies loop initialization. The initialization expression may be any type.

A specified condition expression is evaluated before repetition, with three possible results:

If the condition expression is true (not 0), the statement is executed. A specified loop expression is evaluated next. According to the evaluation, execution is repeated.

With no condition expression specified, the condition expression is interpreted as true, and executed in the same way as above. With a condition expression not specified by a parameter, the for statement ends when the goto statement (associated with a labeled statement outside the main part of that statement) or the break statement is executed inside that statement.

If the condition expression is false (0), the for-next statement ends, and the control moves to the next statement in the same program.

When the system encounters a break statement specified in the main part of that statement, the loop stops.

When the system encounters a continue statement specified in the main part of that statement, the subsequent steps are skipped, with the condition expression evaluated. If the condition is true, the execution is repeated.

You should not nest more than 255 for-next structures.

(3) Example of coding

DEFINE
{
integer WINH,count,length;
float SLEEP_TIME=0.5;
string s1,s2;
integer i,sloop_cnt   = 0;
integer sloop_max = 30;
}
...
...
sloop_cnt=1;
AIT_LogMessage("Searching for Active windows - For");
for(; sloop_cnt < sloop_max ;sloop_cnt = sloop_cnt + 1)
    if (AIT_FocusWindow("Unpacking", "#32770",0.0) > 0)
        if(AIT_FocusWindow("Unpacking Installable Software...", "#32770", 0.0) > 0)
           AIT_LogMessage("Unpacking Installable Software... is opened");
           sloop_cnt= 0;
           AIT_Sleep(SLEEP_TIME);
        endif;
        endif;
   AIT_Sleep(SLEEP_TIME);
next;

18.6.7 continue

The continue statement moves the control to the starting position of the nearest do, for, or while loop that encloses this statement. Typically, the continue statement is used to return the control to the loop starting position from a deep nesting level.

(1) Format

Jump statement

continue;

(2) Description

The following shows the rules to determine where the next repetition starts for the do, for, or while statement when the continue statement is encountered.

The next repetition is started by reevaluation of expressions in the do or while statement inside it.

When the continue statement is specified in the for statement, the condition expression in the for statement is reevaluated. The result of reevaluation determines whether to exit or repeat the main part of the statement.

You should not specify more than 255 continue statements in a loop structure.

(3) Example of coding

for (count=1;count<=10;count=count+1)
    if (count < 5)
           continue;
    endif;
    ...
next;

In the above example, the codes following the continue statement are skipped until the value of count reaches 5.

18.6.8 break

The break statement ends execution of the nearest do-while, for-next, switch-endswitch, or while-loop statement that encloses it. The control moves to the statement following the ended statement. The break statement is used to exit a loop.

(1) Format

Jump statement

break;

(2) Description

The break statement is used to exit a loop before the end criterion is satisfied in the loop. Also, this statement may be used to exit a switch statement in a specific case. Unless the break statement is used within a repetitive statement or a switch statement, an error occurs.

You should not specify more than 255 break statements in a loop structure.

(3) Example of coding

i = 0;
for(;;)
   AIT_LogMessage("Inside Loop");
   i = i + 1;
   if(i>100)
      break;
   endif;
next;

18.6.9 switch-endswitch

The switch statement selects the processing according to the result of the expression. The expression is specified within parentheses.

The switch statement can contain case labels and a default label, which are options of processing to be executed. The case labels can have unique constants. For the switch statement to be meaningful, it must contain at least one case label.

You can specify only one default label. This label is not a required item. When you use this, do not specify any value.

(1) Format

switch (expression)

  [case constant-value:]+
       [expression;]*
  ...
  ...
 [default:]
       [expression;]*

endswitch;

(2) Description

The expression is evaluated.

The control moves to the block that has the same case label value as the result of the expression. Until the break statement is encountered, the subsequent statements are executed (dependent of the case label value).

If the break statement is encountered, the control leaves the switch statement.

If the result of the expression is not equal to the case label value, the control will move to the default label, when it is specified.

When specifying the switch-endswitch statement, you have to follow the rules below:

The data type of the value returned by the expression in the switch statement must be the same as the constants specified in case labels.

You must not nest more than 255 switch statements.

case labels do not need to have associated executable statements (with the exception of last case statement, which must have at least one associated executable statement).

The switch-endswitch statement can have up to 255 case labels.

In case labels, you can specify a numeric constant, a string constant, or an AIT language macro. You cannot specify any expressions in them.

Example

case -5:        // Valid
case +6:        // Valid
case "String":  // Valid
case intvar:    // Invalid
case 3+2:       // Invalid

The constants you specify in case labels must have the same data type as the result of the expression in the switch statement.

Example

switch (Stringvar1+Stringvar2) //Both variables are string type.
case 1:                        // Invalid
case "caption-1":              // Valid
 .
 .
endswitch;

If no case statement is specified in a switch case statement, the statement is interpreted as a syntax error.

You can specify a maximum of 255 break statements in one switch case statement.

You do not need to specify any statements for all case labels except the last case label.

Example

switch(i)
{
  case 1:
  case 2:
    a=b+c; // If you do not specify this statement, the script
           // analyzer will issue a syntax error.
}

(3) Example of coding

s1="abcdefghijk";
switch (!AIT_IsEmpty(s1 ))
case true:            // Executed if s1 is empty.
    s2 = AIT_StrUpper(s1);
    AIT_MessageBox("s2",s2);
       if ( ( length = AIT_StrLength(s2)) > 10)
           break;
    endif;
    break;
default:              // Executed if the expression evaluates to false.
    break;            //
endswitch;

18.7 Function calls

The AIT language supports various types of API functions to carry out standard operations. The API functions can be categorized as follows:

Window operations

Check operations

Resolution checks

Date/time operations

IME operations

Character string operations

Message operations

Registry operations

Directory operations

Redirect operations

File operations

INI file operations

Recorder operations

Taskbar operations

Utility operations

Interfacing with JP1/IT Desktop Management 2

18.7.1 Format

The above API functions can be called from the MAIN and ERROR sections.

When you pass parameters to API functions, make sure that the data types of the parameters conform to the API specifications.

You can specify an expression in a function call. If the data types of expressions and function calls conform to the API specifications, you can nest the function calls.

If a runtime error occurs during execution of an API, the control moves to the ERROR section.

If a function fails, you can use AIT_GetLastError to acquire the return code of the function. You can also use AIT_GetErrorText to acquire the text of the error message.

18.7.2 Example of coding

integer intvar1;
string Caption;
string Stringvar1, Stringvar2;
...
...
AIT_LogMessage("SAMPLE FUNCTION CALL");  // Function call
if(AIT_FocusWindow("Installable-Setup","#32770"))
        // Return value of the function is used in the expression.
   AIT_LogMessage("INSIDE Installable Software SETUP");
        // Executed
   AIT_PlayKey("{Enter}");
endif;
        // Check for the abnormal end of the called function
Caption = "Installable Software";
intvar1    = AIT_GetSubStr(Stringvar1, Stringvar2, 50);
                                        // intvar1 is 0.
if(!intvar1)
           AIT_LogMessage(AIT_GetErrorText(AIT_GetLastError()));
endif;

18.8 Keywords

Keywords are predefined, reserved identifiers that have special meanings. You cannot use any keywords in a program as variable, constant, and label names. Variable and constant names must differ from keywords. Keywords are not case-sensitive. Therefore, you cannot use them as variable and constant names by changing the case of the letters used in them.

The following table lists the keywords defined in the AIT language.

Table 18‒3: Keywords defined in the AIT language

No.

Keyword

1

bool

2

break

3

case

4

const

5

continue

6

default

7

define

8

do

9

else

10

endif

11

endswitch

12

ERROR

13

float

14

for

15

goto

16

IconGroupName

17

if

18

InstallDirectory

19

InstallDrive

20

InstallerName

21

integer

22

JCompany

23

JUser

24

loop

25

MAIN

26

next

27

PACKAGE_INFO

28

PackageID

29

Product

30

ScriptFileVersion

31

SerialNumber

32

string

33

switch

34

Version

35

while

Other keywords include API names, predefined AIT macro names, and several Win32 error codes.

18.9 Macros

The AIT script language has predefined constants you cannot assign a value to. These constants are macros classified as shown below.

You cannot declare any macros in the DEFINE section.

18.9.1 Macros for window and check operations

The table below lists the macros for window and check operations. The data of these macros is the integer type.

Table 18‒4: Macros for window and checking operations

Macro name

ALT_OFF

ALT_ON

BUTTON_CTRL

CALENDAR_CTRL

CAPSLOCK

CHECKBOX_CTRL

COMBO_CTRL

COMMANDBUTTON_CTRL

CONTROL_CAPTION_SIZE

CONTROL_CLASS_SIZE

CTRL_OFF

CTRL_ON

DTPICKER_CTRL

EDIT_CTRL

HSCROLL

IDABORT

IDCANCEL

IDIGNORE

IDNO

IDOK

IDRETRY

IDYES

INSERTLOCK

IPADDRESS_CTRL

KEYSTATE_OFF

KEYSTATE_ON

LBUTTON

LISTBOX_CTRL

LIST_CTRL

MBUTTON

MB_ABORTRETRYIGNORE

MB_ICONEXCLAMATION

MB_ICONINFORMATION

MB_ICONQUESTION

MB_ICONSTOP

MB_OK

MB_OKCANCEL

MB_RETRYCANCEL

MB_YESNO

MB_YESNOCANCEL

NOTIFICATION_CTRL

NUMLOCK

OPTIONBUTTON_CTRL

PROGRESS_CTRL

RBUTTON

REBAR_CTRL

SB_BOTTOM

SB_LEFT

SB_LINEDOWN

SB_LINELEFT

SB_LINERIGHT

SB_LINEUP

SB_PAGEDOWN

SB_PAGELEFT

SB_PAGERIGHT

SB_PAGEUP

SB_RIGHT

SB_THUMBPOSITION

SB_THUMBTRACK

SB_TOP

SCROLLBAR_CTRL

SCROLLLOCK

SHIFT_OFF

SHIFT_ON

SLIDER_CTRL

SPIN_CTRL

STARTBUTTON_CTRL

STATIC_CTRL

STATUSBAR_CTRL

STYLE_CHECK_BUTTON

STYLE_PUSH_BUTTON

STYLE_RADIO_BUTTON

SW_HIDE

SW_MAXIMIZE

SW_MINIMIZE

SW_NORMAL

SW_SHOW

SW_SHOWMAXIMIZED

SW_SHOWMINIMIZED

SW_SHOWMINNOACTIVE

SW_SHOWNOACTIVATE

SW_SHOWNORMAL

TAB_CTRL

TASKBARCLOCK_CTRL

TASKBARITEMS_CTRL

TASKBAR_CTRL

TOOLBAR_CTRL

TOOLTIPS_CTRL

TREE_CTRL

VSCROLL

18.9.2 Macros for message operations

The following macro is for message operations. The data of this macro is the integer type.

HWND_BROADCAST

18.9.3 Macros for file operations

The table below lists the macros for file operations. The data of these macros is the integer type.

Table 18‒5: Macros for file operations

Macro name

AIT_ALLFILES

CREATE_ALWAYS

CREATE_NEW

FILE_ALL

FILE_ATTRIBUTE_ARCHIVE

FILE_ATTRIBUTE_DIRECTORY

FILE_ATTRIBUTE_HIDDEN

FILE_ATTRIBUTE_READONLY

FILE_ATTRIBUTE_SYSTEM

FILE_READ

FILE_WRITE

GENERIC_READ

GENERIC_WRITE

OPEN_ALWAYS

OPEN_EXISTING

TRUNCATE_EXISTING

18.9.4 Macros for IME operations

The table below lists the macros for IME operations. The data of these macros is the integer type.

Table 18‒6: Macros for IME operations

Macro name

IGP_CONVERSION

IGP_GETIMEVERSION

IGP_PROPERTY

IGP_SELECT

IGP_SENTENCE

IGP_SETCOMPSTR

IGP_UI

IME_CHOTKEY_IME_NONIME_TOGGLE

IME_CHOTKEY_SHAPE_TOGGLE

IME_CHOTKEY_SYMBOL_TOGGLE

IME_CMODE_CHARCODE

IME_CMODE_EUDC

IME_CMODE_FULLSHAPE

IME_CMODE_HANJACONVERT

IME_CMODE_KATAKANA

IME_CMODE_NATIVE

IME_CMODE_NOCONVERSION

IME_CMODE_ROMAN

IME_CMODE_SOFTKBD

IME_CMODE_SYMBOL

IME_JHOTKEY_CLOSE_OPEN

IME_KHOTKEY_ENGLISH

IME_KHOTKEY_HANJACONVERT

IME_KHOTKEY_SHAPE_TOGGLE

IME_PROP_AT_CARET

IME_PROP_CANDLIST_START_FROM_1

IME_PROP_SPECIAL_UI

IME_PROP_UNICODE

IME_SMODE_AUTOMATIC

IME_SMODE_CONVERSATION

IME_SMODE_NONE

IME_SMODE_PHRASEPREDICT

IME_SMODE_PLAURALCLAUSE

IME_SMODE_PLURALCLAUSE

IME_SMODE_SINGLECONVERT

IME_THOTKEY_IME_NONIME_TOGGLE

IME_THOTKEY_SHAPE_TOGGLE

IME_THOTKEY_SYMBOL_TOGGLE

SCS_CAP_COMPSTR

SCS_CAP_MAKEREAD

SELECT_CAP_CONVERSION

SELECT_CAP_SENTENCE

UI_CAP_2700

UI_CAP_ROT90

UI_CAP_ROTANY

-

Legend:

-: None

18.9.5 Macros for utility operations

The table below lists the macros for utility operations. The data of these macros is the integer type.

Table 18‒7: Macros for utility operations

Macro name

VER_PLATFORM_WIN32_NT

VER_PLATFORM_WIN32_WINDOWS

18.9.6 Macros for registry operations

The table below lists the macros for registry operations. The data of these macros is the integer type.

Table 18‒8: Macros for registry operations

Macro name

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

-

Legend:

-: None

18.9.7 Macros for directory operations

The table below lists the macros for directory operations. The data of these macros is the integer type.

Table 18‒9: Macros for directory operations

Macro name

AIT_CURRENTDIRECTORY

AIT_PARENTDIRECTORY

18.9.8 Macros for error logging

The table below lists the macros for error logging. The data of these macros is the integer type.

Table 18‒10: Macros for error logging

Macro name

ERROR_ACCESS_DENIED

ERROR_ALREADY_EXISTS

ERROR_BADDB

ERROR_BADKEY

ERROR_BAD_COMMAND

ERROR_BAD_NETPATH

ERROR_BAD_NET_NAME

ERROR_BAD_PATHNAME

ERROR_BUFFER_OVERFLOW

ERROR_CANNOT_MAKE

ERROR_CANTOPEN

ERROR_CANTREAD

ERROR_CANTWRITE

ERROR_CHILD_MUST_BE_VOLATILE

ERROR_CONTROL_ID_NOT_FOUND

ERROR_CRC

ERROR_CURRENT_DIRECTORY

ERROR_DIRECTORY

ERROR_DISK_CORRUPT

ERROR_DISK_FULL

ERROR_FILENAME_EXCED_RANGE

ERROR_FILE_CORRUPT

ERROR_FILE_EXISTS

ERROR_FILE_NOT_FOUND

ERROR_HANDLE_DISK_FULL

ERROR_HANDLE_EOF

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_COMPUTERNAME

ERROR_INVALID_DATA

ERROR_INVALID_DRIVE

ERROR_INVALID_FUNCTION

ERROR_INVALID_HANDLE

ERROR_INVALID_INDEX

ERROR_INVALID_MENU_HANDLE

ERROR_INVALID_NAME

ERROR_INVALID_NETNAME

ERROR_INVALID_PARAMETER

ERROR_INVALID_SCROLLBAR_RANGE

ERROR_INVALID_SHARENAME

ERROR_INVALID_WINDOW_HANDLE

ERROR_KEY_DELETED

ERROR_KEY_HAS_CHILDREN

ERROR_LOCK_VIOLATION

ERROR_MENU_ITEM_NOT_FOUND

ERROR_NETWORK_BUSY

ERROR_NETWORK_UNREACHABLE

ERROR_NOACCESS

ERROR_NOT_ENOUGH_MEMORY

ERROR_NOT_READY

ERROR_NOT_REGISTRY_FILE

ERROR_NO_LOG_SPACE

ERROR_NO_MORE_FILES

ERROR_NO_MORE_ITEMS

ERROR_NO_MORE_SEARCH_HANDLES

ERROR_NO_SCROLLBARS

ERROR_OUTOFMEMORY

ERROR_PATH_BUSY

ERROR_PATH_NOT_FOUND

ERROR_READ_FAULT

ERROR_REGISTRY_CORRUPT

ERROR_REGISTRY_IO_FAILED

ERROR_REGISTRY_RECOVERED

ERROR_SHARING_VIOLATION

ERROR_SUCCESS

ERROR_TIMEOUT

ERROR_TOO_MANY_OPEN_FILES

ERROR_WRITE_FAULT

ERROR_WRITE_PROTECT

19 API Function Reference

This chapter describes the API functions that can be used in the AIT language.

19.1 API functions

The API functions provided by the AIT language can be categorized as follows:

Window operations

Check operations

Resolution checks

Date/time operations

IME operations

Character string operations

Message operations

Registry operations

Redirect operations

Directory operations

File operations

INI file operations

Recorder operations

Taskbar operations

Utility operations

Interfacing with JP1/IT Desktop Management 2

The following subsections describe the API functions for each category shown above.

19.1.1 Window operations

The API functions below allow the application to perform operations on windows and controls. These operations include finding a window, setting the focus on a specific control, and setting the status of a check box or radio button.

API function name

Description

AIT_FocusWindow

Finds the window, and sets the focus on it.

AIT_ExistWindow

Checks whether the window exists.

AIT_MinWnd

Minimizes the window.

AIT_SetWndPos

Changes the position of the specified window.

AIT_SetWndPosSize

Changes the position and size of the specified window.

AIT_GetWindowText

Acquires the title of the specified window.

AIT_SetActWnd

Activates the window.

AIT_GetCtrlText

Acquires text from the window control.

AIT_CtrlSetFocus

Sets the focus on the control.

AIT_SetSpinPos

Sets the position of the spin or slider control.

AIT_SetScrollPos

Sets the position of the scroll bar.

AIT_CtrlClick

Performs a mouse click on the control.

AIT_SelectMultipleListItem

Selects multiple items in the list.

AIT_SelectListItem

Selects an item in the list.

AIT_SelectIPAddressField

Selects the IP address field.

AIT_SelectText

Selects the text of the control.

AIT_DefaultButtonCount

Acquires the number of default buttons.

AIT_SetCheck

Sets the status of the radio button or check box.

AIT_CtrlItemCount

Acquires the number of control items.

AIT_GetIndexText

Acquires text from the index.

AIT_CtrlItemIndex

Acquires the index of the text.

AIT_GetIndexTextLen

Acquires the character length for a 0-based index character string.

AIT_SetKeyState

Sets the key status.

AIT_GetKeyState

Acquires the key status.

AIT_MouseClick

Performs a mouse click.

AIT_MouseUp

Performs a mouse release.

AIT_MouseDown

Holds down the mouse button.

AIT_MouseMoveTo

Moves the mouse pointer.

AIT_MouseDragDrop

Performs a mouse drag-and-drop operation.

AIT_MouseDblClk

Performs a mouse double-click.

AIT_SetComboEditSelText

Selects text in the combo box.

AIT_ComboBoxCloseUp

Performs a close-up operation on the combo box.

AIT_ComboBoxDropDown

Performs a drop-down operation on the combo box.

AIT_GetEditFirstLineIndex

Acquires the index of the first line in the edit box.

AIT_GetEditCurrentLineIndex

Acquires the index of the current line in the edit box.

AIT_GetCtrlTextLen

Acquires the length of the control text.

AIT_GetEditTextLineLen

Acquires the length of the line in the edit box.

AIT_GetDtPickerTime

Acquires the time from the date/time picker.

AIT_GetDtPickerDate

Acquires the date from the date/time picker.

AIT_SetDtPickerTime

Sets a time with the date/time picker.

AIT_SetDtPickerDate

Sets a date with the date/time picker.

AIT_GetMenu

Acquires a menu handle.

AIT_GetSubMenu

Acquires a sub-menu handle.

AIT_GetMenuText

Acquires a menu text.

AIT_GetMenuIndex

Acquires the menu index.

AIT_MenuItemClick

Clicks on the specified menu item.

19.1.2 Check operations

The API functions below allow the application to carry out check operations such as checking the existence and status of a control, and checking whether the focus is set on the control.

API function name

Description

AIT_VerifyExistence

Checks whether the control exists.

AIT_VerifyEnabled

Checks whether the control can be used.

AIT_VerifyFocus

Checks whether the focus is set on the control.

AIT_VerifyState

Checks the status of the control.

AIT_VerifyCharPos

Checks the position of the character string of the control.

AIT_VerifyLine

Checks the index of the line.

AIT_VerifyText

Checks for the specified text.

AIT_VerifySelected

Checks for the text selected in the edit box.

AIT_VerifyFirstVisible

Checks the first visible item of the control.

AIT_VerifyCount

Checks the number of items.

AIT_VerifyPos

Checks the position of the control.

AIT_VerifyIndex

Checks the index of the control.

AIT_VerifyLocation

Checks the position of the control.

AIT_VerifyDateTime

Checks date or time value for the control.

AIT_VerifyKeyState

Checks the status of the key.

AIT_VerifyDefaultButton

Checks the style of the default button.

AIT_VerifyNoOfCtrls

Checks the number of controls in the window.

AIT_VerifyMenuChecked

Checks whether the menu item is selected.

AIT_VerifyMenuEnabled

Checks whether the menu item can be used.

19.1.3 Resolution check

The API function below checks the resolution set in the system.

API function name

Description

AIT_CheckResolution

Checks the resolution of the display.

19.1.4 Date/time operations

The API functions below allow the application to process a date/time.

API function name

Description

AIT_GetDate

Acquires a system's date.

AIT_GetTime

Acquires a system's time.

19.1.5 IME operations

The API functions below allow the application to simulate enabling/disabling the IME, selecting the conversion mode, and other operations the user frequently performs.

API function name

Description

AIT_IMEGetOpenStatus

Acquires the open status of the IME.

AIT_IMESetOpenStatus

Sets the open status of the IME.

AIT_IMEGetConversionStatus

Acquires the conversion status of the IME.

AIT_IMESetConversionStatus

Sets the conversion status of the IME.

AIT_IMEGetStatusWindowPos

Acquires the position of the status window of the IME.

AIT_IMESetStatusWindowPos

Sets the position of the status window of the IME.

AIT_IMEGetProperty

Acquires the properties of the IME.

AIT_IMESimulateHotKey

Simulates the hot key of the IME.

19.1.6 Character string operations

The API functions below allow the application to carry out character string processing including partial character string processing, cut processing and conversion to the ASCII code.

API function name

Description

AIT_GetSubStr

Returns a character string with the specified length from the character string.

AIT_FindSubStr

Finds a character sting, and returns the position of the first matching character string.

AIT_StrLength

Acquires the length of the character string.

AIT_IsEmpty

Checks whether the character string is empty.

AIT_StrLTrim

Truncates the character string from the left.

AIT_StrRTrim

Truncates the character string from the right.

AIT_StrTrim

Removes characters from a character string.

AIT_StrUpper

Converts the characters in the character string to uppercase.

AIT_StrLower

Converts the characters in the character string to lowercase.

AIT_StrLeft

Acquires the specified number of characters on the left in the character string.

AIT_StrRight

Acquires the specified number of characters on the right in the character string.

AIT_CharToASCII

Returns the ASCII code of the character.

AIT_ASCIIToChar

Converts an ASCII code into the corresponding character.

19.1.7 Message operations

The API functions below define new window messages, and post a recorded message to another window.

API function name

Description

AIT_RegisterWindowMessage

Defines a window message.

AIT_PostMessage

Posts the message.

19.1.8 Registry operations

The API functions below allow the application to perform registry operations such as creating a registry key, deleting a registry key, and referencing a key value.

API function name

Description

AIT_RegCreateKey

Creates a registry key.

AIT_RegDeleteKey

Deletes a registry key.

AIT_RegDeleteValue

Deletes a registry value.

AIT_RegOpenKey

Opens a registry key.

AIT_RegCloseKey

Closes a registry key.

AIT_RegGetStringValue

Acquires a string-type value for the registry.

AIT_RegGetDWORDValue

Acquires a DWORD-type value of the registry.

AIT_RegSetStringValue

Sets a string-type value for the registry.

AIT_RegSetDWORDValue

Sets a DWORD-type value of the registry.

AIT_RegKeyExists

Checks whether the registry key exists.

AIT_RegValueExists

Checks whether the registry value exists.

19.1.9 Redirect operations

The API functions below allow the application to switch the mode in which to access registry paths or file paths.

API function name

Description

AIT_Wow64DisableWow64Redirection

Switches to the mode in which the application accesses registry paths or file paths as a 64-bit application.

AIT_Wow64RevertWow64Redirection

Switches to the mode in which the application accesses registry paths or file paths as a 32-bit application.

19.1.10 Directory operations

The API functions below allow the application to create, delete, and copy a directory.

API function name

Description

AIT_DirCreate

Creates a directory.

AIT_DirRemove

Deletes the current directory.

AIT_DirCopy

Copies a directory.

AIT_SetCurrentDirectory

Sets the current directory.

AIT_GetCurrentDirectory

Acquires the current directory.

19.1.11 File operations

The API functions below allow the application to create, copy, delete, and rename a file.

API function name

Description

AIT_FileOpen

Opens or creates the file.

AIT_FileClose

Closes the file.

AIT_FileGetLine

Acquires data from the file.

AIT_FilePutLine

Writes data into the file.

AIT_FileGetPos

Acquires the position of the file pointer.

AIT_FileSetPos

Sets the file pointer at the specified position.

AIT_FileEOF

Checks whether the file pointer is at the end of the file.

AIT_FileSize

Acquires the file size.

AIT_FileCopy

Copies the file.

AIT_FileDelete

Deletes the file.

AIT_FileExists

Checks whether the file exists.

AIT_FileRename

Renames the file.

AIT_ChangeFileAttribute

Changes the file attribute.

AIT_FindFirstFile

Finds the first file.

AIT_FindNextFile

Finds the next file.

AIT_FindCloseFile

Closes the search handle.

19.1.12 INI file operations

The API functions below allow the application to perform operations on initialization files (.INI). These operations include acquiring a key value in a section and acquiring all the contents of a section.

API function name

Description

AIT_GetProfileString

Acquires a profile string.

AIT_SetProfileString

Sets a profile string.

AIT_GetProfileFirstSection

Acquires the first section.

AIT_GetProfileNextSection

Acquires the next profile section.

AIT_GetProfileFirstSectionNames

Acquires the first section name.

AIT_GetProfileNextSectionNames

Acquires the next section name.

19.1.13 Recorder operations

The API functions below are used to create an AIT file for automatic installation.

API function name

Description

AIT_Sleep

Stops execution of the AIT file for the specified period.

AIT_SetDefaultWaitTimeout

Sets the default time-out for a wait.

AIT_Exec

Performs the specified processing.

AIT_ExecCommand

Executes the specified MS-DOS or system command.

AIT_PlayKey

Simulates keyboard entries on the active window.

19.1.14 Taskbar operations

The API functions below are used to perform taskbar operations such as checking whether a taskbar item has been clicked, and checking whether the focus is set on the taskbar.

API function name

Description

AIT_TaskbarClk

Sets a hot spot on the taskbar where a single-click of the specified mouse button can be simulated.

AIT_TaskbarHasFocus

Check whether the input focus is set on the taskbar.

AIT_TaskbarSetFocus

Sets the input focus on the taskbar.

19.1.15 Utility operations

The utility API functions below allow the application to display message and status boxes, acquire the OS type and carry out other processing.

API function name

Description

AIT_MessageBox

Displays a message box.

AIT_StatusBox

Displays a status box.

AIT_StatusBoxClose

Closes the status box.

AIT_GetEnv

Acquires the contents of an environment variable.

AIT_GetLastError

Acquires the last occurring error.

AIT_GetErrorText

Acquires an error message.

AIT_InitLog

Initializes a log file.

AIT_LogMessage

Stores a message into a log file.

AIT_Exit

Exits AIT file processing.

AIT_GetOSType

Acquires the OS type.

19.1.16 Interfacing with JP1/IT Desktop Management 2

The API function below enables interfacing with JP1/IT Desktop Management 2.

API function name

Description

AIT_DMPSTRC

Sets a global variable specific to JP1/IT Desktop Management 2.

Always specify this API function when you want to use an AIT file or perform remote installation with JP1/IT Desktop Management 2.

19.2 Details about the API functions

This section describes the API functions.

Format of API function explanations

The API functions are described in the following format. The API functions are sorted in alphabetical order.

Description

This describes the functionality of the API function.

Format

This provides the coding format of the API function.

The parameters enclosed with [] are optional. If you omit such a parameter, the default is used. Optional parameters are shown at the end of the parameter list. You can omit only the last parameter(s).

Example 1:

bool AIT_SelectListItem ( strCaption, nCtrlType, strItemText [, fTimeOut] );

For the format of the above API function, you do not need to specify fTimeOut when calling the function.

Example 2:

AIT_SelectListItem ( "Countries" LISTBOX_CTRL, "Japan" );
integer AIT_MessageBox ( strMessage, strTitle [, nIconType] [, nMsgBoxType] );

For the format of the above API function, you can call the following function with both nIconType and nMsgBoxType omitted:

AIT_MessageBox( "Hello World","Error");

If you specify nMsgBoxType but do not want to specify nIconType, the default of nIconType will be used.

AIT_MessageBox( "Hello World","Error", MB_ICONEXCLAMATION );

Parameters

This provides the parameters you can specify in the API function. There are input and output parameters. Some of the parameters are optional.

Return value

This describes the return values of the API function.

Each API has its error code returned if the API fails during processing. In an AIT file, if you need to code special error handling for special processing, you first check return codes to see whether API functions were successfully executed.

If a run-time error has occurred, the script coded in the ERROR section of the AIT file is executed automatically.

Note

This provides points you should note when executing the API function.

AIT_ASCIIToChar

Description

Converts the specified ASCII code into the corresponding character.

Format

string AIT_ASCIIToChar  (
  integer nASCIIValue     // ASCII code
);

Parameters

nASCIIValue (input)

Specify an ASCII code.

Return value

This API function returns the character corresponding to the ASCII code.

AIT_ChangeFileAttribute

Description

Changes the attribute of the specified file or directory.

Format

bool AIT_ChangeFileAttribute  (
  string strFileName,     // Filename
  integer nFileAttributes // File attribute
);

Parameters

strFileName (input)

Specify a filename. You can also specify a directory.

nFileAttributes (input)

Specify a new attribute. For the values you can use for input, see AIT_FileExists.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, use AIT_GetLastError to acquire an extended error code.

The following gives the error codes that AIT_GetLastError might return if the function has not been executed normally:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

18

ERROR_NO_MORE_FILES

21

ERROR_NOT_READY

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

183

ERROR_ALREADY_EXISTS

206

ERROR_FILENAME_EXCED_RANGE

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

AIT_CharToASCII

Description

Converts the specified character into the corresponding ASCII code.

Format

integer AIT_CharToASCII (
  string strStrName     // Character string consisting of at least one character
);

Parameters

strStrName (input)

Specify a character string.

Return value

This API function returns the ASCII code of the first character in the specified character string.

AIT_CheckResolution

Description

Checks whether the specified resolution matches the resolution of the current screen.

Format

integer AIT_CheckResolution  (
  integer nWidth,     // Width of a screen to be checked
  integer nHeight     // Height of a screen to be checked
);

Parameters

nWidth (input)

Specify the width (in units of pixels) you want to check against the width of the primary display monitor screen.

nHeight (input)

Specify the height (in units of pixels) you want to check against the height of the primary display monitor screen.

Return values

This API function returns 1 if the specified resolution matches the current resolution. Otherwise, this API function returns 0. This API function returns -1 if the function fails. In this case, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_ComboBoxCloseUp

Description

Simulates a close-up operation on the combo box.

Format

bool AIT_ComboBoxCloseUp  (
  string strCaption    // Control's caption
  [,float fTimeOut]    // Time-out
);
bool AIT_ComboBoxCloseUp  (
  integer nCtrlID     // Control ID
  [,float fTimeOut]   // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

fTimeOut (input, optional)

Specify a time-out value in units of seconds for a retry if no control has been returned. Also specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_ComboBoxDropDown

Description

Simulates a drop-down operation on the combo box.

Format

bool AIT_ComboBoxDropDown  (
  string strCaption       // Control's caption
  [,float fTimeOut]       // Time-out
);
bool AIT_ComboBoxDropDown  (
  integer nCtrlID         // Control ID
  [,float fTimeOut]       // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

fTimeOut (input, optional)

Specify the maximum time the function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_CtrlClick

Description

Simulates a mouse click on a specific control in the active window.

Format

bool AIT_CtrlClick  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nMouseButton   // Mouse button
  [,float fTimeOut]      // Time-out
);
bool AIT_CtrlClick  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nMouseButton   // Mouse button
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text control.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nMouseButton (input, optional)

Specify the mouse button for which a click operation should be simulated. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

The default is LBUTTON.

fTimeOut (input, optional)

Specify the maximum time the function can use to find a control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_CtrlItemCount

Description

Uses a specific control in the active window to acquire the number of items.

Format

bool AIT_CtrlItemCount  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nItemCount     // Number of items
  [,float fTimeOut]      // Time-out
);
bool AIT_CtrlItemCount  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nItemCount     // Item count
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

nItemCount (output)

Specify a variable for receiving the number of items in the control. When the control is returned from the function, the variable stores the number of items.

fTimeOut (input, optional)

Specify the maximum time the function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_CtrlItemIndex

Description

Uses a specific control in the active window to acquire the index of the item text.

Format

bool AIT_CtrlItemIndex  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  string strItemText,    // Item text
  integer nIndex         // Item index
  [,float fTimeOut]      // Time-out
);
bool AIT_CtrlItemIndex  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  string strItemText,    // Item text
  integer nIndex         // Item index
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

strItemText (input)

Specify an item text for acquiring an index.

nIndex (output)

Specify a variable for receiving the text index. When the function returns, the variable stores the index for the item text. The default index value is 0.

fTimeOut (input, optional)

Specify the maximum time the function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1413

ERROR_INVALID_INDEX

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_CtrlSetFocus

Description

Sets the focus on a specific control.

Format

bool AIT_CtrlSetFocus (
  string strCaption,     // Control's caption
  integer nCtrlType      // Control type
  [,float fTimeOut]      // Time-out
);
bool AIT_CtrlSetFocus (
  integer nCtrlID,       // Control ID
  integer nCtrlType      // Control type
  [,float fTimeOut]      // Time-out
);
bool AIT_CtrlSetFocus (
  integer nIndex         // Control's index
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control box is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nIndex (Can be entered)

Specify the tab order of the control.

fTimeOut (input, optional)

Specify the maximum time the function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_DefaultButtonCount

Description

Acquires the number of command buttons that have the default button style in the active window.

Format

integer AIT_DefaultButtonCount ();

Parameters

None

Return values

The return value is the number of command buttons that have the default button style if the function was executed normally, and is false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

112

ERROR_DISK_FULL

1460

ERROR_TIMEOUT

AIT_DirCopy

Description

Copies a directory to another location. If the specified copy destination directory already exists, it is overwritten.

Format

bool AIT_DirCopy  (
  string strSourceDirName,   // Copy source directory name
  string strTargetDirName    // Copy destination directory name
);

Parameters

strSourceDirName (input)

Specify a copy source directory name.

strTargetDirName (input)

Specify a copy destination directory name.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

266

ERROR_CANNOT_COPY

AIT_DirCreate

Description

Creates a new directory.

Format

bool AIT_DirCreate  (
  string strDirName    // Directory name
);

Parameters

strDirName (input)

Specify the name of a directory you want to create.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

23

ERROR_CRC

53

ERROR_BAD_NETPATH

64

ERROR_NETNAME_DELETED

82

ERROR_CANNOT_MAKE

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

183

ERROR_ALREADY_EXISTS

206

ERROR_FILENAME_EXCED_RANGE

267

ERROR_DIRECTORY

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_DirRemove

Description

Removes an existing directory.

Format

bool AIT_DirRemove  (
  string strDirName    // Directory name
);

Parameters

strDirName (input)

Specify a directory name.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

16

ERROR_CURRENT_DIRECTORY

87

ERROR_INVALID_PARAMETER

AIT_DMPSTRC

Description

Sets a global variable that is specific to JP1/Desktop Management 2. Always specify this API function when you want to use an AIT file or perform remote installation with JP1/Desktop Management 2.

This API function is called before the AIT file starts the installer.

Format

bool AIT_DMPSTRC ();

Parameters

None

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

38

ERROR_HANDLE_EOF

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

206

ERROR_FILENAME_EXCED_RANGE

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_Exec

Description

Executes a specified application file.

Format

bool AIT_Exec  (
  string strExeName,     // Application filename
  integer nShowState     // Displayed
);

Parameters

strExeName (input)

Specify an application filename.

nShowState (input)

Specify how to display the application. You have to specify one of the following values.

Value

Description

SW_HIDE

Does not display the application.

SW_SHOWNORMAL

or

SW_NORMAL

Normally displays the application.

SW_SHOWMINIMIZED

Minimize the application.

SW_SHOWMAXIMIZED

or

SW_MAXIMIZE

Maximizes the application.

SW_SHOWNOACTIVATE

Normally displays the application with no focus.

SW_SHOWMINNOACTIVE

Minimizes the application with no focus.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

87

ERROR_INVALID_PARAMETER

123

ERROR_INVALID_NAME

AIT_ExecCommand

Description

Executes an MS-DOS or system command.

Format

bool AIT_ExecCommand  (
  string strCommandName     // MS-DOS command
);

Parameters

strCommandName (input)

Specify an application filename or a system command.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

87

ERROR_INVALID_PARAMETER

123

ERROR_INVALID_NAME

AIT_ExistWindow

Description

Checks whether the window exists which matches a specified window name and class name.

Format

integer AIT_ExistWindow  (
  string strWndCaption,     // Window's caption
  string strClassName       // Class name
  [,float fTimeOut]         // Time-out
);

Parameters

strWndCaption (input)

Specify the caption of a window.

strClassName (input)

Specify a window's class name.

fTimeOut (input, optional)

Specify the maximum time the function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is 1 if the window exists, and 0 if not. If the function has not been executed successfully, the return value is -1. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

AIT_Exit

Description

Exits the AIT file.

Format

AIT_Exit ();

Parameters

None

Return values

None

AIT_FileClose

Description

Closes a file handle.

Format

bool AIT_FileClose  (
  integer nFileHandle     // File handle
);

Parameters

nFileHandle (input)

Specify a file handle you have opened using the AIT_FileOpen function.

Return values

The return value is true if the function was executed normally, and false if not.

If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

4

ERROR_TOO_MANY_OPEN_FILES

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

AIT_FileCopy

Description

Copies a copy source file to a copy destination file. If the specified copy destination file already exists, it is overwritten.

Format

bool AIT_FileCopy  (
  string strSourceFileName,     // Copy source filename
  string strTargetFileName      // Copy destination filename
);

Parameters

strSourceFileName (input)

Specify a copy source filename. You can also use a wildcard (*).

strTargetFileName (input)

Specify a copy destination file or directory name. You cannot use the wild card. If the specified copy destination directory does not exist, it is created.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

87

ERROR_INVALID_PARAMETER

117

ERROR_INVALID_CATEGORY

AIT_FileDelete

Description

Deletes a specified file.

Format

bool AIT_FileDelete  (
  string strFileName     // Filename
);

Parameters

strFileName (input)

Specify the name of a file you want to remove. You can also use a wildcard (*).

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

53

ERROR_BAD_NETPATH

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_FileEOF

Description

Checks whether the file pointer has reached the EOF.

Format

integer AIT_FileEOF (
  integer nFileHandle     // File handle
);

Parameters

nFileHandle (input)

Specify a file handle.

Return values

The return value is 1 if the file pointer has reached the EOF, and 0 if not. If the function has not been executed, the return value is -1. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

AIT_FileExists

Description

Checks whether the file with a specified attribute exists.

Format

integer AIT_FileExists  (
  string strFileName            // Filename
  [,integer nFileAttributes]    // File attribute
);

Parameters

strFileName (input)

Specify the name of a file to be found.

nFileAttributes (input, optional)

Specify a file attribute, which must be one of the following values.

Value

Description

FILE_ATTRIBUTE_DIRECTORY

The file is a directory.

FILE_ATTRIBUTE_HIDDEN

The file is a hidden one.

FILE_ATTRIBUTE_SYSTEM

The file is part of the OS, or is OS-specific.

FILE_ATTRIBUTE_ARCHIVE

The file is an archive one. The application uses this attribute as a mark for file backup or deletion.

FILE_ATTRIBUTE_READONLY

The file is a read-only one. The application can read the file, but cannot program and delete it.

By default, a file is detected independent of the file attribute.

Return values

The return value is 1 if the file exists, and 0 if not. If the function has not been executed successfully, the return value is -1. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

998

ERROR_NOACCESS

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_FileGetLine

Description

Reads data from a specified file.

Format

bool AIT_FileGetLine  (
  integer nFileHandle,    // File handle
  string strReadData      // Data to be read from the file
);

Parameters

nFileHandle (input)

Specify a file handle.

strReadData (output)

Specify a variable for receiving data to be read from the file. When the function returns, the variable stores data.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

38

ERROR_HANDLE_EOF

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

AIT_FileGetPos

Description

Acquires the current position of the file pointer.

Format

bool AIT_FileGetPos  (
  integer nFileHandle,    // File handle
  integer nFilePos        // Current file pointer position
);

Parameters

nFileHandle (input)

Specify a file handle.

nFilePos (output)

Specify a variable for receiving the current position of the file pointer. When the function returns, the variable stores the pointer position.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

38

ERROR_HANDLE_EOF

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

AIT_FileOpen

Description

Opens an existing file, or creates a new file in set access mode.

Format

bool AIT_FileOpen  (
  string strFileName,     // Filename
  integer nAccessMode,    // Access mode
  integer nOperation,     // How to create
  integer nFileHandle     // File handle
);

Parameters

strFileName (input)

Specify the name of a file you want to create or open.

nAccessMode (input)

Specify mode of access to a file, which must be one or combination of the following values.

Value

Description

GENERIC_READ

Specify access to a file to be read. You can read data from the file and move the file pointer. To set mode of reading/writing access, specify the mode in combination with GENERIC_WRITE.

GENERIC_WRITE

Specify access to a file to be programmed. You can program the file with data, and move the file pointer. To set mode of reading/writing access, specify the mode in combination with GENERIC_READ.

nOperation (input)

Specify how to handle a file when it exists or does not exist. You have to set one of the following values.

Value

Description

CREATE_NEW

Creates a file. If a specified file already exists, the function will not be executed successfully.

CREATE_ALWAYS

Creates a new file. If a specified file already exists, the function overwrites the file.

OPEN_EXISTING

Opens a file. If a specified file does not exist, the function will not be executed successfully.

OPEN_ALWAYS

Opens a specified file if it exists. If a specified file does not exist, it is created.

TRUNCATE_EXISTING

Opens a file. The opened file is arranged for the 0-byte size. You have to specify at least GENERIC_WRITE access in a calling process to open a file. If no file exists, the function will not be executed successfully.

nFileHandle (output)

Specify a variable for receiving a file handle. When the function returns, the variable stores the file handle.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

4

ERROR_TOO_MANY_OPEN_FILES

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

18

ERROR_NO_MORE_FILES

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

53

ERROR_BAD_NETPATH

80

ERROR_FILE_EXISTS

82

ERROR_CANNOT_MAKE

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

183

ERROR_ALREADY_EXISTS

206

ERROR_FILENAME_EXCED_RANGE

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Note

Use the AIT_FileClose function to close a file handle returned by AIT_OpenFile.

AIT_FilePutLine

Description

Writes data into a specified file.

Format

bool AIT_FilePutLine  (
  integer nFileHandle,     // File handle
  string strWriteData      // Data to be written into a file
);

Parameters

nFileHandle (input)

Specify a file handle.

strWriteData (input)

Specify data to be written into a file.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

38

ERROR_HANDLE_EOF

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Notes

If you specify that zero bytes be written, the system considers that null writing operations are specified.

The AIT_FilePutLine function writes data at the current file pointer position, which is updated after writing operations.

AIT_FileRename

Description

Change a file or directory name.

Format

bool AIT_FileRename (
  string strFileName,       // Current filename
  string strNewFileName     // New filename
);

Parameters

strFileName (input)

Specify a file or directory name you want to change.

strNewFileName (input)

Specify a new file or directory name.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

38

ERROR_HANDLE_EOF

53

ERROR_BAD_NETPATH

80

ERROR_FILE_EXISTS

82

ERROR_CANNOT_MAKE

87

ERROR_INVALID_PARAMETER

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_FileSetPos

Description

Sets the file pointer at a specified position.

Format

bool AIT_FileSetPos  (
  integer nFileHandle,     // File handle
  integer nSetPos          // New file pointer position
);

Parameters

nFileHandle (input)

Specify a file handle.

nSetPos (input)

Specify a new file pointer position.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

19

ERROR_WRITE_PROTECT

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

38

ERROR_HANDLE_EOF

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Notes

You must not use the file pointer indicated by the nFileHandle parameter value for duplicate reading or writing operations.

If you execute this function with the new file pointer position set at 0, the current file pointer position will be held.

AIT_FileSize

Description

Acquires a file size.

Format

bool AIT_FileSize  (
  integer nFileHandle,     // File handle
  integer nFileSize        // File size
);

Parameters

nFileHandle (input)

Specify a file handle.

nFileSize (output)

Specify a variable for receiving a file size. When the function returns, the variable stores the file size.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

21

ERROR_NOT_READY

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

38

ERROR_HANDLE_EOF

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Note

The AIT_FileSize function acquires a file size not compressed.

AIT_FindCloseFile

Description

Closes a file search handle returned by the AIT_FindFirstFile function.

Format

bool AIT_FindCloseFile  (
  integer nSearchHandle     // File search handle
);

Parameters

nSearchHandle (input)

Specify a file search handle returned by the AIT_FindFirstFile function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

112

ERROR_DISK_FULL

Note

After having called the AIT_FindClose function, you cannot use the handle set in the nSearchHandle parameter to subsequently call the AIT_FindNextFile or AIT_FindCloseFile function.

AIT_FindFirstFile

Description

Uses a file search handle to return the first filename that matches a specified filename.

Format

bool AIT_FindFirstFile  (
  string strFileNamePattern,    // Filename
  string strFileName,           // Found filename
  integer nSearchHandle         // File search handle
);

Parameters

strFileNamePattern (input)

Specify a valid directory name, path or filename. You can also use a wildcard (*). If the character string ends with the wild card, period or directory name, the user must be authorized to access all the subdirectories on the path.

strFileName (output)

Specify a variable for receiving the name of a found file that matches a set filename. When the function returns, the variable stores the found filename.

nSearchHandle (output)

Specify a variable for receiving a file search handle to be used to subsequently find AIT_FindNextFile and AIT_FindCloseFile. When the function returns, the variable stores the file search handle.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

18

ERROR_NO_MORE_FILES

21

ERROR_NOT_READY

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

Notes

This function uses only a filename to find the file. It cannot use an attribute to find the file. Independent of the presence or absence of subsequent \, you cannot specify the root directory as a strFileName input character string for AIT_FindFirstFile.

Use AIT_FindCloseFile to close a file search handle returned by AIT_FindFirstFile.

AIT_FindNextFile

Description

Uses a search handle returned by the AIT_FindFirstFile function to find the next file.

Format

bool AIT_FindNextFile  (
  integer nSearchHandle,     // File search handle
  string strFileName         // Found filename
);

Parameters

nSearchHandle (input)

Specify a file search handle returned in response to previously called AIT_FindFirstFile.

strFileName (output)

Specify a variable for receiving a found filename. When the function returns, the variable stores the found filename.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

18

ERROR_NO_MORE_FILES

21

ERROR_NOT_READY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

148

ERROR_PATH_BUSY

1231

ERROR_NETWORK_UNREACHABLE

Note

This function uses only a name to find the file. It cannot use any attributes to find the file.

AIT_FindSubStr

Description

Finds a specified character string from the position specified in nStartPos, and returns the first matching character string position.

Format

integer AIT_FindSubStr  (
  string strStrName,         // Character string
  string strSearchStr        // Character string to be found
  [,integer nStartPos]       // Character position at which to start finding
);

Parameters

strStrName (input)

Specify a character string.

strSearchStr (input)

Specify a character string to be found.

nStartPos (input, optional)

Specify the position at which to start finding a character string. The default nStartPos value is 0, which corresponds to the first character of a character string. By default, this operation starts at the first character.

Return values

This API function returns the 0-based index for the first character of the target character string. This API function returns -1 if no character string exists or the null character string is specified.

You can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_FocusWindow

Description

Acquires a window handle having specified window and class names, and sets the focus.

Format

integer AIT_FocusWindow  (
  string strWndCaption,     // Window's caption
  string strClassName       // Class name
  [,float fTimeOut]         // Time-out
);

Parameters

strWndCaption (input)

Specify the caption of a window.

strClassName (input)

Specify a window's class name.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is the window handle if the function was executed normally, and 0 if not. If the function has returned 0, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

With an empty character string set in strWndCaption, the function finds the window with a blank caption. If multiple windows have a blank caption, the focus is set to the first found window.

AIT_GetCtrlText

Description

Acquires text from a specific control in the active window.

Format

bool AIT_GetCtrlText  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  string strCtrlText     // Control's text
  [,float fTimeOut]      // Time-out
);
bool AIT_GetCtrlText  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  string strCtrlText     // Control's text
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text control.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

strCtrlText (output)

Specify a variable to receive the text of a control. When the function returns, the variable stores text.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

For an edit box, the function acquires a text for its contents. For a static text and button, it acquires a control's caption. For the other controls, it acquires the currently selected item as the text.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetCtrlTextLen

Description

Acquires the text length from a specific control in the active window.

Format

bool AIT_GetCtrlTextLen  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nTextLen       // Control text length
  [,float fTimeOut]      // Time-out
);
bool AIT_GetCtrlTextLen  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nTextLen       // Control text length
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nTextLen (output)

Specify a variable to receive the text length of the control. When the function returns, the variable stores the text length.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetCurrentDirectory

Description

Acquires the current directory.

Format

bool AIT_GetCurrentDirectory  (
  string strDirName      // Directory name
);

Parameters

strDirName (output)

Specify a variable to receive a directory name. When the function returns, the variable stores the directory name.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

AIT_GetDate

Description

Acquires the system date in the short format.

Format

string AIT_GetDate ();

Parameters

None

Return value

The system date is returned in the short format as a character string.

AIT_GetDtPickerDate

Description

Acquires a date from the date/time picker.

Format

bool AIT_GetDtPickerDate  (
  string strCaption,    // Control's caption
  string strOutDate     // Control's date
  [,float fTimeOut]     // Time-out
);
bool AIT_GetDtPickerDate  (
  string strCaption,    // Control's caption
  integer nYear,        // Year
  integer nMonth,       // Month
  integer nDay          // Day
  [,float fTimeOut]     // Time-out
);
bool AIT_GetDtPickerDate  (
  integer nCtrlID,      // Control ID
  string strOutDate     // Control's date
  [,float fTimeOut]     // Time-out
);
bool AIT_GetDtPickerDate  (
  integer nCtrlID,     // Control ID
  integer nYear,       // Year
  integer nMonth,      // Month
  integer nDay         // Day
  [,float fTimeOut]    // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

strOutDate (output)

Specify a variable to receive the date value of a control. When the function returns, the variable stores the date in the MM/DD/YYYY format where MM indicates the month, DD indicates the day, and YYYY indicates the year.

nYear (output)

Specify a variable to receive a control's year value. When the function returns, the variable stores the year value.

nMonth (output)

Specify a variable to receive a control's month value. When the function returns, the variable stores the month value.

nDay (output)

Specify a variable to receive a control's day value. When the function returns, the variable stores the day value.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the time set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetDtPickerTime

Description

Acquires time for the date/time picker.

Format

bool AIT_GetDtPickerTime  (
  string strCaption,    // Control's caption
  string strOutTime     // Control time
  [,float fTimeOut]     // Time-out
);
bool AIT_GetDtPickerTime  (
  string strCaption,    // Control ID
  integer nHour,        // Hours
  integer nMinute,      // Minutes
  integer nSecond       // Seconds
  [,float fTimeOut]     // Time-out
);
bool AIT_GetDtPickerTime  (
  integer nCtrlID,      // Control ID
  string strOutTime     // Control time
  [,float fTimeOut]     // Time-out
);
bool AIT_SetDtPickerTime  (
  integer nCtrlID,      // Control ID
  integer nHour,        // Hours
  integer nMinute,      // Minutes
  integer nSecond       // Seconds
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

strOutTime (output)

Sets a variable to receive a control time value. When the function returns, the variable stores the time value in the hh:mm:ss format where hh indicates the hour, mm indicates the minute, and ss indicates the second.

nHour (output)

Specify a variable to receive a control hour value. When the function returns, the variable stores the hour value.

nMinute (output)

Specify a variable to receive a control minute value. When the function returns, the variable stores the minute value.

nSecond (output)

Specify a variable to receive a control seconds value. When the function returns, the variable stores the seconds value.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetEditCurrentLineIndex

Description

Acquires the index of the current line in an edit box containing multiple lines. Data is entered into the current line.

Format

bool AIT_GetEditCurrentLineIndex  (
  string strCaption,   // Control's caption
  integer nIndex       // Current line's index
  [,float fTimeOut]    // Time-out
);
bool AIT_GetEditCurrentLineIndex  (
  integer nCtrlID,     // Control ID
  integer nIndex       // Current line's index
  [,float fTimeOut]    // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nIndex (output)

Specify a variable to receive the index of the current line. When the function returns, the variable stores the index. The default index value is 0.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetEditFirstLineIndex

Description

Acquires the index of the first line in the edit box containing multiple lines, or for the first character in the edit box containing a single line.

Format

bool AIT_GetEditFirstLineIndex  (
  string strCaption,      // Control's caption
  integer nFirstVisible   // Index for the first line or character
  [,float fTimeOut]       // Time-out
);
bool AIT_GetEditFirstLineIndex  (
  integer nCtrlID,        // Control ID
  integer nFirstVisible   // Index for the first line or character
  [,float fTimeOut]       // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nFirstVisible (output)

Specify the variable for receiving the index value for the first line or character. When the function returns, the variable stores the index. The default index value is 0.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetEditTextLineLen

Description

Acquires the length of any line in the edit box containing multiple lines in the active window.

Format

bool AIT_GetEditTextLineLen  (
  string strCaption,    // Control's caption
  integer nLineIndex,   // Line's index
  integer nLineLength   // Line length
  [,float fTimeOut]     // Time-out
);
bool AIT_GetEditTextLineLen  (
  integer nCtrlID,      // Control ID
  integer nLineIndex,   // Line's index
  integer nLineLength   // Line length
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nLineIndex (input)

Specify the index of the edit box containing multiple lines. The default index value is 0.

nLineLength (output)

Specify a variable to receive the length of the index of a line set in nLineIndex. When the function returns, the variable stores the length.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetEnv

Description

Acquires the contents of a set environment variable.

Format

string AIT_GetEnv  (
  string strEnvVar     // Environment variable name
);

Parameters

strEnvVar (input)

Specify an environment variable name.

Return value

This API function returns the contents of the environment variable.

AIT_GetErrorText

Description

Acquires the system error text corresponding to a specified error code.

Format

string AIT_GetErrorText  (
  integer nErrorCode     // Error code
);

Parameters

nErrorCode (input)

Specify the error code returned by the AIT_GetLastError function.

Return value

This API function returns the error message corresponding to a specified error code.

AIT_GetIndexText

Description

Acquires the item text specified by an index from a specific control in the active window.

Format

bool AIT_GetIndexText  (
  string strCaption,    // Control's caption
  integer nCtrlType,    // Control type
  integer nIndex,       // Index
  string strItemText    // Item text
  [,float fTimeOut]     // Time-out
);
bool AIT_GetIndexText  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  integer nIndex,       // Index
  string strItemText    // Item text
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a comb box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

nIndex (input)

Specify the index of the item text you want to acquire. The default index value is 0.

strItemText (output)

Specify a variable to receive the item text with an index set on the control. When the function returns, the variable stores the item text.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1413

ERROR_INVALID_INDEX

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetIndexTextLen

Description

Acquires the length of the item text specified by an index from a specific control in the active window.

Format

bool AIT_GetIndexTextLen  (
  string strCaption,    // Control's caption
  integer nCtrlType,    // Control type
  integer nIndex,       // Index
  integer nTextLen      // Text length
  [,float fTimeOut]     // Time-out
);
bool AIT_GetIndexTextLen  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  integer nIndex,       // Index
  integer nTextLen      // Text length
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

nIndex (input)

Specify the index of the item text you want to acquire. The default index value is 0.

nTextLen (output)

Specify a variable to receive the length of the item text with an index set on the control. When the function returns, the variable stores the length of the item text.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_GetKeyState

Description

Acquires key status.

Format

int AIT_GetKeyState  (
  integer nVirtualKey    // Virtual key
);

Parameters

nVirtualKey (input)

Specify a virtual key code whose key status you want to acquire.

You have to set one of the following values.

Value

Description

NUMLOCK

Num Lock key

SCROLLLOCK

Scroll Lock key

CAPSLOCK

Caps Lock key

Return values

The return value is 1 if the key is on, and 0 if it is off. The return value is -1 if the function has not been executed successfully.

If the function has returned -1, you can use AIT_GetLastError to acquire an extended code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_GetLastError

Description

Acquires a detailed code on the previously executed function.

Format

integer AIT_GetLastError ();

Parameters

None

Return value

This API function returns a detailed code, which is the same as a run time error code.

AIT_GetMenu

Description

Used to acquire a menu handle for a window.

Format

bool AIT_GetMenu  (
  integer nWndHandle,    // Window handle
  integer nMenu          // Menu handle
  [,float fTimeOut]      // Time-out
);

Parameters

nWndHandle (input)

Specify a window handle.

nMenu (output)

Specify a variable to receive a menu handle. When the function returns, the variable stores the handle.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

AIT_GetMenuIndex

Description

Acquires the index of a specified menu item.

Format

bool AIT_GetMenuIndex  (
  integer nMenu,         // Menu handle
  string strMenuText,    // Menu item
  integer nIndex         // Index for a menu item
  [,float fTimeOut]      // Time-out
);

Parameters

nMenu (input)

Specify a menu handle.

strMenuText (input)

Specify a menu item.

nIndex (output)

Specify a variable to receive the index of a menu item. When the function returns, the variable stores the index. The default index value is 0.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

112

ERROR_DISK_FULL

1401

ERROR_INVALID_MENU_HANDLE

1460

ERROR_TIMEOUT

AIT_GetMenuText

Description

Acquires a specified menu item.

Format

bool AIT_GetMenuText  (
  integer nMenu,        // Menu handle
  integer nIndex,       // Index for a menu item
  string strMenuText    // Menu item
  [,float fTimeOut]     // Time-out
);

Parameters

nMenu (input)

Specify a menu handle.

nIndex (input)

Specify the index of a menu item. The default index value is 0.

strMenuText (output)

Specify a variable to receive a menu item. When the function returns, the variable stores the menu item.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1401

ERROR_INVALID_MENU_HANDLE

1460

ERROR_TIMEOUT

AIT_GetOSType

Description

Acquires major and minor OS versions, and a platform ID.

Format

bool AIT_GetOSType  (
  integer nMajorVersion,    // Major OS version
  integer nMinorVersion,    // Minor OS version
  integer nPlatformID       // Platform ID
);

Parameters

nMajorVersion (output)

Specify a variable to receive a major OS version. When the function returns, the variable stores one of the following values.

Value

Description

5

Windows XP

5

Windows Server 2003

6

Windows Vista

6

Windows Server 2008

6

Windows 7

6

Windows Server 2012

6

Windows Server 2012 R2

6

Windows 8

6

Windows 8.1

10

Windows 10

10

Windows Server 2016

10

Windows Server 2019

10

Windows Server 2022

10

Windows 11

nMinorVersion (output)

Specify a variable to receive a minor OS version. When the function returns, the variable stores one of the following values.

Value

Description

1

Windows XP

2

Windows Server 2003

0

Windows Vista

0

Windows Server 2008

1

Windows Server 2008 R2

1

Windows 7

2

Windows Server 2012

3

Windows Server 2012 R2

2

Windows 8

3

Windows 8.1

0

Windows 10

0

Windows Server 2016

0

Windows Server 2019

0

Windows Server 2022

0

Windows 11

nPlatformID (output)

Specify a variable to receive an OS platform ID. When the function returns, the variable stores one of the following values.

Value

Description

VER_PLATFORM_WIN32_NT

Windows 11, Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012 R2, Windows Server 2012, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

122

ERROR_INSUFFICIENT_BUFFER

Note

You have to use a desired version number or a greater number to identify what OS version the application is working on. This allows you to test even a new OS version in the same way.

AIT_GetProfileFirstSection

Description

Acquires the first key and its value from a specified INI file section.

Format

bool AIT_GetProfileFirstSection  (
  string strIniFileName,     // INI filename
  string strSectionName,     // INI file's section name
  string strValues           // Section data
);

Parameters

strIniFileName (input)

Specify an INI filename.

strSectionName (input)

Specify the name of a section in an INI file.

strValues (output)

Specify a variable to receive a key and its value from a set section. When the function returns, the variable stores a key and its value. A key and its value are combined in the key=value format.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

38

ERROR_HANDLE_EOF

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

998

ERROR_NOACCESS

1005

ERROR_UNRECOGNIZED_VOLUME

1169

ERROR_NO_MATCH

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_GetProfileFirstSectionNames

Description

Acquires the name of the first section in a specified INI file.

Format

bool AIT_GetProfileFirstSectionNames  (
  string strIniFileName,     // INI filename
  string strSectionName      // Section name
);

Parameters

strIniFileName (input)

Specify an INI filename.

strSectionName (output)

Specify a variable to receive the first section name from a specified INI file. When the function returns, the variable stores the section name.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

998

ERROR_NOACCESS

1005

ERROR_UNRECOGNIZED_VOLUME

1169

ERROR_NO_MATCH

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_GetProfileNextSection

Description

Acquires the next key and its value from a section in an INI file specified in the AIT_GetProfileFirstSection function.

Format

bool AIT_GetProfileNextSection  (
  string strValues       // Sectional data
);

Parameters

strValues (output)

Specify a variable to receive the next key in a section set in AIT_GetProfileFirstSection, and its value. When the function returns, the variable stores the key and its value. A key and its value are combined in the key=value format.

Return values

The return value is true if the function was executed normally, and false if not. If the key, the section or the specified INI file does not exist, the function returns false.

AIT_GetProfileNextSectionNames

Description

Acquires the next section name from an INI file specified in the AIT_GetProfileFirstSectionNames function.

Format

bool AIT_GetProfileNextSectionNames  (
  string strSectionName       // Section name
);

Parameters

strSectionName (output)

Specify a variable to receive the next section name in an INI file set in AIT_GetProfileFirstSectionNames. When the function returns, the variable stores the section name.

Return values

The return value is true if the function was executed normally, and false if not. If the key, the section or the specified INI file does not exist, the function returns false.

AIT_GetProfileString

Description

Acquires the value of a specified key from a section in a specified INI file.

Format

bool AIT_GetProfileString  (
  string strIniFileName,     // INI filename
  string strSectionName,     // Section name
  string strKeyName,         // Key name
  string strValue            // Key value
);

Parameters

strIniFileName (input)

Specify an INI filename.

strSectionName (input)

Specify a section name in an INI file.

strKeyName (input)

Specify a key name belonging to a section name.

strValue (output)

Specify a variable to receive a key value. When the function returns, the variable stores the key value.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

38

ERROR_HANDLE_EOF

53

ERROR_BAD_NETPATH

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

998

ERROR_NOACCESS

1005

ERROR_UNRECOGNIZED_VOLUME

1169

ERROR_NO_MATCH

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

AIT_GetSubMenu

Description

Acquires a submenu handle in a menu.

Format

bool AIT_GetSubMenu  (
  integer nMenu,      // Menu handle
  integer nIndex,     // Index for a menu item
  integer nSubMenu    // Submenu handle
  [,float fTimeOut]   // Time-out
);

Parameters

nMenu (input)

Specify a menu handle you have got by calling the AIT_GetMenu function.

nIndex (input)

Specify the index of a menu item. The default index value is 0.

nSubMenu (output)

Specify a variable to receive a submenu handle. When the function returns, the variable stores the handle.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1401

ERROR_INVALID_MENU_HANDLE

1460

ERROR_TIMEOUT

AIT_GetSubStr

Description

This API function returns a character string of specified length from a character string.

Format

bool AIT_GetSubStr (
  string  strSubString,      // Extracted character string
  string  strStrName,        // Character string
  integer nStartPos          // Character position at which to start extraction
  [,integer nLength]         // Number of characters
);

Parameters

strSubString (output)

Specify a variable to receive an extracted character string. When the function returns, the variable stores the character string.

strStrName (input)

Specify a character string name.

nStartPos (input)

Specify a character position at which to start extraction. The default is 0, corresponding to the first character of a character string.

nLength (input, optional)

Specify the number of characters you want to extract. So long as this parameter does not exceed the number of characters in a character string, the character string with a character count set from nStartPos is extracted. The default is the length to the end string character.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_GetTime

Description

Acquires system time.

Format

string AIT_GetTime ();

Parameters

None

Return value

Acquires system time.

AIT_GetWindowText

Description

Acquires the title of a specified window.

Format

bool AIT_GetWindowText  (
  integer nWndHandle,     // Window handle
  string strCaption       // Control's caption
);

Parameters

nWndHandle (input)

Specify a window handle. Acquires the title of the active window with 0 set.

strCaption (output)

Specify a variable to receive a control's caption. When the function returns, the variable stores the caption.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMEGetConversionStatus

Description

Acquires the current status of IME conversion.

Format

bool AIT_IMEGetConversionStatus  (
  integer nWndHandle,     // Window handle
  integer nConvMode,      // Conversion mode
  integer nSentenceMode   // Statement mode
);

Parameters

nWndHandle (input)

Specify a window handle whose status you want to acquire.

With 0 set, the window with an input focus is used.

nConvMode (output)

Specify a variable to receive conversion status. When the function returns, the variable stores a combination of the following values.

Value

Description

IME_CMODE_CHARCODE

With this value on, the IME is in character code input mode.

IME_CMODE_EUDC

With this value on, the IME is in EUDC conversion mode.

IME_CMODE_FULLSHAPE

With this value on, the IME is in two-byte mode. With this value off, it is in one-byte mode.

IME_CMODE_HANJACONVERT

With this value on, the IME is in HANJA conversion mode.

IME_CMODE_KATAKANA

With this value on, katakana mode is set. With this value off, kana mode is set.

IME_CMODE_NATIVE

With this value on, NATIVE mode is set. With this value off, ALPHANUMERIC mode is set.

IME_CMODE_NOCONVERSION

With this value on, the IME does not carry out conversion. This is the same as if IME were closed.

IME_CMODE_ROMAN

With this value on, the IME is in alphabetic input mode.

IME_CMODE_SOFTKBD

With this value on, the IME is in soft keyboard mode.

IME_CMODE_SYMBOL

With this value on, the IME is in SYMBOL conversion mode.

nSentenceMode (output)

Specify a variable to receive character mode. When the function returns, the variable stores a combination of the following values.

Value

Description

IME_SMODE_AUTOMATIC

The IME is set in automatic conversion mode.

IME_SMODE_NONE

No sentence information.

IME_SMODE_PHRASEPREDICT

The IME uses phrase information to predict the next character. (Continuous clause)

IME_SMODE_PLURALCLAUSE

The IME uses multiple-clause information for conversion processing. (Complex words are prioritized.)

IME_SMODE_SINGLECONVERT

The IME is set in single conversion mode.

IME_SMODE_CONVERSATION

The IME uses conversion mode.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMEGetOpenStatus

Description

Checks to see if the IME is open or closed.

Format

integer AIT_IMEGetOpenStatus  (
  [integer nWndHandle]     // Window handle
);

Parameters

nWndHandle (input, optional)

Specify a window handle whose status you want to acquire.

By default, the window with an input focus is used.

Return values

The return value is 1 if the IME is open, 0 if it is closed, and -1 if the function has not been processed successfully.

If the function has returned -1, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMEGetProperty

Description

Acquires IME properties or functionalities associated with an input focus window.

Format

integer AIT_IMEGetProperty  (
  integer nPropertyInfo     // Property information
);

Parameters

nPropertyInfo (input)

Specify property information you want to acquire. You have to set one of the following values.

Value

Description

IGP_PROPERTY

Property information

IGP_CONVERSION

Conversion functionality

IGP_SENTENCE

Sentence mode functionality

IGP_UI

User interface functionality

IGP_SETCOMPSTR

Composition character string functionality

IGP_SELECT

Selection inheritance functionality

Return values

The value returned if the function was executed normally is the property or functionality value corresponding to the nPropertyInfo value. In the other cases, the return value is -1.

The value returned if nPropertyInfo is IGP_PROPERTY is a combination of the following values.

Value

Description

IME_PROP_AT_CARET

With this value on, the conversion window is at the caret position. If not, it is near the caret.

IME_PROP_SPECIAL_UI

With this value on, the IME has no standard user interface. In this case, do not use the application to draw in the IME window.

IME_PROP_CANDLIST_START_FROM_1

With this value on, the character strings in a candidate list are numbered in sequence beginning with 1. If not, they are numbered in sequence beginning with 0.

IME_PROP_UNICODE

With this value on, the input context character string contains Unicode characters. If not, it contains one- and two-byte characters.

If nPropertyInfo is IGP_UI, the return value is a combination of the following values.

Value

Description

UI_CAP_2700

Supports a value of 0 or 2700 as the text printing direction.

UI_CAP_ROT90

Supports values of 0, 900, 1800, and 2700 as the text printing direction.

UI_CAP_ROTANY

Supports any printing direction.

If nPropertyInfo is IGP_SETCOMPSTR, the return value is a combination of the values below.

Value

Description

SCS_CAP_COMPSTR

You can use the SCS_SETSTR value of IMESetCompositionString to create a composition character string.

SCS_CAP_MAKEREAD

You can use the SCS_SETSTR value of IMESetCompositionString to create a read character string from the appropriate composition character string.

If nPropertyInfo is IGP_SELECT, the return value is a combination of the values below.

Value

Description

SELECT_CAP_CONVERSION

Inherits conversion mode if a new IME has been selected.

SELECT_CAP_SENTENCE

Inherits sentence mode if a new IME has been selected.

If the function has returned -1, you can use AIT_GetLastError to acquire an extended error code.

The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_IMEGetStatusWindowPos

Description

Acquires the position of a status window.

Format

bool AIT_IMEGetStatusWindowPos  (
  integer nWndHandle,     // Window handle
  integer nX,             // X coordinate
  integer nY              // Y coordinate
);

Parameters

nWndHandle (input)

Specify a window handled to be used to acquire a status window position.

With 0 set, the window handle with an input focus is used.

nX (output)

Specify a variable to receive the X coordinate of a status window. When the function returns, the variable stores this value.

nY (output)

Specify a variable to receive the Y coordinate of a status window. When the function returns, the variable stores this value.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMESetConversionStatus

Description

Sets the current conversion status.

Format

bool AIT_IMESetConversionStatus  (
  integer nWndHandle,     // Window handle
  integer nConvMode,      // Conversion mode
  integer nSentenceMode   // Statement mode
);

Parameters

nWndHandle (input)

Specify a window handle to which to set status.

With 0 set, the window handle with an input focus is used.

nConvMode (input)

Specify a combination of conversion modes.

For details on bit values, see AIT_IMEGetConversionStatus.

nSentenceMode (input)

Specify statement mode.

For details on bit values, see AIT_IMEGetConversionStatus.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMESetOpenStatus

Description

Opens and closes the IME.

Format

bool AIT_IMESetOpenStatus  (
  integer nWndHandle,     // Window handle
  bool bCondition         // Condition
);

Parameters

nWndHandle (input)

Specify a window handle to be assigned status.

With 0 set, the window handle with an input focus is used.

bCondition (input)

Specify whether to open or close the IME. Setting true opens the IME, while setting false closes the IME.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMESetStatusWindowPos

Description

Sets the position of a status window.

Format

bool AIT_IMESetStatusWindowPos  (
  integer nWndHandle,     // Window handle
  integer nX,             // X coordinate
  integer nY              // Y coordinate
);

Parameters

nWndHandle (input)

Specify a window handle to be positioned.

With 0 set, the window handle with an input focus is used.

nX (input)

Specify the X coordinate of a status window.

nY (input)

Specify the Y coordinate of a status window.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_IMESimulateHotKey

Description

Simulates a specified IME hot key.

Format

bool AIT_IMESimulateHotKey  (
  integer nWndHandle,     // Window handle
  integer nHotKeyId       // Hot key ID
);

Parameters

nWndHandle (input)

Specify a window handle.

nHotKeyId (input)

Specify the ID of an IME hot key, which must be one of the following values.

Value

Description

IME_CHOTKEY_IME_NONIME_TOGGLE

This hot key used in the simplified Chinese version switches between IME operation and non-IME operation.

IME_CHOTKEY_SHAPE_TOGGLE

This hot key used in the simplified Chinese version selects appropriate IME shape conversion mode.

IME_CHOTKEY_SYMBOL_TOGGLE

This hot key used in the simplified Chinese version selects appropriate IME shape conversion mode. You can enter Chinese segmentations and two-byte symbols if you assign the keyboard them.

IME_JHOTKEY_CLOSE_OPEN

This hot key used in the Japanese version opens and closes the IME.

IME_KHOTKEY_ENGLISH

This hot key used in the Korean version translates into English.

IME_KHOTKEY_SHAPE_TOGGLE

This hot key used in the Korean version selects appropriate IME shape conversion mode.

IME_KHOTKEY_HANJACONVERT

This hot key used in the Korean version selects conversion to Hanja mode.

IME_THOTKEY_IME_NONIME_TOGGLE

This hot key used in the traditional Chinese version switches between IME operation and non-IME operation.

IME_THOTKEY_SHAPE_TOGGLE

This hot key used in the traditional Chinese version selects appropriate IME shape conversion mode.

IME_THOTKEY_SYMBOL_TOGGLE

This hot key used in the traditional Chinese version selects appropriate IME symbol conversion mode.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_InitLog

Description

Initializes a RecDFile.log file to be used by the AIT_LogMessage function. Before executing the AIT_LogMessage function, be sure to execute this function.

The RecDFile.log file exists in the LOG directory path specified by either of the following registry key values.

When the OS is a 32-bit version:

HKEY_LOCAL_MACHINE\SOFTWARE\HITACHI\IT DESKTOP MANAGEMENT 2/P\PathName

When the OS is a 64-bit version:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Hitachi\IT DESKTOP MANAGEMENT 2/P\PathName

Format

bool AIT_InitLog  (
  string strMessage     // Message character string
);

Parameters

strMessage (input)

Specify a character string message you want to write into a log file.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

3

ERROR_PATH_NOT_FOUND

4

ERROR_TOO_MANY_OPEN_FILES

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

19

ERROR_WRITE_PROTECT

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

53

ERROR_BAD_NETPATH

82

ERROR_CANNOT_MAKE

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

183

ERROR_ALREADY_EXISTS

206

ERROR_FILENAME_EXCED_RANGE

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Notes

If you have run this function, the previous RecDFile.log is changed to Rec1File.log, with a maximum of five files saved as history.

This function records the current date and time as well as messages.

AIT_IsEmpty

Description

Checks to see if the entered character string is empty.

Format

bool AIT_IsEmpty (
  string strStrName     // Character string name
);

Parameters

strStrName (input)

Specify a character string name.

Return values

This API function returns true if the character string is empty, and false if not.

AIT_LogMessage

Description

Saves a message into a RecDFile.log file opened by the AIT_InitLog function.

Format

bool AIT_LogMessage  (
  string strMessage     // Message character string
);

Parameters

strMessage (input)

Specify a character string message you want to write into a log file.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

3

ERROR_PATH_NOT_FOUND

4

ERROR_TOO_MANY_OPEN_FILES

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

19

ERROR_WRITE_PROTECT

32

ERROR_SHARING_VIOLATION

33

ERROR_LOCK_VIOLATION

53

ERROR_BAD_NETPATH

82

ERROR_CANNOT_MAKE

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

161

ERROR_BAD_PATHNAME

183

ERROR_ALREADY_EXISTS

206

ERROR_FILENAME_EXCED_RANGE

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

1231

ERROR_NETWORK_UNREACHABLE

1392

ERROR_FILE_CORRUPT

Note

This function records the current date and time as well as messages.

AIT_MenuItemClick

Description

Clicks a specified menu item.

Format

bool AIT_MenuItemClick  (
  integer nWndHandle,    // Window handle
  integer nMenu,         // Menu handle
  integer nIndex         // Index for a menu item
  [,float fTimeOut]      // Time-out
);

Parameters

nWndHandle (input)

Specify a window handle.

nMenu (input)

Specify a menu handle.

nIndex (input)

Specify the index of a menu item. The default index value is 0.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1401

ERROR_INVALID_MENU_HANDLE

1460

ERROR_TIMEOUT

AIT_MessageBox

Description

Displays a specified message in a dialog box, waits for the user to click a button, and returns the value indicating a button selected by the user.

Format

integer AIT_MessageBox  (
  string strMessage,       // Message
  string strTitle          // Title
  [,integer nIconType]     // Icon type
  [,integer nMsgBoxType]   // Message box type
);

Parameters

strMessage (input)

Specify a message to be displayed in a message box.

strTitle (input)

Specify the title of a message box.

nIconType (input, optional)

Specify the type of icon to be displayed. This type must be one of the following values:

Value

Description

MB_ICONEXCLAMATION

Displays an exclamation mark (!) icon in the message box.

MB_ICONINFORMATION

Displays an icon having circled i.

MB_ICONQUESTION

Displays a question mark (?) icon in the message box.

MB_ICONSTOP

Displays a stop mark icon in the message box.

The default is the MB_ICONEXCLAMATION icon type.

nMsgBoxType (input, optional)

Specify a message box type, which must be one of the following values.

Value

Description

MB_ABORTRETRYIGNORE

Displays a message box that has the Stop, Retry, and Ignore buttons.

MB_OK

Displays a message box that has only the OK button.

MB_OKCANCEL

Displays a message box that has the OK and Cancel buttons.

MB_RETRYCANCEL

Displays a message box that has the Retry and Cancel buttons.

MB_YESNO

Displays a message box that has the Yes and No buttons.

MB_YESNOCANCEL

Displays a message box that has the Yes, No, and Cancel buttons.

The default is the MB_OK message box type.

Return values

This API function returns the value indicating a button the user has selected, which is one of the values below.

Value

Description

IDABORT

You have chosen the Stop button.

IDCANCEL

You have chosen the Cancel button.

IDIGNORE

You have chosen the Ignore button.

IDNO

You have chosen the No button.

IDOK

You have chosen the OK button.

IDRETRY

You have chosen the Retry button.

IDYES

You have chosen the Yes button.

If a value other than the above has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_MinWnd

Description

Minimizes a specified window to activate the next highest-order window.

Format

bool AIT_MinWnd  (
  integer nWndHandle     // Window handle
);
bool AIT_MinWnd  (
  string strCaption,     // Control's caption
  string strClassName    // Class name
);

Parameters

nWndHandle (input)

Specify a window handle.

strCaption (input)

Specify the caption of a control.

strClassName (input)

Specify a window's class name.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_MouseClick

Description

Clicks the mouse at specified coordinates.

Format

bool AIT_MouseClick  (
  integer nMouseButton,     // Mouse button
  integer nX,               // X coordinate
  integer nY                // Y coordinate
);

Parameters

nMouseButton (input)

Specify a mouse button you want to click. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTOM

Center mouse button

RBUTTON

Right mouse button

nX (input)

Specify the X coordinate of a position to be clicked.

nY (input)

Specify the Y coordinate of a position to be clicked.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_MouseDblClk

Description

Double-clicks the mouse at specified coordinates.

Format

bool AIT_MouseDblClk  (
  integer nX,             // X coordinate
  integer nY,             // Y coordinate
  integer nButton,        // Mouse button
  integer nKeyState       // Key status
);

Parameters

nX (input)

Specify the X coordinate of a position to be double-clicked.

nY (input)

Specify the Y coordinate of a position to be double-clicked.

nButton (input)

Specify a mouse button to be double-clicked. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

nKeyState (input)

Specify key status, which must be one of the following values.

Value

Description

SHIFT_ON

The Shift key is on.

ALT_ON

The Alt key is on.

CTRL_ON

The Ctrl key is on.

SHIFT_OFF

The Shift key is off.

ALT_OFF

The Alt key is off.

CTRL_OFF

The Ctrl key is off.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_MouseDown

Description

Presses a mouse button at specified coordinates.

Format

bool AIT_MouseDown  (
  integer nX,              // X coordinate
  integer nY,              // Y coordinate
  integer nButton,         // Mouse button
  integer nKeyState        // Key status
);

Parameters

nX (input)

Specify the X coordinate of a position at which to press a mouse button.

nY (input)

Specify the Y coordinate of a position at which to press a mouse button.

nButton (input)

Specify a button to be pressed by the mouse. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

nKeyState (input)

Specify key status, which must be one of the following values.

Value

Description

SHIFT_ON

The Shift key is on.

ALT_ON

The Alt key is on.

CTRL_ON

The Ctrl key is on.

SHIFT_OFF

The Shift key is off.

ALT_OFF

The Alt key is off.

CTRL_OFF

The Ctrl key is off.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_MouseDragDrop

Description

Drags and drops the section from a specified start position to a specified end position.

Format

bool AIT_MouseDragDrop  (
  integer nXStartPos,       // Start X coordinate
  integer nYStartPos,       // Start Y coordinate
  integer nXEndPos,         // End X coordinate
  integer nYEndPos,         // End Y coordinate
  integer nButton,          // Mouse button
  integer nKeyState         // Key status
);

Parameters

nXStartPos (input)

Specify the X coordinate of a position at which to start dragging.

nYStartPos (input)

Specify the Y coordinate of a position at which to start dragging.

nXEndPos (input)

Specify the X coordinate of a position at which to drop the section.

nYEndPos (input)

Specify the Y coordinate of a position at which to drop the section.

nButton (input)

Specify a mouse button to be used for dragging and dropping. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

nKeyState (input)

Specify key status, which must be one of the following values.

Value

Description

SHIFT_ON

The Shift key is on.

ALT_ON

The Alt key is on.

CTRL_ON

The Ctrl key is on.

SHIFT_OFF

The Shift key is off.

ALT_OFF

The Alt key is off.

CTRL_OFF

The Ctrl key is off.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_MouseMoveTo

Description

Moves the mouse to specified coordinates.

Format

bool AIT_MouseMoveTo  (
  integer nX,             // X coordinate
  integer nY,             // Y coordinate
  integer nButton,        // Mouse button
  integer nKeyState       // Key status
);

Parameters

nX (input)

Specify the X coordinate of a position to which to move the mouse.

nY (input)

Specify the Y coordinate of a position to which to move the mouse.

nButton (input)

Specify a mouse button to be clicked during movement. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

nKeyState (input)

Specify key status, which must be one of the following values.

Value

Description

SHIFT_ON

The Shift key is on.

ALT_ON

The Alt key is on.

CTRL_ON

The Ctrl key is on.

SHIFT_OFF

The Shift key is off.

ALT_OFF

The Alt key is off.

CTRL_OFF

The Ctrl key is off.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_MouseUp

Description

Releases the mouse button at specified coordinates.

Format

bool AIT_MouseUp  (
  integer nX,          // X coordinate
  integer nY,          // Y coordinate
  integer nButton,     // Mouse button
  integer nKeyState    // Key status
);

Parameters

nX (input)

Specify the X coordinate of a position at which to release the mouse button.

nY (input)

Specify the Y coordinate of a position at which to release the mouse button.

nButton (input)

Specify a mouse button to be released. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

nKeyState (input)

Specify key status, which must be one of the following values.

Value

Description

SHIFT_ON

The Shift key is on.

ALT_ON

The Alt key is on.

CTRL_ON

The Ctrl key is on.

SHIFT_OFF

The Shift key is off.

ALT_OFF

The Alt key is off.

CTRL_OFF

The Ctrl key is off.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_PlayKey

Description

Sends keyboard input information to the active window as if the user had typed that information.

Format

bool AIT_PlayKey  (
  string strKeys     // Character string
);

Parameters

strKeys (input)

Specify a key or a combination of key character strings, or a character string. You can specify a combination of the following characters.

All the uppercase and lowercase alphabetic characters from a to z

All the numeric characters from 0 to 9

Following special characters:

~ ! @ # $ % ^ & * ( ) _ + | ? > < " } { [ ] ' ; / . , ` - = \

Example:

AIT_PlayKey("ABC") simulates processing for typing a character string of ABC.

The following gives the special keys you can specify:

Special keys that can be specified

{ALT}

{ALT_LOCK}

{ALT_UNLOCK}

{ALT+SHIFT}

{APPS}

{BACKSPACE}

{CTRL}

{CTRL+ALT}

{CTRL+SHIFT}

{CTRL+ALT+SHIFT}

{CTRL_LOCK}

{CAPSLOCK}

{CAPSLOCK_ON}

{CAPSLOCK_OFF}

{CTRL_UNLOCK}

{DELETE}

{DOWN}

{END}

{ENTER}

{ESC}

{F1}

{F2}

{F3}

{F4}

{F5}

{F6}

{F7}

{F8}

{F9}

{F10}

{F11}

{F12}

{HOME}

{INS}

{KANA_ON}

{KANA_OFF}

{KANJI_ON}

{KANJI_OFF}

{LEFT}

{LWIN}

{LWIN_LOCK}

{LWIN_UNLOCK}

{NUMLOCK_ON}

{NUMLOCK_OFF}

{NUMLOCK}

{NUMPAD0}

{NUMPAD1}

{NUMPAD2}

{NUMPAD3}

{NUMPAD4}

{NUMPAD5}

{NUMPAD6}

{NUMPAD7}

{NUMPAD8}

{NUMPAD9}

{PAUSE}

{PGDOWN}

{PGUP}

{PRNSCR}

{PROCESS}

{RIGHT}

{RWIN}

{RWIN_LOCK}

{RWIN_UNLOCK}

{SCROLLLOCK}

{SCROLLLOCK_ON}

{SCROLLLOCK_OFF}

{SHIFT}

{SHIFT_LOCK}

{SHIFT_UNLOCK}

{SPACE}

{TAB}

{UP}

-

-

-

-

Legend:

-: No value.

Example:

AIT_PlayKey("{TAB}") simulates processing for pressing the Tab key.

When specifying a key in combination with the Shift, Ctrl, or Alt key, add the following key operation codes before a regular key text.

Key

Key operation code

Shift

+

Ctrl

^

Alt

%

Example:

AIT_PlayKey("%(N)") indicates that Alt+N key is pressed.

To repeat keys in the same order, type:

{REPEAT n}character-to-repeat{END_REPEAT}

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error number

Error code

87

ERROR_INVALID_PARAMETER

AIT_PostMessage

Description

Posts a message to a message queue associated with the thread used to create a specified window. This API function returns the control without waiting for that thread to process the message.

Format

bool AIT_PostMessage  (
  integer nWndHandle,     // Window handle
  integer nMessage,       // Message
  integer nWParam,        // First parameter for a message
  integer nLParam         // Second parameter for a message
);

Parameters

nWndHandle (input)

Specify a window handle to which to post a message.

The following value has a special meaning.

Value

Description

HWND_BROADCAST

Posts a message to all the top-level windows in the system, including an invalid window not owned, an invisible window not owned, an overlapped window (hidden by another front window), and a pop-up window. Does not post a message to any child windows.

nMessage (input)

Specify a message you want to post.

nWParam (input)

Specify additional information particular to a message.

nLParam (input)

Specify additional information particular to a message.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

AIT_RegCloseKey

Description

Closes a handle to a specified registry key.

Format

bool AIT_RegCloseKey(
  integer nHKeyHandle     // Key handle
);

Parameters

nHKeyHandle (input)

Specify an already opened registry key.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

AIT_RegCreateKey

Description

Creates a specified registry key. Opens a specified registry key if it already exists.

Format

bool AIT_RegCreateKey(
  integer nHKeyHandle,       // Key handle
  string strRegKeyName,      // Name of a key to be created
  integer nOutputHkeyHandle  // Output key handle
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify the name of a registry key to be created or opened.

nOutputHkeyHandle (output)

Specify a variable to receive a handle to a registry key. When the function returns, the variable stores the handle.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

Note

Before termination, call AIT_RegCloseKey to close nOutputHkeyHandle.

To create a registry key, you must have permission to write at the location where you want to create the registry key.

If you attempt to open an existing registry key on which you do not have write permission, the registry key opens in the read-only mode.

AIT_RegDeleteKey

Description

Deletes a sub-key for a specified registry.

Format

bool AIT_RegDeleteKey(
  integer nHKeyHandle,     // Key handle
  string strRegKeyName     // Name of a key to be deleted
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key.

strRegKeyName (input)

Specify a sub-key name for a registry to be deleted.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

5

ERROR_ACCESS_DENIED

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

Note

When the OS of the computer is Windows, if the specified key has a sub-key, you cannot delete the specified key. Before deleting a key, delete all of its sub-keys.

AIT_RegDeleteValue

Description

Deletes a specified registry value.

Format

bool AIT_RegDeleteValue(
  integer nHKeyHandle,     // Key handle
  string strRegValueName   // Registry value name
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key.

strRegValueName (input)

Specify a registry key name you want to delete.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

AIT_RegGetDWORDValue

Description

Acquires a registry value of the DWORD-type.

Format

bool AIT_RegGetDWORDValue(
  integer nHKeyHandle,      // Key handle
  string strRegKeyName,     // Registry sub-key name
  string strRegValueName,   // Registry value name
  integer nRegValueData     // Registry value data
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify a sub-key name for a registry.

strRegValueName (input)

Specify a registry value name you want to acquire.

nRegValueData (output)

Specify a variable to receive registry value data of the DWORD-type. When the function returns, the variable stores the registry value data.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

234

ERROR_MORE_DATA

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1012

ERROR_CANTREAD

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1018

ERROR_KEY_DELETED

1019

ERROR_NO_LOG_SPACE

1069

ERROR_NO_MATCH

AIT_RegGetStringValue

Description

Acquires a registry value of the character string data type (REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ).

Format

bool AIT_RegGetStringValue(
  integer nHKeyHandle,      // Key handle
  string strRegKeyName,     // Registry sub-key name
  string strRegValueName,   // Registry value name
  string strRegValueData    // Registry value data
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify a registry sub-key name.

strRegValueName (input)

Specify a registry value name you want to acquire.

strRegValueData (output)

Specify a variable to receive registry value data of the character string data type. When the function returns, the variable stores the registry data value.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

234

ERROR_MORE_DATA

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1012

ERROR_CANTREAD

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1018

ERROR_KEY_DELETED

1019

ERROR_NO_LOG_SPACE

1169

ERROR_NO_MATCH

AIT_RegisterWindowMessage

Description

Defines a new window message particular to the system. You can use this message value to post or send a message.

Typically, this function is used to register a message to be applied to communication between two cooperating applications.

Format

integer AIT_RegisterWindowMessage  (
  string strMessageString     // Message character string
);

Parameters

strMessageString (input)

Specify a message you want to register.

Return values

The return value is a message value (message ID) ranging from 49152 to 65535 if the message has been registered normally.

The return value is 0 if the function has not been processed successfully. You can use AIT_GetLastError to acquire an extended error code.

The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

AIT_RegKeyExists

Description

Checks whether the specified registry key exists.

Format

integer AIT_RegKeyExists(
  integer nHKeyHandle,       // Key handle
  string strRegKeyName       // Registry sub-key name
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key.

strRegKeyName (input)

Specify the name of a registry sub-key to check if it exists.

Return values

The return value is 1 if the key exists, 0 if not, and -1 if the function has not been processed successfully.

If the function has returned -1, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

AIT_RegOpenKey

Description

Opens a specified registry key.

Format

bool AIT_RegOpenKey(
  integer nHKeyHandle,       // Key handle
  string strRegKeyName,      // Name of a key to be opened
  integer nOutputHkeyHandle  // Output key handle
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify a sub-key name for a registry to be opened.

nOutputHkeyHandle (output)

Specify a variable to receive a handle to a registry key. When the function returns, the variable stores the handle.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1018

ERROR_KEY_DELETED

1019

ERROR_NO_LOG_SPACE

Note

Before termination, call AIT_RegCloseKey to close nOutputHkeyHandle.

If you attempt to open a registry key for which you do not have write permission, the registry key opens in the read-only mode.

AIT_RegSetDWORDValue

Description

Sets data to a registry value of the DWORD-type.

Format

bool AIT_RegSetDWORDValue(
  integer nHKeyHandle,      // Key handle
  string strRegKeyName,     // Registry sub-key name
  string strRegValueName,   // Registry value name
  integer nRegValueData     // Registry value data
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify a sub-key name for a registry.

strRegValueName (input)

Specify the name of a registry value you want to set.

nRegValueData (input)

Specify data you want to set to a registry value of the DWORD-type.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

234

ERROR_MORE_DATA

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1013

ERROR_CANTWRITE

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1018

ERROR_KEY_DELETED

1019

ERROR_NO_LOG_SPACE

1169

ERROR_NO_MATCH

AIT_RegSetStringValue

Description

Sets data to a registry value of the character string data type (REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ).

Format

bool AIT_RegSetStringValue(
  integer nHKeyHandle,      // Key handle
  string strRegKeyName,     // Registry sub-key name
  string strRegValueName,   // Registry value name
  string strRegValueData    // Registry value data
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key, or one of the following values.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

strRegKeyName (input)

Specify a registry sub-key name.

strRegValueName (input)

Specify a registry value name you want to set.

strRegValueData (input)

Specify data you want to set to a registry value of the character string data type.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

234

ERROR_MORE_DATA

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1013

ERROR_CANTWRITE

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1018

ERROR_KEY_DELETED

1019

ERROR_NO_LOG_SPACE

1169

ERROR_NO_MATCH

Notes

When you set character string data to a new registry value, the data type is REG_SZ. You cannot change the data type.

When you use this API function to update an existing registry value, you cannot change the data type.

AIT_RegValueExists

Description

Checks whether the specified registry value exists.

Format

integer AIT_RegValueExists(
  integer nHKeyHandle,     // Key handle
  string strRegValueName   // Registry value name
);

Parameters

nHKeyHandle (input)

Specify a handle to an already opened registry key.

strRegValueName (input)

Specify the name of a registry value to check if it exists.

Return values

The return value is 1 if this value exists, 0 if not, and -1 if the function has not been processed successfully.

If the function has returned -1, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

6

ERROR_INVALID_HANDLE

87

ERROR_INVALID_PARAMETER

236

ERROR_MORE_DATA

1009

ERROR_BADDB

1010

ERROR_BADKEY

1011

ERROR_CANTOPEN

1015

ERROR_REGISTRY_CORRUPT

1016

ERROR_REGISTRY_IO_FAILED

1019

ERROR_NO_LOG_SPACE

AIT_SelectIPAddressField

Description

Selects a text in the IP address control on the active window.

Format

bool AIT_SelectIPAddressField  (
  string strCaption,       // Control's caption
  integer nFieldIndex,     // Field index
  integer nStartSel,       // Text start position
  integer nEndSel          // Text count
  [,float fTimeOut]        // Time-out
);
bool AIT_SelectIPAddressField  (
  integer nCtrlID,         // Control ID
  integer nFieldIndex,     // Field index
  integer nStartSel,       // Text start position
  integer nEndSel          // Text count
  [,float fTimeOut]        // Time-out
);

Parameters

strCaption (input)

Specify the control's caption.

nCtrlID (input)

Specify the control ID.

nFieldIndex (input)

Specify the index of a field in the IP address control. The default index value is 0.

nStartSel (input)

Specify the start character position at which to select text. The default nStartSel value is 0, corresponding to the first text character.

nEndSel (input)

Specify the number of texts you want to select.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

The start value may be greater than the end value. The smaller of the two values refers to the first character position of selected text. The greater value refers to the first character position beyond selected text.

The start value is a fixed selected text point, while the end value is a varying end point.

If the start point is 0 and the end point is -1, all the texts in the edit control are selected. If the start point is -1, active selection is released.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SelectListItem

Description

Selects an item specified in a specific control on the active window.

Format

bool AIT_SelectListItem  (
  string strCaption,    // Control's caption
  integer nCtrlType,    // Control type
  string strItemText    // Item text selected
  [,float fTimeOut]     // Time-out
);
bool AIT_SelectListItem  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  string strItemText    // Item text selected
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

LIST_CTRL

The control type is a list control.

strItemText (input)

Specify text you want to select on a specific control.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

Do not use the AIT_SelectListItem function for controls that allow selection of multiple values.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SelectMultipleListItem

Description

Selects the specified items in a specific multi-selection control on the active window.

Format

bool AIT_SelectMultipleListItem  (
  string strCaption,    // Control's caption
  integer nCtrlType,    // Control type
  string strItemText    // Item text selected
  [,float fTimeOut]     // Time-out
);
bool AIT_SelectMultipleListItem  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  string strItemText    // Item text selected
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

LISTBOX_CTRL

The control type is a list box.

LIST_CTRL

The control is a list control.

strItemText (input)

Specify the text items you want to select in the multi-selection control. You can specify multiple values delimited by a comma.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

Use the AIT_SelectMultipleListItem function only for controls that allow selection of multiple values.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SelectText

Description

Selects text in the edit control on the active window.

Format

bool AIT_SelectText  (
  string strCaption,   // Control's caption
  integer nStartPos,   // Control start position
  integer nEndPos      // Control end position
  [,float fTimeOut]    // Time-out
);
bool AIT_SelectText  (
  integer nCtrlID,     // Control ID
  integer nStartPos,   // Control start position
  integer nEndPos      // Control end position
  [,float fTimeOut]    // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nStartPos (input)

Specify a start character position at which to select text. The default nStartPos value is 0, corresponding to the first text character.

nEndPos (input)

Specify the end character position at which to select text.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

The start value may be greater than the end value. The smaller of the two values refers to the first character position of selected text. The greater value refers to the first character position beyond selected text.

The start value is a fixed selected text point, while the end value is a varying end point.

If the start point is 0 and the end point is -1, all the texts in the edit control are selected. If the start point is -1, active selection is released.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetActWnd

Description

Activates a specified window.

Format

bool AIT_SetActWnd  (
  integer nWndHandle     // Window handle
);

Parameters

nWndHandle (input)

Specify a window's handle.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_SetCheck

Description

Turns on and off, and deactivates a specific control on the active window.

Format

bool AIT_SetCheck  (
  string strCaption,     // Control's caption
  integer nCtrlType      // Control type
  [,integer nCondition]  // Check type
  [,float fTimeOut]      // Time-out
);
bool AIT_SetCheck  (
  integer nCtrlID,       // Control ID
  integer nCtrlType      // Control type
  [,integer nCondition]  // Check status type
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

nCondition (input, optional)

Specify a check status type, which must be one of the following values.

Value

Description

0

Turned off

1

Turned on

2

Deactivated or grayed

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetComboEditSelText

Description

Sets text selection in a combo box on the active window.

Format

bool AIT_SetComboEditSelText  (
  string strCaption,    // Control's caption
  integer nStartSel,    // Control start position
  integer nEndSel       // Control end position
  [,float fTimeOut]     // Time-out
);
bool AIT_SetComboEditSelText  (
  integer nCtrlID,      // Control's caption
  integer nStartSel,    // Control start position
  integer nEndSel       // Control end position
  [,float fTimeOut]     // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nStartSel (input)

Specify the start position of text selection in an edit control. The default nStartSel value is 0.

nEndSel (input)

Specify the end position of text selection in an edit control.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Notes

The start value may be greater than the end value. The smaller of the two values refers to the first character position of selected text. The greater value refers to the first character position beyond selected text.

The start value is a fixed selected text point, while the end value is a varying end point. The user can use the Shift key to adjust the size of a selected text. If the start point is 0 and the end point is -1, all the texts in the edit control are selected. If the start point is -1, active selection is released.

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetCurrentDirectory

Description

Changes a selected directory to the current directory.

Format

bool AIT_SetCurrentDirectory  (
  string strDirName    // Directory name
);

Parameters

strDirName (input)

Specify a directory name.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

21

ERROR_NOT_READY

53

ERROR_BAD_NETPATH

123

ERROR_INVALID_NAME

161

ERROR_BAD_PATHNAME

1005

ERROR_UNRECOGNIZED_VOLUME

1210

ERROR_INVALID_COMPUTERNAME

1214

ERROR_INVALID_NETNAME

AIT_SetDefaultWaitTimeout

Description

Sets the default time-out to be used in an API function associated with a control.

Format

AIT_SetDefaultWaitTimeout  (
  float fTimeOut      // Time-out value (seconds)
);

Parameters

fTimeOut (input)

Specify the default time-out in units of seconds. If you have omitted this function, the time-out is five seconds.

Return values

None

AIT_SetDtPickerDate

Description

Sets a date to the date/time picker.

Format

bool AIT_SetDtPickerDate  (
  string strCaption,     // Control's caption
  integer nYear,         // Year
  integer nMonth,        // Month
  integer nDay           // Day
  [,float fTimeOut]      // Time-out
);
bool AIT_SetDtPickerDate  (
  string strCaption,     // Control's caption
  string strInputDate    // Date
  [,float fTimeOut]      // Time-out
);
bool AIT_SetDtPickerDate  (
  integer nCtrlID,       // Control ID
  integer nYear,         // Year
  integer nMonth,        // Month
  integer nDay           // Day
  [,float fTimeOut]      // Time-out
);
bool AIT_SetDtPickerDate  (
  integer nCtrlID,        // Control ID
  string  strInputDate    // Date
  [,float fTimeOut]       // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nYear (input)

Specify a year to be set to a control.

nMonth (input)

Specify a month to be set to a control.

nDay (input)

Specify a day to be set to a control.

strInputDate

Specify a date to be set to in control in the MM/DD/YYYY format, where MM indicates the month, DD indicates the day, and YYYY indicates the year.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetDtPickerTime

Description

Sets time to the date/time picker.

Format

bool AIT_SetDtPickerTime  (
  string strCaption,     // Control's caption
  integer nHour,         // Hours
  integer nMinute,       // Minutes
  integer nSecond        // Seconds
  [,float fTimeOut]      // Time-out
);
bool AIT_SetDtPickerTime  (
  string strCaption,     // Control's caption
  string strInputTime    // Time
  [,float fTimeOut]      // Time-out
);
bool AIT_SetDtPickerTime  (
  integer nCtrlID,       // Control ID
  integer nHour,         // Hours
  integer nMinute,       // Minutes
  integer nSecond        // Seconds
  integer [nTimeOut]     // Time-out
);
bool AIT_SetDtPickerTime  (
  integer nCtrlID,       // Control ID
  string strInputTime    // Time
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nHour (input)

Specify hours to be set to a control.

nMinute (input)

Specify minutes to be set to a control.

nSecond (input)

Specify seconds to be set to a control.

strInputTime (input)

Specify time to be set to a control in the hh:mm:ss format, where hh indicates the hour, mm indicates the minute, and ss indicates the second.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetKeyState

Description

Sets specified key status.

Format

bool AIT_SetKeyState  (
  integer nVirtualKey,     // Virtual key
  integer nKeyState        // Key status
);

Parameters

nVirtualKey (input)

Specify a virtual key you want to set. You have to set one of the following values.

Value

Description

NUMLOCK

Num Lock key

SCROLLLOCK

Scroll Lock key

CAPSLOCK

Caps Lock key

nKeyState (input)

Specify key status you want to set. You have to set one of the following values.

Value

Description

KEYSTATE_OFF

The key is off.

KEYSTATE_ON

The key is on.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

AIT_SetProfileString

Description

Creates or changes a key value in an INI file section.

Format

bool AIT_SetProfileString  (
  string strIniFileName,     // INI filename
  string strSectionName,     // Section name
  string strKeyName,         // Key name
  string strValue            // Value
);

Parameters

strIniFileName (input)

Specify an INI filename.

strSectionName (input)

Specify an INI file section name.

strKeyName (input)

Specify a key name belonging to a section name.

strValue (input)

Specify a key value you want to set.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

2

ERROR_FILE_NOT_FOUND

3

ERROR_PATH_NOT_FOUND

5

ERROR_ACCESS_DENIED

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

15

ERROR_INVALID_DRIVE

21

ERROR_NOT_READY

23

ERROR_CRC

53

ERROR_BAD_NETPATH

67

ERROR_BAD_NET_NAME

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

123

ERROR_INVALID_NAME

148

ERROR_PATH_BUSY

1005

ERROR_UNRECOGNIZED_VOLUME

AIT_SetScrollPos

Description

Moves the scroll bar.

Format

bool AIT_SetScrollPos (
  integer nCtrlID,         // Control ID
  integer nPosition        // Position
  [,float fTimeOut]        // Time-out
);
bool AIT_SetScrollPos (
  string strCaption,       // Control's caption
  integer nCtrlType,       // Control type
  integer nScrollType,     // Scroll type
  integer nPosition,       // Set position
  integer nScrollMovement  // Movement type
  [,float fTimeOut]        // Time-out
);
bool AIT_SetScrollPos (
  integer nCtrlID,         // Control ID
  integer nCtrlType,       // Control type
  integer nScrollType,     // Scroll type
  integer nPosition,       // Set position
  integer nScrollMovement  // Movement type
  [,float fTimeOut]        // Time-out
);

Parameters

nCtrlID (input)

Specify a control ID.

nPosition (input)

Specify a position to be set.

strCaption (input)

Specify the caption of a control.

nCtrlType (input)

Specify a control type for the scroll bar, which must be one of the following values.

Value

Description

EDIT_CTRL

The control type is an edit control.

LISTBOX_CTRL

The control type is a list box.

LIST_CTRL

The control type is a list control.

TREE_CTRL

The control type is a tree control.

nScrollType (input)

Specify a scroll bar type, which must be one of the following values.

Value

Description

VSCROLL

Vertical scroll bar

HSCROLL

Horizontal scroll bar

nScrollMovement (input)

Specify the type of scroll bar control movement. If nScrollType is VSCROLL, you have to set one of the following values.

Value

Description

SB_BOTTOM

Moves the scroll bar to the bottom right.

SB_LINEDOWN

Moves the scroll bar to the next line.

SB_LINEUP

Moves the scroll bar to the above line.

SB_PAGEDOWN

Moves the scroll bar to the next page.

SB_PAGEUP

Moves the scroll bar to the previous page.

SB_THUMBPOSITION

The user has dragged the scroll box (thumb), and released the mouse button.

SB_THUMBTRACK

The user is dragging the scroll box.

SB_TOP

Moves the scroll bar to the top left.

If nScrollType is HSCROLL, you have to set one of the following values.

Value

Description

SB_LEFT

Moves the scroll bar to the top left.

SB_RIGHT

Moves the scroll bar to the bottom right.

SB_LINELEFT

Moves the scroll bar to the left by one unit.

SB_LINERIGHT

Moves the scroll bar to the right by one unit.

SB_PAGELEFT

Moves the scroll bar to the left by the window width.

SB_PAGERIGHT

Moves the scroll bar to the right by the window width.

SB_THUMBPOSITION

The user has dragged the scroll box (thumb), and released the mouse button.

SB_THUMBTRACK

The user is dragging the scroll box.

nTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetSpinPos

Description

Sets a position in a specific control on the active window.

Format

bool AIT_SetSpinPos (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nPosition      // Set position
  [,float fTimeOut]      // Time-out
);
bool AIT_SetSpinPos (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nPosition      // Set position
  [,float fTimeOut]      // Time-out
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

SPIN_CTRL

The control type is a spin control.

SLIDER_CTRL

The control type is a slider control.

nPosition (input)

Specify a position you want to set.

fTimeOut (input, optional)

Specify the maximum time this function can use to find the control, in units of seconds. The default is the value set in the AIT_SetDefaultWaitTimeout function.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_SetWndPos

Description

Changes a specified window position.

Format

bool AIT_SetWndPos  (
  integer nWndHandle,     // Window handle
  integer nLeft,          // Horizontal position
  integer nTop            // Vertical position
);

Parameters

nWndHandle (input)

Specify a window handle. If you set 0, the active window position will be set.

nLeft (input)

Specify the X coordinate of the top left corner of a new window (horizontal position).

nTop (input)

Specify the Y coordinate of the top left corner of a new window (vertical position).

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_SetWndPosSize

Description

Changes the position and size of a specified window.

Format

bool AIT_SetWndPosSize  (
  integer nHandle,      // Window handle
  integer nLeft,        // Horizontal position
  integer nTop,         // Vertical position
  integer nWidth,       // Window width
  integer nHeight       // Window height
);

Parameters

nHandle (input)

Specify a window handle. If you specify 0, the active window position will be set.

nLeft (input)

Specify the X coordinate of the top left corner of a new window (horizontal position).

nTop (input)

Specify the Y coordinate of the top left corner of a new window (vertical position).

nWidth (input)

Specify the width of a new window.

nHeight (input)

Specify the height of a new window.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_Sleep

Description

Interrupts execution of the AIT file for a certain period.

Format

AIT_Sleep  (
  float fSeconds        // Seconds
);

Parameters

fSeconds (input)

Specify the period of interruption in units of seconds.

Return values

None

AIT_StatusBox

Description

Displays the dialog box containing an entered message.

Format

bool AIT_StatusBox(
  string    strMessage,        // Message character string
  [[[[,integer nXCord]         // X coordinate
  [,integer    nYCord]         // Y coordinate
  [,integer    nWidth]         // Message box width
  [,integer    nHeight]]       // Message box height
  [,bool       bIsTop]         // Most front message box
  [,bool       bIsMovable]]    // Movable message box
  [,string     strFontName]]   // Message font name
  [,integer    nFontSize]      // Message font size
  [,integer    nFontWeight]    // Message font width
);

Parameters

strMessage (input)

Specify a message character string you want to display in the dialog box.

nXCord (input, optional)

Specify the X coordinate of the top left corner of the dialog box. If you specify -1, the dialog box is displayed at the center of the X axis.

nYCord (input, optional)

Specify the Y coordinate of the top left corner of the dialog box. If you specify -1, the dialog box is displayed at the center of the Y axis.

If you omit nXCord and nYCord, the dialog box will be positioned at the center.

nWidth (input, optional)

Specify the width of the dialog box.

nHeight (input, optional)

Specify the height of the dialog box.

If you have omitted nWidth and nHeight, the dialog box size becomes equal to the strMessage size.

bIsTop (input, optional)

If you set true, the dialog box will always be positioned on the most front. If you set false, it will be displayed on the front at first. If you move or create another window, however, the dialog box will be moved behind it. For arbitrary operation, set false.

Note that an operation on another window may move the focus from the dialog box even when true is set. If the dialog box is displayed beneath another window, you can re-execute this API function to display the dialog box on the front again.

When specifying this parameter, you must also specify nXCord, nYCord, nWidth, and nHeight.

bIsMovable (input, optional)

With true set, you can move the dialog box. With false set, you cannot move the dialog box.

When specifying this parameter, you must also specify nXCord, nYCord, nWidth, and nHeight.

strFontName (input, optional)

Specify a character string describing a message display font. The usable fonts may vary with systems.

For arbitrary operation, specify "". In this case, the default font is determined by the system.

When specifying this parameter, you must also specify nXCord, nYCord, nWidth, nHeight, bIsTop, and bIsMovable.

nFontSize (input, optional)

Specify the message font size using an integer in units of points.

For arbitrary operation, set 0. In this case, the default font size is determined by the system.

nFontWeight (input, optional)

Specify the message font size by using an integer. The range of valid values is from 0 to 900. As the value increases, the font becomes thicker.

For arbitrary operation, set 0. In this case, the default font thickness is determined by the system.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error code that AIT_GetLastError might return:

Extended error code

Error code

87

ERROR_INVALID_PARAMETER

Note

The parameter you can omit according to the above description is not independent. You have to set the default of the preceding omissible parameter. For example, when specifying only nXCord and nYCord, you can omit the subsequent omissible parameters. When specifying only nFontSize and nFontWeight, however, you cannot omit the subsequent omissible parameters, and you have to set the preceding omissible parameters at defaults.

AIT_StatusBoxClose

Description

Closes a displayed status box.

Format

AIT_StatusBoxClose ();

Parameters

None

Return values

None

AIT_StrLeft

Description

Returns the specified number of characters from the left of the character string.

The number of characters you have specified using nNumChars are extracted from the start (left end) of strStrName. If the number of characters set in nNumChars exceeds the length of the character string, the entire character string is extracted.

Format

string AIT_StrLeft (
  string strStrName,    // Character string
  integer nNumChars     // Character count
);

Parameters

strStrName (input)

Specify a character string.

nNumChars (input)

Specify the number of characters to be extracted.

Return value

The return value is the extracted character string.

Note

For a multi-byte character set (MBCS), eight bits are assumed to be a single character. That is, the first and last bytes of a multi-byte character are counted as two characters.

AIT_StrLength

Description

Returns the length of a character string.

Format

integer AIT_StrLength (
  string strStrName    // Character string
);

Parameters

strStrName (input)

Specify a character string.

Return value

This API function returns the length of a character string.

AIT_StrLower

Description

Converts the characters in a character string to the lowercase.

Format

string AIT_StrLower (
  string strStrName    // Character string
);

Parameters

strStrName (input)

Specify a character string.

Return value

This API function returns the character string with its characters converted to lowercase.

AIT_StrLTrim

Description

Returns a character string where all blanks or specified characters are deleted from its start (left end).

Format

string AIT_StrLTrim (
  string strStrName        // Character string
  [,string strCharValue]   // Character value
);

Parameters

strStrName (input)

Specify a character string.

strCharValue (input, optional)

Specify characters you want to delete. By default, blanks (such as breaks, spaces, and tabs) are deleted from the start of a character string.

Return value

This API function returns a character string where all blanks or specified characters are deleted from its start.

AIT_StrRight

Description

Returns the specified number of characters from the right of the character string.

The number of characters you have specified using nNumChars are extracted from the start (left end) of strStrName. If the number of characters set in nNumChars exceeds the length of the character string, the entire character string is returned.

Format

string AIT_StrRight (
  string strStrName,    // Character string
  integer nNumChars     // Character count
);

Parameters

strStrName (input)

Specify a character string.

nNumChars (input)

Specify the number of characters to be extracted.

Return value

The return value is the extracted character string.

Note

For a multi-byte character set (MBCS), eight bits are assumed to be a single character. That is, the first and last bytes of a multi-byte character are counted as two characters.

AIT_StrRTrim

Description

Returns a character string where all blanks or specified characters are deleted from its right end.

Format

string AIT_StrRTrim (
  string strStrName        // Character string
  [,string strCharValue]   // Character value
);

Parameters

strStrName (input)

Specify a character string.

strCharValue (input, optional)

Specify a character you want to delete. By default, blanks (such as breaks, spaces, and tabs) are deleted from the end of a character string.

Return value

This API function returns a character string where all blanks or specified characters are deleted from its end.

AIT_StrTrim

Description

Returns a character string where all blanks or specified characters are deleted from its left and right ends.

Format

string AIT_StrTrim (
  string strStrName        // Character string
  [,string strCharValue]   // Character value
);

Parameters

strStrName (input)

Specify a character string.

strCharValue (input, optional)

Specify a character to be deleted. By default, blanks (such as breaks, spaces, and tabs) are deleted from the start and end.

Return value

This API function returns a character string where all specified characters are deleted from its start and end.

AIT_StrUpper

Description

Converts the characters in a character string to uppercase.

Format

string AIT_StrUpper (
  string strStrName    // Character string
);

Parameters

strStrName (input)

Specify a character string.

Return value

This API function returns a character string with its characters converted to uppercase.

AIT_TaskbarClk

Description

Clicks a free area on the taskbar.

Format

bool AIT_TaskbarClk  (
  [integer nMouseButton]     // Mouse button
);

Parameters

nMouseButton (input, optional)

Specify a button to be clicked by the mouse. You have to set one of the following values.

Value

Description

LBUTTON

Left mouse button

MBUTTON

Center mouse button

RBUTTON

Right mouse button

The default is RBUTTON.

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_TaskbarHasFocus

Description

Checks whether the taskbar has an input focus.

Format

integer AIT_TaskbarHasFocus ();

Parameters

None

Return values

The return value is 1 if the taskbar has a focus, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_TaskbarSetFocus

Description

Sets an input focus to the taskbar.

Format

bool AIT_TaskbarSetFocus ();

Parameters

None

Return values

The return value is true if the function was executed normally, and false if not. If the function has returned false, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

1400

ERROR_INVALID_WINDOW_HANDLE

AIT_VerifyCharPos

Description

Checks a character position in a specific control on the active window.

Format

integer AIT_VerifyCharPos  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nVerifyPos     // Character position
);
integer AIT_VerifyCharPos  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nVerifyPos     // Character position
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type for which only EDIT_CTRL is valid.

nVerifyPos (input)

Specify the positional value of a character to be checked. Because 0-based positioning is used, the position of the first character in the edit box is 0.

Return values

The return value is 1 if the found position is the same as a specified one, 0 if not, and -1 if the function has not been processed normally. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyCount

Description

Checks the number of items in a specific control on the active window.

Format

integer AIT_VerifyCount  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nItemCount     // Item count
);
integer AIT_VerifyCount  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nItemCount     // Item count
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

nItemCount (input)

Specify the number of items to be checked.

Return values

The return value is 1 if the specified item count is matched, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyDateTime

Description

Checks a date or time in a specific control on the active window.

Format

integer AIT_VerifyDateTime  (
  string strCaption,     // Control's caption
  string strDateTime     // Date or time
);
integer AIT_VerifyDateTime  (
  integer nCtrlID,       // Control ID
  string strDateTime     // Date or time
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

strDateTime (input)

Specify a control's date or time.

Return values

The return value is 1 if the specified date or time is matched, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyDefaultButton

Description

Checks whether a specific command button in the active window is the default button.

Format

integer AIT_VerifyDefaultButton  (
  string strCaption    // Control's caption
);
integer AIT_VerifyDefaultButton  (
  integer nCtrlID      // Control ID
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

Return values

The return value is 1 if the button is the default one, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyEnabled

Description

Checks whether a specific control in the active window is usable.

Format

integer AIT_VerifyEnabled  (
  string strCaption,     // Control's caption
  integer nCtrlType      // Control type
  [,integer nCtrlPos]    // Tab order
);
integer AIT_VerifyEnabled  (
  integer nCtrlID,       // Control ID
  integer nCtrlType      // Control type
  [,integer nCtrlPos]    // Tab order
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nCtrlPos (input, optional)

Specify a control's tab order.

Return values

The return value is 1 if the control is usable, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyExistence

Description

Checks whether the active window contains a specific control.

Format

integer AIT_VerifyExistence  (
  string strCaption,    // Control's caption
  integer nCtrlType     // Control type
);
integer AIT_VerifyExistence  (
  integer nCtrlID,      // Control ID
  integer nCtrlType     // Control type
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

IPADDRESS_CTRL

The control type is an IP address control.

SLIDER_CTRL

The control type is a slider control.

SCROLLBAR_CTRL

The control type is a scroll bar control.

Return values

The return value is 1 if the control exists, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyFirstVisible

Description

Checks the index of the first visible item in a list box.

Format

integer AIT_VerifyFirstVisible  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nIndex         // Index
);
integer AIT_VerifyFirstVisible  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nIndex         // Index
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type for which only LISTBOX_CTRL is valid.

nIndex (input)

Specify a control's index. As the index is based on 0, the index for the first item in a control is 0.

Return values

The return value is 1 if the specified index matches the index for the first visible item, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyFocus

Description

Checks whether the specific control in the active window has a focus.

Format

integer AIT_VerifyFocus  (
  string strCaption,     // Control's caption
  integer nCtrlType      // Control type
);
integer AIT_VerifyFocus  (
  integer nCtrlID,       // Control ID
  integer nCtrlType      // Control type
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

Return values

The return value is 1 if the control has a focus, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyIndex

Description

Checks whether the text matches the index in a specific control on the active window.

Format

integer AIT_VerifyIndex  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  string strCtrlText,    // Control text
  integer nIndex         // Index
);
integer AIT_VerifyIndex  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  string strCtrlText,    // Control text
  integer nIndex         // Index
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

strCtrlText (input)

Specify the text of a control.

nIndex (input)

Specify a control's index based on 0.

Return values

The return value is 1 if the specified control's index matches the text, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyKeyState

Description

Checks whether the key status is the same as that on the keyboard.

Format

integer AIT_VerifyKeyState  (
  integer nVirtualKey,     // Virtual key
  integer nKeyState        // Key status
);

Parameters

nVirtualKey (input)

Specify a virtual key having key status to be checked.

You have to set one of the following values.

Value

Description

NUMLOCK

Num Lock key

SCROLLLOCK

Scroll Lock key

CAPSLOCK

Caps Lock key

nKeyState (input)

Specify key status to be checked, which is on or off. You have to set one of the following values.

Value

Description

KEYSTATE_OFF

Specify this value to check whether the key is off.

KEYSTATE_ON

Specify this value to check whether the key is on.

Return values

The return value is 1 if the key status matches specified status, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

AIT_VerifyLine

Description

Verifies on the active window that the index matches the current line on an edit box containing multiple lines.

Format

integer AIT_VerifyLine  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nIndex         // Index
);
integer AIT_VerifyLine  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     // Control type
  integer nIndex         // Index
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type for which only EDIT_CTRL is valid.

nIndex (input)

Specify the index of the current line to be checked. As the index value is based on 0, the index for the first line in an edit box is 0.

Return values

The return value is 1 if the current line in an edit box matches a specified index, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyLocation

Description

Checks whether a specific control in the active window matches specified coordinates.

Format

integer AIT_VerifyLocation  (
  string  strCaption,   // Control's caption
  integer nCtrlType,    // Control type
  integer nLeft,        // Coordinates of the top left control corner
  integer nTop,         // Coordinates of the control top
  integer nRight,       // Coordinates the top right control corner
  integer nBottom       // Coordinates of the control bottom
);
integer AIT_VerifyLocation  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  integer nLeft,        // Coordinates of the top left control corner
  integer nTop,         // Coordinates of the control top
  integer nRight,       // Coordinates of the top right control corner
  integer nBottom       // Coordinates of the control bottom
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nLeft (input)

Specify the X coordinate of the top left control corner.

nTop (input)

Specify the Y coordinate of the top left control corner.

nRight (input)

Specify the X coordinate of the bottom right control corner.

nBottom (input)

Specify the Y coordinate of the bottom right control corner.

Return values

The return value is 1 if coordinates of a control match specified ones, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyMenuChecked

Description

Checks whether a menu item has been checked.

Format

integer AIT_VerifyMenuChecked  (
  integer nMenu,      // Menu handle
  integer nIndex      // Index for a menu item
);

Parameters

nMenu (input)

Specify a menu handle returned by the AIT_GetMenu or AIT_GetSubMenu API function.

nIndex (input)

Specify the index of a menu item. As the menu index is based on 0, the index for the first menu item is 0.

The indexes also include a menu separator index. If a menu separator index has been given as an input value, this function is not processed successfully, with ERROR_INVALID_INDEX returned as the extended error code.

Return values

The return value is 1 if the menu item has been checked, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error code

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1401

ERROR_INVALID_MENU_HANDLE

1413

ERROR_INVALID_INDEX

1460

ERROR_TIMEOUT

AIT_VerifyMenuEnabled

Description

Checks whether the menu item is enabled.

Format

integer AIT_VerifyMenuEnabled  (
  integer nMenu,      // Menu handle
  integer nIndex      // Index for a menu item
);

Parameters

nMenu (input)

Specify a menu handle returned by the AIT_GetMenu or AIT_GetSubMenu API function.

nIndex (input)

Specify the index of a menu item. As the menu index is based on 0, the index for the first menu item is 0.

The indexes also include a menu separator index. If a menu separator index has been given as an input value, this function is not processed successfully, with ERROR_INVALID_INDEX returned as the extended error code.

Return values

The return value is 1 if the menu item is enabled, 0 if not, and -1 if the function has not been processed successfully.

If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1401

ERROR_INVALID_MENU_HANDLE

1413

ERROR_INVALID_INDEX

1460

ERROR_TIMEOUT

AIT_VerifyNoOfCtrls

Description

Checks whether the number of controls in an active control matches a specified value.

Format

integer AIT_VerifyNoOfCtrls  (
  integer nNumControls      // Control count
);

Parameters

nNumControls (input)

Specify the number of controls to be checked.

Return values

The return value is 1 if the number of controls matches a specified value, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

AIT_VerifyPos

Description

Checks whether the specific control in the active window matches specified tab order.

Format

integer AIT_VerifyPos  (
  string strCaption,     // Control's caption
  integer nCtrlType,     // Control type
  integer nCtrlPos       // Tab order
);
integer AIT_VerifyPos  (
  integer nCtrlID,       // Control ID
  integer nCtrlType,     //Control type
  integer nCtrlPos       // Tab order
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

BUTTON_CTRL

The control type is a command button.

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

EDIT_CTRL

The control type is an edit box.

STATIC_CTRL

The control type is a static text.

COMBO_CTRL

The control type is a combo box.

LISTBOX_CTRL

The control type is a list box.

SPIN_CTRL

The control type is a spin control.

TREE_CTRL

The control type is a tree control.

LIST_CTRL

The control type is a list control.

DTPICKER_CTRL

The control type is a date/time picker.

nCtrlPos (input)

Specify a control's tab order.

Return values

The return value is 1 if the control's tab order matches specified tab order, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifySelected

Description

Checks whether the specified text is selected in a specific control on the active window.

Format

integer AIT_VerifySelected  (
  string strCaption,      // Control's caption
  integer nCtrlType,      // Control type
  string strSelectedText  // Selected text
);
integer AIT_VerifySelected  (
  integer nCtrlID,        // Control ID
  integer nCtrlType,      // Control type
  string strSelectedText  // Selected text
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type for which only EDIT_CTRL is valid.

strSelectedText (input)

Specify text to be checked.

Return values

The return value is 1 if the text selected in a control matches specified text, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

6

ERROR_INVALID_HANDLE

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyState

Description

Checks whether the specific control has been checked in the active window.

Format

integer AIT_VerifyState  (
  string strCaption,    // Control's caption
  integer nCtrlType     // Control type
);
integer AIT_VerifyState  (
  integer nCtrlID,      // Control ID
  integer nCtrlType     // Control type
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type, which must be one of the following values.

Value

Description

CHECKBOX_CTRL

The control type is a check box.

OPTIONBUTTON_CTRL

The control type is an option button.

Return values

The return value is 1 if the control is checked, 0 if not, 2 if unknown, and -1 if the function has not been processed successfully. The unknown status is applied only to CHECKBOX_CTRL. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

Note

You can identify the control by using a complete caption or an associated label name or specifying the first part of such a caption or label name. When specifying the first part, prefix a swung dash (~) to the character string that you specify.

AIT_VerifyText

Description

Checks whether the control text matches a specified text in the active window.

Format

integer AIT_VerifyText  (
  string strCaption,    // Control's caption
  integer nCtrlType,    // Control type
  string strText        // Text
);
integer AIT_VerifyText  (
  integer nCtrlID,      // Control ID
  integer nCtrlType,    // Control type
  string strText        // Text
);

Parameters

strCaption (input)

Specify the caption of a control.

nCtrlID (input)

Specify a control ID.

nCtrlType (input)

Specify a control type for which only EDIT_CTRL is valid.

strText (input)

Specify text to be checked.

Return values

The return value is 1 if the control text matches specified text, 0 if not, and -1 if the function has not been processed successfully. If -1 has been returned, you can use AIT_GetLastError to acquire an extended error code. The following gives the error codes that AIT_GetLastError might return:

Extended error number

Error code

8

ERROR_NOT_ENOUGH_MEMORY

14

ERROR_OUTOFMEMORY

87

ERROR_INVALID_PARAMETER

112

ERROR_DISK_FULL

1400

ERROR_INVALID_WINDOW_HANDLE

1460

ERROR_TIMEOUT

AIT_Wow64DisableWow64Redirection

Description

Switches to the mode in which the application accesses registry paths or file paths as a 64-bit application.

Format

integer AIT_Wow64DisableWow64Redirection ();

Parameters

None

Return values

The return value is 1 if the mode in which the application accesses registry or file paths as a 64-bit application has already been set before the function is executed. The return value is 0 if the mode in which the application accesses registry or file paths as a 32-bit application has been set before the function is executed.

AIT_Wow64RevertWow64Redirection

Description

Switches to the mode in which the application accesses registry paths or file paths as a 32-bit application.

Format

integer AIT_Wow64RevertWow64Redirection ();

Parameters

None

Return values

The return value is 1 if the mode in which the application accesses registry or file paths as a 64-bit application has been set before the function is executed. The return value is 0 if the mode in which the application accesses registry or file paths as a 32-bit application has already been set before the function is executed.

19.3 Examples of using API functions

This section gives examples of using the API functions provided by the AIT language.

19.3.1 Deleting carriage return and linefeed characters

The text read from a file may contain carriage return and linefeed characters (\r\n). This subsection gives an example of reading the file that contains the text Deleted CR and LF.\r\n, deleting carriage return and linefeed characters from the text, and outputting the result to RecDFile.log.

(1) Coding example

strFileName = "C:'\Sample.txt";
strCharValue = "\r\n";               // Deletes CR and LF.
if (AIT_FileOpen(strFileName, GENERIC_READ, OPEN_EXISTING, nFileHandle))
  // Reads data from the file.
  if (!AIT_FileGetLine(nFileHandle, strReadData))
    AIT_LogMessage("AIT_FileGetLine failed");
  else
    // Deletes CR and LF from the data read from the file.
    strStrName = AIT_StrRTrim(strReadData, strCharValue);
    AIT_LogMessage("strStrName = " + strStrName);
  endif;
  AIT_FileClose(nFileHandle);
else
  AIT_LogMessage("AIT_FileOpen failed");
endif;

(2) Results

The following shows the results output to RecDFile.log.

strStrName = Deleted CR and LF.

19.3.2 Extracting characters

This subsection gives an example of extracting only alphanumeric characters from the character string 0123-4567-89AB-CDEF and outputs the results to RecDFile.log.

(1) Coding example

strStrName = "0123-4567-89AB-CDEF";    // Original string
strSearchStr = "-";                    // Search string
nStartPos = 0;
while(TRUE)
  // Gets the length of string to be extracted.
  nLength = AIT_FindSubStr(strStrName, strSearchStr, nStartPos);
  if (nLength == -1)
    // Sets the string to be extracted last.
    strSubString = strStrName;
    AIT_LogMessage("strSubString = " + strSubString);
    // Ends extraction of strings.
    break;
  else
    // Extracts a string.
    if (!AIT_GetSubStr(strSubString, strStrName, nStartPos, nLength))
      AIT_LogMessage("AIT_GetSubStr failed");
      break;
    else
      AIT_LogMessage("strSubString = " + strSubString);
    endif;
    // Deletes the extracted string from the original string.
    strStrName = AIT_StrLTrim(strStrName, strSubString);
    strStrName = AIT_StrLTrim(strStrName, strSearchStr);
    strSubString = "";
  endif;
loop;
// Value of strStrName changes from that before processing.
AIT_LogMessage("strStrName = " + strStrName);

(2) Results

The following shows the results output to RecDFile.log.

strSubString = 0123
strSubString = 4567
strSubString = 89AB
strSubString = CDEF
strStrName = CDEF

19.3.3 Manipulating the HKEY_CURRENT_USER registry key during remote installation

Be careful when you want to perform remote installation by using an AIT file in which an API function that manipulates the HKEY_CURRENT_USER hive is specified. If the logged-on user of a remote installation target computer is not a member of the Administrators group, the function manipulates the HKEY_USERS\.DEFAULT key, instead of HKEY_CURRENT_USER. In this case, to manipulate the HKEY_CURRENT_USER hive, you need to use Run from the Start menu to import the relevant registry file.

To manipulate the HKEY_CURRENT_USER hive during remote installation using an AIT file:

Create the registry file.

Create the registry file for the registry branch that you want to add or edit.

Important

It is recommended that you back up the registry and understand how to restore the system before manipulating the registry.

Create an AIT file.

The following gives an example of coding that chooses Run from the Start menu, executes regedit.exe, and then imports the desired registry file. In this example, Sample.reg is the registry file to be imported.

while(iLoopCount < iLoopMax)
  if((AITEVENTFLAG1==0) && (AITIGNORE == 0))
    // Displays the Start menu.
    AIT_PlayKey("{LWIN}");
    AIT_Sleep(SLEEP_TIME_EVENTS);
    // Chooses Run.
    AIT_PlayKey("r");
    AIT_Sleep(SLEEP_TIME_EVENTS);
    AITEVENTFLAG1 = 1;
    AITIGNORE = 1;
    iLoopCount = 0;
  endif;
  if((AITEVENTFLAG1==1) && (AITIGNORE == 0) && (AIT_FocusWindow("Run", "#32770") != 0))
    // Enters the path of the registry file.
    AIT_GetCurrentDirectory(strPath);
    AIT_PlayKey("regedit.exe /s '"" + strPath + "'\Sample.reg'"");
    AIT_Sleep(SLEEP_TIME_EVENTS);
    // Imports the registry file.
    AIT_PlayKey("{ENTER}");
    AIT_Sleep(SLEEP_TIME_EVENTS);
    iLoopCount = iLoopMax;
    DM_RTN = OK_END;
    continue;
  endif;
  AITIGNORE = 0;
  iLoopCount = iLoopCount + 1;
  AIT_Sleep(SLEEP_TIME);
loop;

Store the created registry file in the same directory as for the software to be distributed.

Perform packaging, specifying the created AIT file.

Perform remote installation.

The registry file will be copied to the same directory as for setup.exe, and the AIT file will be executed at the remote installation target computers.

20 Troubleshooting the AIT

This chapter describes messages that may be output by the Automatic Installation Tool. This chapter describes the actions to be taken when a problem occurs in the Automatic Installation Tool.

20.1 Checking messages

While the Automatic Installation Tool is executing an AIT file or parsing the codes in the file, incorrect simulations, insufficient disk space, memory damage, and other problems may occur. If such problems occur, first, check whether error messages have been output to the standard output and log files. When error messages have been output, you can find the causes of the problems from the message IDs.

20.1.1 Message output destination

Messages are displayed in a dialog box or in the output window. Some messages are also output to log files. The log files are stored in the following directory:

JP1/IT-Desktop-Management-2-installation-directory\LOG

The following table explains the log files.

Filename

Maximum number of lines

Description

ait.log

2000

This file stores error messages concerning GUI operations.

aitapi.log

2000

This file stores API-related error messages.

aitexec.log

2000

This file stores error messages concerning execution and parsing.

20.1.2 Format of message explanations

The message explanations in this chapter use the following format:

Message ID

Message text

Cause

aa...aa

Action

bb...bb

Example

cc...cc

(1) Message ID

Message format: AITXnnnn-Z message-text

AIT

This indicates that the Automatic Installation Tool program displayed the message.

X

This identifies the component which output the message.

G: GUI

CE or CW: This indicates that the error occurred during execution or parsing of AIT file. (E stands for an error and W stands for warning.)

nnn or nnnn

This indicates a message number assigned by the component.

Z

This indicates a message type. For the messages that begin with AITCE or AITCW do not have this part. E or W in AITCE or AITCW substitutes for this part.

E (error):

This indicates that a fatal error occurred. Normally, processing stops if a message of this type is output.

W (warning):

This displays a warning message that indicates expected information was not detected, and the default was used instead.

Q (question):

This indicates a message to which the user has to respond.

I (information):

This displays an informational message that indicates important actions are being performed.

(2) Message text

Message text is the contents of a message. In message text, the portions indicated in the xxx style are replaced with appropriate strings.

(3) Cause

This describes why the message was output.

(4) Action

This describes actions to be taken if the message is output.

(5) Example

This shows invalid and valid API function usage examples.

20.2 Messages that may be displayed during editing

This section covers the messages that may be displayed while you are using the edit window. These messages are displayed in a dialog box or in the output window.

AITG100-E

The registry is either corrupt or invalid.

Cause

Possible causes are as follows:

The registry database is damaged.

A registry key is invalid.

The registry is damaged. The file cannot be recovered because some file structures including registry data are damaged, the memory image for a system file is damaged, or an alternative backup or log does not exist or is damaged.

Although the system attempted to load or restore the file into the registry, the specified file did not have the registry file format.

Action

Carry out required processing according to appropriate additional information. If the registry is damaged, use a recovery disk to restore settings.

If you cannot solve the problem, contact the system administrator.

AITG101-E

The registry operation failed.

Cause

Possible causes are as follows:

A registry key could not be opened.

A registry key could not be loaded.

A registry key could not be updated.

Because an invalid I/O operation on the registry caused a non-recoverable error, a read, write, or flush operation failed for one of the files including system registry images.

An invalid operation was performed on a registry key that has already been indicated as deleted.

A necessary area could not be allocated in the registry log.

No symbolic link can be created for a registry key already having a sub-key or value.

An attempt has been made to create a stable sub-key under a volatile parent key.

The target multi-byte code page contains no Unicode mapping.

No index matches the specified key.

Action

Carry out required processing according to appropriate additional information.

If you cannot solve the problem, contact the system administrator.

AITG102-E

An internal error occurred.

Cause

The application attempted to access resources by using a handle such as the following:

an invalid handle;

an invalid window handle; or

an invalid hook handle.

Action

Re-execute the application.

If you cannot solve the problem, contact the system administrator.

AITG103-E

Memory or disk space is insufficient.

Cause

Possible causes are as follows:

Memory is insufficient to process the command.

Memory is insufficient to complete the processing.

The disk is full.

The disk contains no sufficient space.

System resources are insufficient to complete the required service.

Action

Terminate all the unnecessary applications, and retry the processing.

Delete unnecessary files on the disk, and re-execute the application.

If you cannot solve the problem, contact the system administrator.

AITG104-E

The file or directory operation failed.

Cause

Possible causes are as follows:

The system cannot find the specified file.

The system cannot find the specified path.

The system cannot open the file.

The system cannot find the specified drive.

No directory can be deleted.

The system cannot move the file to another disk drive.

The file does not exist.

No directory or file can be created.

The filename is too long.

The directory is not a subdirectory of the root directory.

The directory is not empty.

During access to the hard disk, disk operations failed, with a retry failing.

Action

Carry out required processing according to appropriate additional information.

For example, use the valid filename, path name or drive name to retry the processing.

If you cannot solve the problem, contact the system administrator.

AITG105-E

An attempt to initiate the Recorder failed.

Cause

Any of the following items has been initialized in the edit window:

Syntax check

Run

Recorder

Window properties

Action

Re-execute the application.

If you cannot solve the problem, contact the system administrator.

AITG106-E

The debugging operation failed.

Cause

During debugging, the application cannot communicate with the execution engine.

Action

Re-execute the application.

If you cannot solve the problem, contact the system administrator.

AITG107-W

A syntax file was not found. Syntax highlighting will not be enabled.

Cause

The syntax file (AIT.syn) could not be found from the edit window.

Action

The path of the syntax file set in either of the following registry keys does not indicate the correct location.

When the OS is a 32-bit version:

HKEY_LOCAL_MACHINE\SOFTWARE\HITACHI\JP1/IT Desktop Management - AIT\ConfPath

When the OS is a 64-bit version:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Hitachi\JP1/IT Desktop Management - AIT\ConfPath

Verify the path in the registry, and re-execute the application.

AITG108-E

The line number is invalid.

Cause

An invalid line number has been specified in the line number edit box of the Go To or Breakpoints Setup dialog box.

Action

Specify a valid line number, and re-execute the processing.

AITG109-E

The string string.could not be found.

Cause

The application could not find the character string specified in the Find or Replace dialog box.

Action

Unnecessary

AITG110-E

The format of the PACKAGE_INFO section is invalid.

Cause

When the Package Information dialog box was opened, a format error was detected in the PACKAGE_INFO section of the AIT file.

Action

Check the syntax of the AIT file, then open the Package Information dialog box.

AITG111-E

Enter the required item item-name.

Cause

Any of the following required package items has not been specified in the Package Information dialog box:

Package ID

Product

Version

Installer name

Install drive

Install directory

Action

Specify the required items, then generate package information.

AITG112-Q

Do you want to update the Package Information?

Cause

This message is displayed if you click the Stop button in the Recorder dialog box. Select whether to generate the PACKAGE_INFO section of the AIT file.

Action

Click the Yes button to display the Package Information dialog box to generate the PACKAGE_INFO section. Click the No button to create the AIT file without the PACKAGE_INFO section.

AITG113-E

Specify a value between 1 and 64.

Cause

An integer value that is not in the range from 1 to 64 is specified in the Tab size text box of the Tabs page in the Options dialog box.

Action

Specify an integer value from 1 to 64, and then retry the operation.

AITG114-E

Invalid characters have been entered. Specify specifiable-character-string.

Cause

An invalid character is specified for one or more of the following package items in the Package Information dialog box:

Package ID

Product

Version

Installer name

Install directory

Action

Enter a specifiable character string according to the contents displayed in specifiable-character-string, then generate package information.

AITG115-W

The registry key could not updated.

Cause

Possible causes are as follows:

The registry database is damaged.

A registry key cannot be opened.

A registry key cannot be read.

A registry key cannot be updated.

A registry key is invalid.

The registry is damaged. The file cannot be recovered because part of the file structures including registry data are damaged, a memory image on a system file is damaged, or an alternative backup or log does not exist or is damaged.

Although the system attempted to update a file in the registry, the specified file did not have the registry file format.

Action

Carry out required processing according to appropriate additional information.

AITG116-W

The registry key could not be read.

Cause

Possible causes are as follows:

The registry database is damaged.

A registry key cannot be opened.

A registry key cannot be read.

A registry key is invalid.

The registry is damaged. The file cannot be recovered because part of the file structures including registry data are damaged, a memory image on a system file is damaged, or an alternative backup or log does not exist or is damaged.

Although the system attempted to read a file from the registry, the specified file did not have the registry file format.

Action

Carry out required processing according to appropriate additional information.

AITG117-W

The registry key could not be deleted.

Cause

Possible causes are as follows:

The registry database is damaged.

A registry key cannot be deleted.

A registry key is invalid.

The registry is damaged. The file cannot be recovered because part of the file structures including registry data are damaged, a memory image on a system file is damaged, or an alternative backup or log does not exist or is damaged.

Although the system attempted to delete the file from the registry, the specified file did not have the registry file format.

Action

Carry out required processing according to appropriate additional information.

AITG118-W

The file cannot be closed. The file is being processed.

Cause

An attempt was made to close the AIT file during a syntax check on the file.

Action

Unnecessary

AITG119-W

The application cannot be closed. The file is being processed.

Cause

Possible causes are as follows:

An attempt was made to close the AIT file during a syntax check on the file.

An attempt was made to close the application during execution of the AIT file.

Action

Unnecessary

AITG120-E

The symbol was not found.

Cause

Possible causes are as follows:

In the debug mode, a variable not defined in the AIT file was entered in the Watch window.

In the debug mode, a symbol not defined in the AIT file was entered.

Action

Verify that the symbol you entered in the Watch window is a valid variable in the AIT file being debugged.

AITG121-W

The user permission is insufficient. Saved options will be applied only to the current session.

Cause

You attempted to save a registry value although you were logged on as a guest.

Action

Unnecessary

AITG122-E

The maximum of maximum-number-of-characters-you-can-use-to-specify-the-package-item characters is exceeded.

Cause

The generated PACKAGE_INFO section includes a package item specified with too many characters.

Action

Make sure that all the items in the PACKAGE_INFO section are specified with a correct character length.

AITG123-E

The maximum of maximum-number-of-characters-you-can-use-to-specify-the-package-item characters is exceeded.

Cause

The generated program product ID file contains a package item longer than the maximum.

Action

After checking the maximum number of characters that can be used to specify the package item, specify the package item with a correct length.

AITG124-E

An attempt to operate the Program product ID file has failed.

Cause

Another application might be using the program product ID file.

Action

Close the program product ID files that are being used by other applications.

AITG125-E

Enter the item item-name.

Cause

One or the other of the following items was not specified in the Package Information dialog box:

AIT file path

Package file ID

Action

After specifying the necessary item, generate the package information.

AITG200-E

The recording operation failed.

Cause

The application attempted to access resources by using a handle such as the following:

an invalid handle;

an invalid window handle; or

an invalid hook handle.

Action

Re-execute the application.

If you cannot solve the problem, contact the system administrator.

AITG201-E

An attempt to acquire window details failed.

Cause

Window information could not be acquired during recording.

Action

If you cannot solve the problem, contact the system administrator.

AITG202-E

An attempt to acquire control details failed.

Cause

Window control information could not be acquired during recording.

Action

If you cannot solve the problem, contact the system administrator.

AITG203-E

An attempt to acquire event details failed.

Cause

Event information could not be acquired during recording.

Action

If you cannot solve the problem, contact the system administrator.

AITG204-E

An attempt to generate the PACKAGE_INFO section in the AIT file failed.

Cause

The PACKAGE_INFO section could not be generated after the end of recording.

Action

Delete the temporary folder before re-execution.

If you cannot solve the problem, contact the system administrator.

AITG205-E

An attempt to generate the DEFINE section in the AIT file failed.

Cause

The DEFINE section could not be generated after the end of recording.

Action

Delete a temporary folder before re-execution.

If you cannot solve the problem, contact the system administrator.

AITG206-E

An attempt to generate the MAIN section in the AIT file failed.

Cause

The MAIN section could not be generated after the end of recording.

Action

Delete a temporary folder before re-execution.

If you cannot solve the problem, contact the system administrator.

AITG208-E

An attempt to generate the AIT file failed.

Cause

The AIT file could not be generated after the end of recording possibly because:

disk operations and retries have not performed successfully during access to the hard disk;

memory is insufficient to process the command;

memory is insufficient to complete the processing; or

the handle is invalid.

Action

Carry out required processing according to appropriate additional information.

If you cannot solve the problem, contact the system administrator.

AITG209-I

The Installer application installer-name executed successfully.

Cause

The AIT file has been executed normally.

Action

Unnecessary

AITG211-W

The AIT File Log option is not set in the registry.

Cause

The log option is not set in the registry.

Action

Set the log option in the registry.

AITG212-I

The recording process completed.

Cause

Recording has been completed normally.

Action

Unnecessary

AITG213-I

Creation of the AIT file was successful.

Cause

The AIT file has been generated successfully after the end of recording.

Action

Unnecessary

AITG214-W

The user information file update was skipped because an event is unknown.

Cause

The Recorder cannot resume recording after a temporary stop.

Action

Unnecessary

AITG215-E

An attempt to continue recording failed.

Cause

The Recorder cannot resume recording after a temporary stop.

Action

Carry out required processing according to appropriate additional information.

AITG216-Q

An attempt to start the Installer application failed: installer-name, additional-information

Do you want to continue recording?

Cause

An invalid installer name is specified in the Recorder dialog box.

For additional-information, one of the following strings is displayed:

The specified file could not be found.

The specified path could not be found.

The access was rejected.

Memory is insufficient to carry out the processing.

Action

Click the Yes button to start recording, and click the No button to carry out required processing according to additional information.

20.3 Messages that may be displayed during execution and parsing of AIT files

This section covers the messages that may be displayed during execution and parsing of AIT files. These messages appear in the output window.

AITCE-0001

Unexpected token-1, missing token-2.

Cause

An invalid keyword or symbol token-1 was detected. The script parsing expects the keyword or symbol token-2.

Action

Add token-2 if necessary.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END = 0;
   const integer NG_END = -1      // ";" is not specified.
   const integer sloop_max = 30;
}

Example of valid specification:

DEFINE
{
   const integer OK_END = 0;
   const integer NG_END = -1;      // ";" has been added.
   const integer sloop_max = 30;
}

AITCE-0002

Unexpected token

Cause

An invalid keyword or symbol token was detected.

Action

Delete the unexpected keyword or symbol.

Example

Example of invalid specification:

DEFINE
{
   integer OK_END = 0;
   integer sloop_max = 0;;      // Two semicolons (;;) are specified.
}

The sloop_max variable contains two semicolons (;;).

Example of valid specification:

DEFINE
{
   integer OK_END = 0;
   integer sloop_max = 0;      // The semicolon (;) has been deleted.
}

One semicolon (;) has been deleted from the sloop_max variable.

AITCE-0003

A function name is used as an identifier.

Cause

A function name cannot be used as an identifier.

Action

Change the identifier name.

Example

Example of invalid specification:

DEFINE
{
   integer AIT_LogMessage = 10;
}

A function name is used as a variable name.

Example of valid specification:

DEFINE
{
   integer AIT_LogMessageNumber = 10;
}

The variable name has been changed to AIT_LogMessageNumber.

AITCE-0005

The number of nested levels is greater than 255.

Cause

The number of nesting levels in the AIT file exceeds 255, which is the maximum.

Action

If the number of nested if, if-else, do-while, while, or switch structure levels exceeds the maximum of 255, the AIT file cannot be parsed. Re-edit the AIT file to decrease the number of nested structure levels.

AITCE-0006

The identifier name exceeds 64 characters.

Cause

Each identifier name can have up to 64 characters. The AIT file contains an identifier name that has more than 64 characters.

Action

Specify an identifier name that has up to 64 characters.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
   integer sample123456sample123456sample123456sample123456sample123456sample = 0;      // The specified variable name has 66 characters.
}

The second variable name has more than 64 characters.

Example of valid specification:

DEFINE
{
   integer sloop_max = 0;
   integer sample123456 = 0;   // The specified variable name
                               // has 64 or fewer characters.
}

The second variable name has 64 or fewer characters.

AITCE-0007

The string constant should not span multiple lines.

Cause

As the first line ends with \n, the string constant is written over two lines.

Action

Specify a string constant in one line.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
   string SoftwareName = " My
                           Setup";  // The string constant is
                                    // written over two lines.
}

A string constant in the SoftwareName variable is written over two lines.

Example of valid specification:

DEFINE
{
   integer sloop_max = 0;
   string SoftwareName = " My Setup";   // The specified string constant is in one line.
}

The string constant for variable SoftwareName is specified in one line.

AITCE-0008

Use a valid escape sequence.

Cause

The string constant for the AIT file specified during execution contains an invalid escape sequence.

Action

Use a valid escape sequence for a string constant.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
   string str1 = "sample'
                  testing";
}

The string variable strl is assigned a string written over two lines but an invalid escape sequence is used.

Instead of an apostrophe ('), an underscore (_) must be used to indicate that the string continues to the next line.

Example of valid specification:

DEFINE
{
   integer sloop_max=10;
   string str1 = "sample_
                  testing";
}

An apostrophe (') is replaced with an underscore (_), which is the correct escape sequence.

AITCE-0009

Identifiers cannot be used in case statements.

Cause

An identifier is specified in the case clause.

Action

Use only constants or macros in the case clause.

Example

Example of invalid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch (FileVersion)
      case stMsgText:      // An identifier is specified
                           // in the case clause.
    :
         break;
      default:
    :
         break;
   endswitch;
}

The identifier stMsgText is specified in the case clause.

Example of valid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch (FileVersion)
      case "7.1":      // A string constant which is not
                       // an identifier is specified.
    :
         break;
      default:
    :
         break;
   endswitch;
}

Instead of the identifier stMsgText, a string constant is specified in the case clause.

AITCE-0010

Usage of the "+" or "-" signs is invalid.

Cause

The ++, --, +-, or -+ operator is used in the AIT file. These operators specified in an AIT file cannot be parsed.

Action

Delete the ++, --, +-, or -+ operator from the AIT file.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_count = 0;
}
MAIN
{
   if (AIT_FileExists("#setup.exe") == 0)
      :
      :
      sloop_count++;      // The invalid operator"++" is used to
                          // increment the value of the variable.
   endif;
}

You cannot use the increment and decrement operators.

Since ++ is specified for the sloop_count variable, an error message is displayed.

Example of valid specification:

DEFINE
{
   integer sloop_count = 0;
}
MAIN
{
   if (AIT_FileExists("#setup.exe") == 0)
      :
      :
      sloop_count = sloop_count + 1;   // "++" is not used.
   endif;
}

++ is replaced with another equivalent code.

AITCE-0011

The AIT file contains more than 65535 lines.

Cause

The AIT file can contain up to 65,535 lines. If the AIT file contains more than 65,535 lines, parsing of the AIT file stops.

Action

Reduce the number of lines in the AIT file.

AITCE-0012

identifier : An identifier is undeclared.

Cause

The variable of an undeclared variable type is specified.

Action

Correctly declare the variable in the DEFINE section.

Example

Example of invalid specification:

DEFINE
{
   string stMsgText;
}
MAIN
{
   if (AIT_FileExists("#setup.exe") == 0)
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
      AIT_LogMessage(stMsgText);
      sloop_max = 0;      // This variable is not declared
                          // in the DEFINE section.
   endif;
}

The sloop_max variable is specified in the MAIN section although it is not declared in the DEFINE section.

Example of valid specification:

DEFINE
{
   string  stMsgText;
   integer sloop_max;      // Variable sloop_max has been declared.

}
MAIN
{
   if (AIT_FileExists("#setup.exe") == 0)
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
      AIT_LogMessage(stMsgText);
      sloop_max = 0;     // A declared variable is used.
   endif;
}

The sloop_max variable has been declared in the DEFINE section, and is specified in the MAIN section.

AITCE-0013

identifier: Redeclared.

Cause

The already declared identifier is redeclared.

Action

Delete the redeclared variable.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 10;
   string sloop_max = "sample";     // Variable sloop_max is
                                    // redeclared as the string type.
}

The sloop_max variable that was declared as the integer type is redeclared as the string type.

Example of valid specification:

DEFINE
{
   integer sloop_max = 10;
   string stMsgText = "sample";    // Another variable name is used.
}

The redeclared variable sloop_max has been deleted, and a new variable name is declared.

AITCE-0014

The package information field package-item contains invalid data value.

Cause

Any of the package items in the PACKAGE_INFO section contains an invalid value.

Action

Specify a value adapted to the package information field.

Example

Example of invalid specification:

PACKAGE_INFO
{
   PackageID = "#$@#ADOBEACROBATREADER";   // The package ID contains
                                           // invalid string #$@#.
   Product = "Adobe Reader 6.0";
   Version = "0060";
   InstallerName = "AdbeRdr60_enu_full.exe";
   InstallDrive = "C:";
   InstallDirectory = "'Program Files'\Adobe'\Acrobat 6.0";
}

The package ID in the PACKAGE_INFO section contains an invalid string #$@.

Example of valid specification:

PACKAGE_INFO
{
   PackageID = "ACROBAT-READER";       // Invalid string #$@#
                                       // has been deleted.
   Product = "Adobe Reader 6.0";
   Version = "0060";
   InstallerName = "AdbeRdr60_enu_full.exe";
   InstallDrive = "C:";
   InstallDirectory = "'Program Files'\Adobe'\Acrobat 6.0";
}

The invalid string #$@ has been deleted from the package ID in the PACKAGE_INFO section.

AITCE-0015

A 'const' cannot be re-assigned a value.

Cause

The variable defined as the constant type is assigned a value in the MAIN section.

Action

Change the definition of constant or delete the right side of the constant.

Example

Example of invalid specification:

DEFINE
{
   const float SLEEP_TIME = 2.0;
   integer sloop_count;
}
MAIN
{
   if (AIT_FocusWindow("Setup", "#32770",0.0) > 0)
      AIT_PlayKey("{Enter}");
      AIT_LogMessage("Setup: Enter");
      sloop_count = 0;
      SLEEP_TIME = 3.0;      // The constant value for variable
                             // SLEEP_TIME is being changed.
      AIT_Sleep(SLEEP_TIME);
   endif;
}

The SLEEP_TIME variable defined as the constant float type has been assigned a different value in the MAIN section.

Example of valid specification:

DEFINE
{
   const float SLEEP_TIME = 3.0;
   integer sloop_cnt;
}

MAIN
{
   if (AIT_FocusWindow("Setup", "#32770",0.0) > 0)
      AIT_PlayKey("{Enter}");
      AIT_LogMessage("Setup : Enter");
      sloop_cnt = 0;
      AIT_Sleep(SLEEP_TIME);
   endif;
}

In the MAIN section, assignment to the SLEEP_TIME variable of type constant float has been deleted.

AITCE-0018

The AIT file analysis has been abnormally terminated because of a syntax error in the AIT file.

Cause

The syntax check has encountered a fatal error (including invalid string end processing or invalid character count specification in a variable name).

Action

Correct the error, then re-check the AIT file.

Example

Example of invalid specification:

DEFINE
{
   string ErrorTxt = "ABC
def";
}

Although a string constant cannot be specified over multiple lines, the string is specified over multiple lines.

Example of valid specification:

DEFINE
{
   string ErrorTxt = "ABC_
def";      // "_" indicates the continuation of the string.
}

Add an underscore (_) that indicates that the string continues to the next line.

AITCE-0019

Division by zero

Cause

Because the second operand for division is 0, the division is considered as being undefined for an AIT file parsing.

Action

Specify a value other than 0 as the divisor.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_count = 0;
   const integer  sloop_max = 30;
}
MAIN
{
   sloop_count = sloop_max / 0;      // As the divisor is 0, this
                                     // results in and error.
}

Although division by 0 is impossible, the sloop_max variable is divided by 0.

Example of valid specification:

DEFINE
{
   integer sloop_count = 0;
   const integer sloop_max = 30;
}
MAIN
{
   sloop_count = sloop_max / 1;      // The divisor has been changed
                                     // to a value other than 0.
}

The division of the sloop_max variable by 0 has been deleted.

AITCE-0020

data type-1 and data type-2 are incompatible for processing-name.

Cause

The left-side and right-side values for an operator are assigned incompatible data types. For example, if the string and integer types have been used for comparison, this message is displayed.

Action

Specify data types compatible between the left-side and right-side values for an operator.

Example

Example of invalid specification:

DEFINE
{
   const integer ExeVersion = 7;
   const string FileVersion = "7";
}
MAIN
{
   if (ExeVersion == FileVersion)   // The string and integer types
                                    // are used for comparison.
      ...
      ...
   endif;
}

The ExeVersion variable of type integer and the FileVersion variable of type string are compared.

The string and integer types are incompatible for a comparison operation.

Example of valid specification:

DEFINE
{
   const integer ExeVersion = 7;
   const integer FileVersion = 7;
}
MAIN
{
   if (ExeVersion == FileVersion)      // Variables of the same type
                                       // are compared.
      ...
      ...
   endif;
}

The data type of the FileVersion variable has been changed from string to integer to enable comparison.

AITCE-0021

operator-name incompatible for operation data-type-1.

Cause

For the indicated operation, an invalid data type is specified. For example, if the float type has been used for a remainder operation (%) or if the string type has been used for an operation, this message is displayed.

Action

Specify a data type that can be used for the operation.

Example

Example of invalid specification:

DEFINE
{
   float SLEEP_TIME = 7.1;
}
MAIN
{
   SLEEP_TIME = SLEEP_TIME % 2;      // float type cannot be used for
                                     // remainder operation. This
                                     // results in an error.
}

Although the float type cannot be used for a remainder operation, float-type variable SLEEP_TIME is used for the remainder operation.

Example of valid specification:

DEFINE
{
   integer SLEEP_TIME = 7;
}
MAIN
{
   SLEEP_TIME = SLEEP_TIME % 2;      // Integer-type variable is used
                                     // for remainder operation.
}

The integer-type value is used for the remainder operation.

AITCE-0022

Specify an integer value between '-2147483648' and '2147483647'.

Cause

An integer value out of the allowable range is specified.

Action

Specify an integer value between -2,147,483,648 and 2,147,483,647.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END = 21474836476;   // Value exceeds the maximum.
}

The OK_END variable is assigned an integer-type value greater than the maximum.

Example of valid specification:

DEFINE
{
   const integer OK_END =214748364;      // Value is within the
                                         // allowable range.
}

The OK_END variable has been assigned an integer-type value within the allowable range.

AITCE-0023

Specify a float value between '3.402823466e+38' and '1.175494351e-38'.

Cause

A float value out of the allowable range is specified.

Action

Specify a float value between 3.402823466e+38 and 1.175494351e-38.

Example

Example of invalid specification:

DEFINE
{
   const float NG_END = 3.402823466e+40;  // Value exceeds the maximum.
}

The NG_END variable is assigned a float-type value greater than the maximum.

Example of valid specification:

DEFINE
{
   const float NG_END = 3.402823466e+10;    // Value is within the
                                            // allowable range.
}

The NG_END variable has been assigned a float-type value within the allowable range.

AITCE-0024

The data type for a switch expression is invalid.

Cause

The data type of a case label value does not match the data type of the switch statement. For example, if a switch statement of type integer contains a case label whose value is the float type, this message is displayed.

Action

Use the same data type for the switch statement and the case label values.

Example

Example of invalid specification:

DEFINE
{
   const string FileVersion = "7.1";
   integer sloop_max = 0;
}
MAIN
{
   switch (FileVersion)   // The switch statement is the string type.
       case 7.1:      // The case label is assigned an integer value.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

Although the switch statement is the string type, the case value is the integer type.

Example of valid specification:

DEFINE
{
   const string FileVersion = "7.1";
   integer sloop_max = 0;
}
MAIN
{
   switch (FileVersion)
      case "7.1":    // A value of the string type is specified.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

The case label has been assigned a string-type value to match the data type with that of the switch statement.

AITCE-0025

Unexpected EOF found in comment.

Cause

There is a comment that begins with /* but the comment end symbol (*/) is not found until the end of the file.

Action

Specify */ to close the comment before the end of the file.

Example

Example of invalid specification:

DEFINE
{
   /* Data type used in  the AIT file   // The comment is not closed.
   const integer NG_END = -1
   const integer sloop_max = 30;
}

All comments must be closed. In this example, the comment is started with /*, but is not ended with */.

Example of valid specification:

DEFINE
{
   /* Data type used in the AIT file */   // The comment is ended.
   const integer NG_END = -1;
   const integer sloop_max = 30;
}

The comment is ended with */.

AITCE-0026

A character is unknown: hexadecimal-character-code.

Cause

A character not defined in AIT language specifications exists. The hexadecimal character code is displayed.

Action

Specify only valid characters covered in AIT language specifications.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END = 0;
   const integer NG_END = -1;
   const integer sloop_max = #30;      // Invalid character "#" exists.
}

Although an invalid string like #$@ cannot be used in a string constant, variable sloop_max contains #.

Example of valid specification:

DEFINE
{
   const integer OK_END =0;
   const integer NG_END = -1;
   const integer sloop_max = 30;    // Invalid character "#" is deleted.
}

# has been deleted from the sloop_max variable.

AITCE-0027

The use of the void data type in the expression is invalid. Use a valid datatype.

Cause

An expression includes a function that returns a void-type value.

Action

In expressions, do not use any functions that return a void-type value.

AITCE-0029

Case value value already used.

Cause

The same case value is used twice or more times in a switch statement.

Action

Specify a unique case label value.

Example

Example of invalid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(FileVersion )
      case "7.1":
         ...
         ...
         break;
      case "7.1":      // Value "7.1" has already been used.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

The case labels of switch statements must have unique values.

In this example, 7.1 is used as the value of the second case label but is also used as the value of the first case label.

Example of valid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(FileVersion )
      case "7.1":      // Duplicate case value "7.1" has been deleted.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

The second case label has been deleted.

AITCE-0030

function name : A function name is invalid.

Cause

An invalid function name (not found in the list of available API functions) is specified.

Action

Specify a valid function name in the AIT file. For details about valid functions (API names), see 19.1 API functions.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists1("#setup.exe") == 0) // AIT_FileExists1 is
                                              // not a valid API name.
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

AIT_FileExists1() is not a valid API.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists("setup.exe") == 0)   // Valid API name
                                              // has been specified.
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

AIT_FileExists() has been specified as an API name.

AITCE-0031

function name : The function does not take the number-of-specified-parameters parameter.

Cause

There is a function that has an invalid number of parameters.

Each function uses a specific set of parameters. This message is displayed if the number of parameters specified for a function does not match the valid number of parameters for the function.

Action

Specify a valid number of parameters for the function. For a list of actual parameters, see 19.2 Details about the API functions.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists() == 0)
      // Argument was specified for AIT_FileExists.
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

Specify at least one parameter for AIT_FileExists(). In this example, no parameter is specified for AIT_FileExists().

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists("#setup.exe") == 0)  // A parameter has been
                                              // specified for
                                              // AIT_FileExists.
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

A parameter has been specified for AIT_FileExists().

AITCE-0032

One or more arguments specified for the function are of invalid data type.

Cause

At least one parameter for the function has a data type that the function does not expect.

Each function has a specific set of parameters. This message is displayed if the data type of a parameter specified for a function does not match the data type of the function.

Action

Specify a valid data type for the function argument. For a list of actual arguments, see 19.2 Details about the API functions.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion )
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
         AIT_Sleep(3);      // Integer value is specified in
                            // AIT_Sleep.
      endif;
   endif;
}

Although only a float-type parameter can be specified for AIT_Sleep(), an integer-type parameter is specified.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string  FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == Version)
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
         AIT_Sleep(3.1);      // Data type has been changed from
                              // integer to float.
      endif;
   endif;
}

The data type of the parameter for AIT_Sleep() has been changed from integer to float.

AITCE-0034

The label label-name is undefined.

Cause

The goto statement is used with no label defined.

In the AIT file, the associated label must be defined for each goto statement.

Action

Specify associated label names for all goto statements.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
}
MAIN
{
   goto ErrorLabel; // Label ErrorLabel is undefined.
   sloop_max = 0;
}

An associated label statement must be specified for the goto statement.

In this example, only goto ErrorLabel is specified. The label ErrorLabel is not defined in the MAIN section.

Example of valid specification:

DEFINE
{
   integer sloop_max = 0;
}
MAIN
{
   goto ErrorLabel;
   sloop_max = 0;
ErrorLabel:      // The label has been defined.
}

The label ErrorLabel has been specified for the goto statement.

AITCE-0037

The label label-name for the goto statement is in a different block.

Cause

The specified label name and the associated goto statement exist in different sections.

A goto statement and the associated label must exist in the same section.

Action

Specify a label name and the associated goto statement in the same section.

Example

Example of invalid specification:

DEFINE
{
   string stMsgText;
}
MAIN
{
   goto ErrorLabel;      // goto statement is defined in MAIN section.
}
ERROR
{
ErrorLabel:      // Label is defined in ERROR section.
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
}

A label and the associated goto statement must be defined in the same section. In this example, the goto statement is in the MAIN section, while the label ErrorLabel is in the ERROR section.

Example of valid specification:

DEFINE
{
   string stMsgText;
}
MAIN
{
      goto ErrorLabel;
ErrorLabel:      // The label is defined in the MAIN section.
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
}

The label ErrorLabel and the associated goto statement have been defined in the MAIN section.

AITCE-0038

The value assigned to the variable is of an invalid data type.

Cause

The value assigned to a variable has an invalid data type. For example, this message is displayed if a string value has been assigned to an integer-type variable.

Action

Specify a value of a valid data type.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END =0;
   const integer NG_END = -1;
   const integer sloop_max = "30";   // A string value is assigned
                                     // to an integer-type variable.
}

In this example, a string-type constant is assigned to the sloop_max variable of type integer constant.

Example of valid specification:

DEFINE
{
   const integer OK_END =0;
   const integer NG_END = -1;
   const integer sloop_max = 30;      // integer value, not a string
                                      // value has been assigned.
}

The string constant has been deleted, and the sloop_max variable of type integer has been assigned.

AITCE-0039

An invalid 'break' statement was found.

Cause

A break statement is used in a statement other than the do-while, while-loop, for-next, or switch statement. The break statement is valid only in the loop structure.

Action

Use the break statement in the do-while, while-loop, for-next, or switch statement.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion )
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
         break;      // The break statement is in the if statement.
      endif;
   endif;
}

In this example, the break statement is in the if structure.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string  FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

The break statement has been deleted from the if structure.

AITCE-0040

An invalid 'continue' statement was found.

Cause

A continue statement is used in a statement other than do-while, while-loop, or for-next statement. The continue statement is valid only in the loop structure.

Action

Use the continue statement only in the do-while, while-loop, or for-next statement.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
         continue;      // The continue statement is in the if statement.
      endif;
   endif;
}

In this example, the continue statement is in the if structure.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string  FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

The continue statement has been deleted from the if structure.

AITCE-0041

loop-structure cannot have more than 255 break statements.

Cause

The loop structure contains more than 255 break statements. The loop structure (do-while, while, for-next, or switch structure) can contain up to 255 break statements.

Action

Reduce the number of break statements in the loop structure to 255 or fewer.

AITCE-0042

loop-structure cannot have more than 255 continue statements.

Cause

The loop structure contains more than 255 continue statements. The loop structure (do-while, while, or for-next) can use up to 255 continue statements.

Action

Reduce the number of continue statements in the loop structure to 255 or fewer.

AITCE-0043

The 'switch' statement cannot have more than 255 case labels.

Cause

The switch statement contains more than 255 case labels. The switch statement can use up to 255 case labels.

Action

Reduce the number of case labels in the switch statement to 255 or fewer.

AITCE-0044

The 'switch' statement cannot have more than one default label.

Cause

The switch statement can use only one default statement.

Action

Specify only one default statement in the switch statement.

Example

Example of invalid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(FileVersion )
      case "7.1":
         ...
         ...
         break;
      default:      // First default statement
         ...
         ...
         break;
      default:      // Two default statements are specified.
         ...
         ...
         break;
   endswitch;
}

Only one default statement can be specified in the switch statement. In this example, the switch statement contains two specified default statements.

Example of valid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(FileVersion)
      case "7.1":
         ...
         ...
         break;
      default:      // Only one default statement is specified.
         ...
         ...
         break;
   endswitch;
}

One default statement has been deleted from the switch statement.

AITCE-0045

A required field field-name is missing in the Package Info block.

Cause

One of the fields which must be specified in the PACKAGE_INFO section is missing.

Action

Specify all the fields required in the PACKAGE_INFO section.

Example

Example of invalid specification:

PACKAGE_INFO
{
   // The package ID that must be specified is missing.
   Product = "Adobe Reader 6.0";
   Version = "0060";
   InstallerName = "AdbeRdr60_enu_full.exe";
   InstallDrive = "C:";
   InstallDirectory = "'Program Files'\Adobe'\Acrobat 6.0";
}

The package ID that must be specified is missing.

Example of valid specification:

PACKAGE_INFO
{
   PackageID = "ADOBEACROBATREADER";   // The required package item
                                       // has been specified.
   Product = "Adobe Reader 6.0";
   Version = "0060";
   InstallerName = "AdbeRdr60_enu_full.exe";
   InstallDrive = "C:";
   InstallDirectory = "'Program Files'\Adobe'\Acrobat 6.0";
}

The package ID has added in the PACKAGE_INFO section.

AITCE-0046

Unary operators '+', '-' and '!' cannot be used with a string constant.

Cause

A unary operator is specified together with a string constant.

Action

Do not specify a unary operator together with a string constant.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END =0;
   const integer NG_END = -1;
   const string szMsgText = !"30";  // "!" is used together with a
                                    // string constant.
}

A unary operator (+, -, or !) cannot be used to initialize a string-type constant in the DEFINE section.

In this example, ! is used together with a string-type constant in the szMsgText variable.

Example of valid specification:

DEFINE
{
   const integer OK_END =0;
   const integer NG_END = -1;
   const string szMsgText = "30";      // "!" has been deleted.
}

! has been deleted from the szMsgText variable.

AITCE-0047

The use of labels is invalid in an expression.

Cause

A label is used in the expression.

Action

Do not use a label in the expression.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
}
MAIN
{
ErrorLabel:
   if (ErrorLabel)      // The label is used in the if structure.
      AIT_LogMessage("Setup(English)For Windows-Start");
      if (AIT_FileExists("#setup.exe") == 0)
         goto ErrorLabel;
         sloop_max = 0;
      endif;
   endif;
}

A label cannot be used in the expression. In this example, the label ErrorLabel is used in the if structure.

Example of valid specification:

DEFINE
{
   integer sloop_max = 0;
   string stMsgText;
}
MAIN
{
   if(1)      // The label has been deleted from the expression.
      if (AIT_FileExists("#setup.exe") == 0)
         goto ErrorLabel;
         sloop_max = 0;
      endif;
ErrorLabel:
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
      AIT_LogMessage(stMsgText);
   endif;
}

The label ErrorLabel has been deleted from the if structure to validate the value in the expression.

AITCE-0048

The "!" operator is not allowed in case statements.

Cause

An expression is specified in a case label. Only constant values can be specified in the case labels of switch statements.

Action

Do not specify an expression in a case label.

Example

Example of invalid specification:

DEFINE
{
   const integer FileVersion = 7;
   string stMsgText;
}
MAIN
{
   switch (FileVersion)
      case 7:
         ...
         ...
         break;
      case 5 + 1:      // Expression cannot be used in a case label.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

Only a constant can be used in the switch statement. In this example, the second case label is assigned an additive expression.

Example of valid specification:

DEFINE
{
   const integer FileVersion = 7;
   string stMsgText;
}
MAIN
{
   switch (FileVersion)
      case 7:
         ...
         ...
         break;
      case 6:      // The expression has been deleted, and a constant
                   // is specified, instead.
         :
         :
         break;
      default:
         :
         :
         break;
   endswitch;
}

The additive expression has been deleted from the second case statement, and a constant is specified, instead.

AITCE-0050

The AIT file version is higher than the DLL version of the execution engine.

Cause

The AIT file version may be higher than the DLL version of the execution engine.

Action

Before executing an AIT file, check whether the DLL version of the script engine is higher than ScriptFileVersion indicated in the PACKAGE_INFO section. ScriptFileVersion must be lower than the DLL version.

AITCW-0016

Conversion from higher-ranking-data-type to lower-ranking-data-type: Possible loss of accuracy

Cause

If you attempt to assign a lower-ranking data type a higher-ranking data type in the AIT file, the value is rounded down, being assigned to the lower-ranking data type. For example, this message is displayed if a float-type variable has been assigned to an integer-type variable.

Action

Use a higher-ranking data type.

Example

Example of invalid specification:

DEFINE
{
   const integer OK_END = 0;
   const integer SLEEP_TIME = 3.8;      // An attempt has been made to assign the integer variable the float-type variable. The value is rounded down, with only 3 saves in the variable.
}

In this example, a float-type value is assigned to the SLEEP_TIME variable of type integer. The assigned value is rounded down, with only the integer-type value saved in the SLEEP_TIME variable.

Example of valid specification:

DEFINE
{
   const integer OK_END =0;
   const float SLEEP_TIME = 3.8;      // The variable type has been changed to the float type.
}

The data type of the SLEEP_TIME variable has been changed from integer to float to hold a float-type value.

AITCW-0017

Unsafe use of boolean variable for processing.

Cause

If you have specified a bool-type variable in an unexpected way, this warning message is displayed. For example, if you have specified a bool-type variable for a divisional or remainder operation (/ or %), this leads to division by 0 or 0/0 contradiction, and this warning message will be displayed.

Action

In such a case, do not specify any variables of type bool.

Example

Example of invalid specification:

DEFINE
{
   const integer sloop_max = 30;
   integer sloop_count;
   bool IsPathSet = false;
}
MAIN
{
   sloop_count = sloop_max / IsPathSet;      // The Boolean variable is specified as the divisor.
}

If a bool-type variable has been used, this leads to a division by 0, and this warning message will be displayed. In this example, the IsPathSet variable of type bool is specified as the divisor, leading to a division by 0.

Example of valid specification:

DEFINE
{
   integer NG_END = 1;
   const integer sloop_max = 30;
   integer sloop_count;
}
MAIN
{
   sloop_count = sloop_max / NG_END;     // The Boolean variable has been deleted, and the integer-type variable has been specified as the divisor.
}

The IsPathSet variable of type bool has been deleted, and the NG_END variable of type integer has been specified as the divisor.

AITCW-0028

Unsafe mix of type data-type-1 and type data-type-2 in operation operator.

Cause

A mixture of integer and bool types is specified in such as bitwise logical AND and OR operations.

Action

For the indicated operand, make sure that the data types of the expressions are consistent.

Example

Example of invalid specification:

DEFINE
{
   integer sloop_max = 0;
   bool IsPathSet;
}
MAIN
{
   sloop_max = sloop_max & IsPathSet;      // The integer and bool types are specified for bit logical AND.
}

In this example, the integer and bool types are specified for the AND operation, with data types mixed.

Example of valid specification:

DEFINE
{
   integer sloop_max = 0;
   integer sloop_count;
}
MAIN
{
   sloop_max = sloop_max & sloop_count;      // Integer types have been specified for bit logical AND.
}

The operands of the & operator have the same data type integer.

AITCW-0033

Switch statement contains only default label.

Cause

The switch statement contains only a default case label, and contains no case labels. This is equivalent to a statement sequence error.

Action

Specify at least one case label in the switch statement.

Example

Example of invalid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(FileVersion)
      default:      // Only the default label is used in the switch statement.
         :
         :
         break;
   endswitch;
}

All switch statements require at least one case label. In this example, however, the case statement does not exist, with only the default statement specified.

Example of valid specification:

DEFINE
{
   const string FileVersion = "7.1";
   string stMsgText;
}
MAIN
{
   switch(Version )
      case "7.1":      // The switch statement contains the case statement.
         ...
         ...
         break;
      default:
         ...
         ...
         break;
   endswitch;
}

A case statement has been added to the switch statement.

AITCW-0035

label-name: Unreferenced label.

Cause

The indicated label has been defined but has not been referenced. It is ignored.

Action

Specify a goto statement that references the label name.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   integer sloop_max = 0;
}
MAIN
{
   if (ExeVersion == FileVersion )
ErrorLabel:   // The goto statement associated with the label does not exist.
      AIT_LogMessage("Setup(English)For Windows-Start");
      if (AIT_FileExists("#setup.exe") == 0)
         sloop_max = 0;
      endif;
   endif;
}

The label requires the associated goto statement. If you have specified a label statement with no goto statement, the label statement is ignored. In this example, label ErrorLabel is specified with no goto statement.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   integer sloop_max = 0;
}
MAIN
{
   if (ExeVersion == FileVersion)
      AIT_LogMessage("Setup(English)For Windows-Start");
      if (AIT_FileExists("#setup.exe") == 0)
         goto ErrorLabel;      // The goto statement has been specified.
         sloop_max = 0;
      endif;
ErrorLabel:      // The label is defined.
      stMsgText = "Setup(English) " + InstallerName + " Not Found";
      AIT_LogMessage(stMsgText);
   endif;
}

The goto statement associated with the label ErrorLabel has been specified.

Another means is to delete unnecessary label statements.

AITCW-0036

variable name: Unreferenced variable.

Cause

The variable defined in the DEFINE section is not referenced.

Action

Delete defines variables that are unnecessary or not used.

Example

Example of invalid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   integer sloop_max;      // This variable is not referenced from anywhere in the program.
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      AIT_LogMessage("Setup(English)For Windows-Start");
      if (AIT_FileExists("#setup.exe") == 0)
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
      endif;
   endif;
}

In this example, the sloop_max variable is defined in the DEFINE section, but is not used in the MAIN section.

Example of valid specification:

DEFINE
{
   const string ExeVersion = "7.1";
   const string FileVersion = "7.1";
   integer sloop_max;
   string stMsgText;
}
MAIN
{
   if (ExeVersion == FileVersion)
      AIT_LogMessage("Setup(English)For Windows-Start");
      if (AIT_FileExists("#setup.exe") == 0)
         sloop_max = 0;// Variable sloop_max is used.
         stMsgText = "Setup(English) " + InstallerName + " Not Found";
         AIT_LogMessage(stMsgText);
      endif;
   endif;
}

The sloop_max variable is used in the MAIN section.

Another means is to delete variables unnecessary in the MAIN section from the DEFINE section.

Appendixes

A. Notes on Using JP1/IT Desktop Management 2 - Agent

This appendix provides points to be noted when JP1/IT Desktop Management 2 - Agent is installed on a computer running Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2.

A.1 Notes that apply to the manager

This section provides cautionary notes that apply to the manager side when JP1/IT Desktop Management 2 - Agent is installed on a computer running Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2.

Jobs that attempt to modify the registry or a file that is protected by Windows Resource Protection result in an error.

Do not assign symbolic links, hard links, or junctions to the following files and directories:

Installation directories specified during packaging or remote installation

Directories and files targeted for remote collection

If a symbolic link, hard link, or junction is assigned to any of these files and directories, that file or directory cannot be used in processing that relates to packaging, remote installation, or remote collection.

A.2 Notes that apply to managed computers

This section provides cautionary notes that apply to managed computers when JP1/IT Desktop Management 2 - Agent is installed on a computer running Windows Server 2022, Windows 11, Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows 7, or Windows Server 2008 R2.

For cautionary notes that apply to JP1/IT Desktop Management 2 - Agent in general, see 1.7.2 Notes on installing software manually.

Windows 11, Windows 10, Windows 8.1, and Windows 8 allow you to disable startup programs from Task Manager, but you must not disable any programs registered on JP1/IT Desktop Management 2 - Agent under any circumstances.

When you perform any of the operations below, the User Account Control dialog box appears. To go ahead with the operation, allow the program to execute. To prevent the operation from taking place, cancel execution of the program.

Install the agent software

Start agent setup#

Start Packager#

#

If the user who initiates the operation does not have administrator permission for the operating system, elevate the user to administrator level before proceeding.

If the display language is Japanese, characters that cannot be converted to Shift-JIS codes are displayed or entered as one or two question marks (?). Similarly, if the display language is Chinese, characters that cannot be converted to GBK codes are displayed or entered as one or two question marks (?).

You cannot use Fast User Switching feature as a way for multiple users to run instances of the JP1/IT Desktop Management 2 - Agent application at the same time.

B. Outputting Audit Logs Related to Distribution by Using Remote Install Manager

This appendix describes the information that is output to the audit log.

B.1 Events for which information is output to audit logs

The table below shows the types of events for which information is output to the audit log, and the timing with which JP1/IT Desktop Management 2 outputs the information. An event type is an identifier used to classify events output to the audit log.

Table B‒1: Types of events output to the audit log

Event type

Description

Timing of output by JP1/IT Desktop Management 2

StartStop

Indicates that software has started or shut down.

When a program with a GUI starts or stops

Authentication

An event indicating that authentication of an administrator succeeded or failed.

When authentication takes place in a program with a GUI

ContentAccess

Indicates that an attempt was made to access a file, registry entry, or database data managed by JP1/IT Desktop Management 2, and the attempt succeeded or failed.

When a job is executed and its execution results notified

When a command is executed and its execution results notified

B.2 Storage format of audit log information

The following describes the way in which audit log information is stored.

The latest audit log information is output to the file NETMAuditManager.LOG. When this log file reaches a certain size, it is renamed NETMAuditManagern.LOG. A new log file is created with the same name as the original, and new log information is written to this file. Specifically, when NETMAuditManager.LOG reaches a certain size, it is renamed NETMAuditManager1.LOG and saved. A new NETMAuditManager.LOG file is then created, and new log information is written into this file. When this new NETMAuditManager.LOG file reaches a certain size, the existing NETMAuditManager1.LOG file is renamed NETMAuditManager2.LOG, and NETMAuditManager.LOG is renamed NETMAuditManager1.LOG. The maximum value of n is 9.

In this way, each time a new log file is created, the number at the end of the old file name is incremented by 1. This means that a file with a higher number is an older file. When the number of saved files exceeds nine, the oldest log file is deleted.

B.3 Output format of audit log information

The following describes the output format, output destination, and output items of an audit log entry. Also shown is an example of audit log output.

(1) Audit log output format

An audit log entry consists of the string CALFHM indicating the information is formatted as an audit log, followed by the revision number of the audit log, and finally the relevant output items.

The following figure shows the output format of audit log information.

Figure B‒1: Audit log output format

(2) Audit log output destination

Audit log information is output to the following directory:

Audit log output destination:

JP1/IT-Desktop-Management 2 - Manager-installation-directory\mgr\log

(3) Output items

The items in an audit log fall into the following two categories:

Common output items

Items common to all JP1 products that output audit log data.

Fixed output items

Optional items each JP1 product can output as audit log data.

(a) Common output items

The following table lists the values output as common output items, and describes each item.

Table B‒2: Common output items in audit logs

No.

Output item

Value

Description

Item name

Output attribute name

1

Common specification identifier

--

CALFHM

An ID indicating that the information is formatted as an audit log.

2

Common specification revision number

--

1.0

The revision number used to manage the audit log.

3

Sequence number

seqnum

sequence-number

The sequence number of the audit log entry.

4

Message ID

msgid

message-ID

The message ID of the product.

5

Date and time

date

YYYY-MM-DDThh:mm:ss.sssTZD#

The date and time at which the audit log was acquired, and the time zone.

6

Generated program name

progid

JP1ITDM2

The name of the program that generated the event.

7

Generated component name

compid

DistributionManager

The following commands and functions can generate audit log entries:

Menu items in the JP1_IT Desktop Management 2 - Manager or JP1_IT Desktop Management 2 - Agent folder:

Remote Install Manager

Unarchiver

Packager

Commands:

Dcmcoll

Collect files

Dcmgpmnt

Apply policies to host groups as a batch

Dcminst

Create and execute jobs

Dcmjbrm

Delete jobs

Dcmjexe

Execute a job

Dcmpack

Execute packaging

Dcmpkget

Back up a package

Dcmpkput

Restore packages from a backup

Dcmpkrm

Delete a package

Dcmrmgen

Delete a job definition

Dcmrtry

Re-execute a job

Dcmstat

Acquire the execution status of a job

Dcmstsw

Monitor the execution status of a job

Dcmsusp

Suspend and resume file transfer

The name of the function that generated the event.

8

Generated process ID

pid

process-ID

The ID of the process where the event occurred.

9

Generated location

ocp:host

host-name

The host name of the host where the event occurred.

If the host name could not be acquired, a hyphen (-) is output.

10

Event type

ctgry

StartStop

Authentication

ContentAccess

The category to which the event output to the audit log belongs.

11

Event result

result

Success

The event was successful

Failure

The event was a failure

Occurrence

An event occurred (other than success or failure)

The result of the event.

12

Subject identification information

subj:uid

The user account or Administrator

Information about the user associated with the event.

subj:pid

process-ID

Information about the process that caused the event

Legend:

--: No attribute name is output.

#

YYYY represents the year, MM the month, DD the day, hh the hour, mm the minutes, ss the seconds, and sss the milliseconds.

T is the delimiter between the date and time.

TZD specifies the time zone. One of the following is output:

+hh:mm: Indicates a time zone hh:mm ahead of UTC.

-hh:mm: Indicates a time zone hh:mm behind UTC.

Z: Indicates a time zone equivalent to UTC.

(b) Fixed output items

The following table lists the values output as fixed output items, and describes each item.

Table B‒3: Fixed output items in audit logs

No.

Output item

Value

Description

Item name

Output attribute name

1

Action information

op

Regist

Package registration

Execute

Execution of an Install package job or Send package, allow client users to choose job

Information about the user operation that caused the event to occur.

Information is not output for operations that do not correspond to these values.

2

Free description

msg

Any message

A message describing the event.

(4) Example of audit log output

The following shows an example of the audit log data output in the process of starting Remote Install Manager in JP1/IT Desktop Management 2 - Manager and creating a host.

In this example, a host was created by the following procedure:

Start Remote Install Manager.

Perform user authentication.

Execute a job to create a new host.

Exit Remote Install Manager.

The audit log data output during this process is as follows:

Figure B‒2: Audit log data

B.4 Configuration for outputting audit logs

The following describes the settings required to output audit log data. If you are using the Manager and Packager on different PCs, you must also configure audit log output in Packager.

Configuration during setup

Set the log output level on the Audit Log page of the Setup for Distribution by Using Remote Install Manager window during the setup process.

Configuration in Packager

In the JP1/ITDM2 Packager window, from the Options menu, select Customize default settings. The Customize Default Settings dialog box appears. On the Audit Log page, select the Output audit logs check box.

For details about how to use the Audit Log page, see 7.2.14(4) Audit Log page.

C. List of Menus

This appendix lists the menus displayed in each window and icon in JP1/IT Desktop Management 2.

C.1 List of System Configuration window menus

The following table lists the menus in the System Configuration window.

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the System Configuration window.

--

Create Host

Creates a host.

Create Host

Rename

Renames a host.

--

Properties

Displays the properties of the selected host.

XXX Properties (where XXX is a host name or IP address)

Change Attributes

Changes host attributes.

Change Attributes

Register/Delete ID Group on ID-management Relay Computer

Registers and deletes ID groups for individual ID-management relay computers.

Register/Delete ID Group on ID-management Relay Computer

Deletion History of System Configuration Information

Displays the history of host deletion from system configuration information.

Deletion History of System Configuration Information

Create from File

Creates a system configuration from a file.

Create System Configuration#1

Save to File

Outputs the system configuration to a file.

Save System Configuration

Print Setup

Defines which information is to be printed.

Print Setup

Print Preview

Displays a print preview.

Print Setup

Print

Prints system configuration information.

Print Setup

Printer Setup

Specifies which printer to use.

--

Output to CSV File

Outputs information managed on the managing system to a file in CSV format.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Cut

Cuts the selected host.

--

Copy

Copies the selected host.

--

Paste

Pastes the host to the selected location.

--

Delete

Deletes a host from the system configuration.

--

Delete Installed Package Information

Deletes information about the software installed on the host.

Delete Installed Package Information

Delete Packages from Relay Computer

Deletes packages from the relay system or management relay server.

Delete Packages from Relay Computer

Select All

Selects all information displayed in the right pane of the window.

--

Invert Selection

Inverts the selection in the right pane of the window.

--

Execute

Execute Job

Creates a new job.

Define New Job

Suspend/Resume File Transfer

Suspend

Suspends file transfer to and from lower systems.

Suspend File Transfer

Resume

Resumes file transfer to lower systems.

Resume File Transfer

View

Select Information

List

Displays a list of destinations.

--

Attributes

Displays host attributes.

--

Installed Packages

Displays information about installed packages.

--

Shift Information

Switches tabs.

--

Set Display

Sets the items to be displayed.

Set Display

Filter Software

User program and data

Displays information about software whose package type is set to User program and data.

--

Hitachi program products

Displays information about software whose package type is set to Hitachi program products.

--

Other companies' software

Displays information about software whose package type is set to Other companies' software.

--

Patch Information

Displays information about patches that packaged by the UNIX-version Packager.

--

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Arrange by Name

Sorts information by name.

--

Arrange by ID

Sorts information by ID.

--

Arrange by Date

Sorts information by date.

--

Options

Find

Searches for hosts.

Find

Job

Sets a monitoring time for job execution statuses.

Job Environment

Arrangement Pattern

Sets the window layout.

Arrangement Pattern

Auto Host Group/ID Maintenance#2

--

--

Start Remote Control#3

Starts remote control.

--

Start Tools

Register Tool

Registers tools to be started from Remote Install Manager.

Tool Registration

tool-name#4

Starts a registered tool.

--

Window

Cascade

Displays open windows in a cascading arrangement.

--

Tile

Displays open windows in a tiled arrangement.

--

Refresh

Refreshes the window contents.

--

Arrange Windows

Arranges the windows according to the specified layout.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

#1

If there is a destination or system configuration displayed, a window appears in which you can save the destination or system configuration before creating the new system configuration.

#2

This window is always unavailable.

#3

Available when a controller is installed.

#4

Displays the registered tool names. A maximum of 10 tools are displayed.

C.2 List of Destination window menus

The following table lists the menus in the Destination window.

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the Destination window.

--

Create Destination

Creates a destination.

Create Destination

Create Host Group

Configures host groups and host group policies.

Create Host Group

Rename

Renames a host group.

--

Properties

Displays the properties of the selected host group.

XXX Properties (where XXX is a host name, IP address, or host group name)

Create ID Group

Creates an ID group.

Create ID Group

Delete ID Group

Deletes the selected ID group.

Delete ID Group

Change ID Group Attribute

Changes the relay system that manages the ID group.

Change ID Group Attribute

Use File for ID Registration

Use a file to register multiple hosts in a ID group as a batch.

Register in ID Group

Save ID Hosts to File

Saves an ID group and hosts that are registered in the ID group to a file.

Save ID Group Member

Deletion History of System Configuration Information

Displays the history of host deletion from system configuration information.

Deletion History of System Configuration Information

Create from File

Creates a host group from a file containing a host group configuration.

Create Destination#1

Add from File

Adds a host group from a file containing a host group configuration.

Add Destination

Save to File

Creates a file from a host group.

Save Destination

Print Setup

Defines which information is to be printed.

Print Setup

Print Preview

Displays a print preview.

Print Setup

Print

Prints destination information.

Print Setup

Printer Setup

Specifies which printer to use.

--

Output to CSV File

Outputs information managed on the managing system to a file in CSV format.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Cut

Cuts the selected host.

--

Copy

Copies the selected host.

--

Paste

Pastes the host to the selected location.

--

Delete

Deletes a host and host group from the destination.

--

Delete Installed Package Information

Deletes information about the software installed on the host.

Delete Installed Package Information

Select All

Selects all information displayed in the right pane of the window.

--

Invert Selection

Inverts the selection in the right pane of the window.

--

Execute

Execute Job

Creates a new job.

Define New Job

Suspend/Resume File Transfer

Suspend

Suspends file transfer to and from lower systems.

Suspend File Transfer

Resume

Resumes file transfer to and from lower systems.

Resume File Transfer

View

Select Information

List

Displays a list of destinations.

--

Attributes

Displays host attributes.

--

Installed Packages

Displays information about installed packages.

--

ID-management Relay Computer

Displays the relay system or management relay server that is managing the ID group.

--

Shift Information

Switches tabs.

--

Set Display

Sets the items to be displayed.

--

Filter Software

User program and data

Displays information about software whose package type is set to User program and data.

--

Hitachi program products

Displays information about software whose package type is set to Hitachi program products.

--

Other companies' software

Displays information about software whose package type is set to Other companies' software.

--

Patch Information

Displays information about patches that packaged by the UNIX-version Packager.

--

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Arrange by Name

Sorts information by name.

--

Arrange by ID

Sorts information by ID.

--

Arrange by Date

Sorts information by date.

--

Double-click ID to Show Destinations

Destinations under an ID group only appear in the right window when you double-click the ID. This option is useful when there are 10,000 or more destinations under an ID group and there is no need to view the destinations under the ID group. When this option is enabled, a single click does not show the destinations.

--

ID Group Members

Displays information about the destination under the selected ID group.

ID Agent Information

Options

Find

Searches for hosts.

Find

Job

Sets a monitoring time for job execution statuses.

Job Environment

Arrangement Pattern

Sets the window layout.

Arrangement Pattern

Auto Host Group/ID Maintenance#2

Displays a window in which you can edit the policies of host groups and ID groups.

Policy Setup

Start Remote Control#3

Starts remote control.

--

Start Tools

Register Tool

Registers tools to be started from Remote Install Manager.

Tool Registration

tool-name#4

Starts a registered tool.

--

Window

Cascade

Displays open windows in a cascading arrangement.

--

Tile

Displays open windows in a tiled arrangement.

--

Refresh

Refreshes the window contents.

--

Arrange Windows

Arranges the windows according to the specified layout.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

#1

If a destination is displayed, a window appears in which you can save the destination.

#2

This window is always unavailable.

#3

Available when a controller is installed.

#4

Displays the registered tool names. A maximum of 10 tools are displayed.

C.3 List of Package window menus

The following table lists the menus in the Package window.

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the Package window.

--

Create Cabinet

Creates a cabinet.

Create Cabinet

Rename

Renames a cabinet.

Rename Cabinet

Properties

Displays information about the selected cabinet or package.

XXX Properties (where XXX is a cabinet name or package name)

Offline Machine Management

Creation of Installation Media

Prepares media from which you can install software on an offline machine.

Creation of Installation Media

Deletion History of System Configuration Information

Displays the history of host deletion from system configuration information.

Deletion History of System Configuration Information

Print Setup

Defines which information is to be printed.

Print Setup

Print Preview

Displays a print preview.

Print Setup

Print

Prints package information.

Print Setup

Printer Setup

Specifies which printer to use.

--

Output to CSV File

Outputs information managed on the managing system to a file in CSV format.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Delete

Deletes the selected cabinet or package.

--

Delete Packages from Relay Computer

Deletes packages from the relay system or management relay server.

Delete Packages from Relay Computer

Select All

Selects all information displayed in the right pane of the window.

--

Invert Selection

Inverts the selection in the right pane of the window.

--

Execute

Execute Job

Creates a new job.

Define New Job

Suspend/Resume File Transfer

Suspend

Suspends file transfer to and from lower systems.

Suspend File Transfer

Resume

Resumes file transfer to and from lower systems.

Resume File Transfer

View

Select Information

List

Displays a list of packages.

--

Attributes

Displays package attributes.

--

Package Contents

Displays the package contents.

--

Shift Information

Switches tabs.

--

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Arrange by Name

Sorts information by name.

--

Arrange by ID

Sorts information by ID.

--

Arrange by Version

Sorts information by version.

--

Arrange by Generation

Sorts information by generation number.

--

Arrange by Date

Sorts information by date.

--

Arrange by Size

Sorts information by size.

--

Arrange by Update Date/Time

Sorts information by when it was last updated.

--

Options

Job

Sets a monitoring time for job execution statuses.

Job Environment

Arrange Pattern

Sets the window layout.

Arrangement Pattern

Window

Cascade

Displays open windows in a cascading arrangement.

--

Tile

Displays open windows in a tiled arrangement.

--

Refresh

Refreshes the window contents.

--

Arrange Windows

Arranges the windows according to the specified layout.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.4 List of Job Definition window menus

The following table lists the menus in the Job Definition window.

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the Job Definition window.

--

Create Folder

Creates a folder.

Create Folder

Create Job

Creates a new job.

Define New Job

Rename

Renames a folder or job.

--

Deletion History of System Configuration Information

Displays the history of host deletion from system configuration information.

Deletion History of System Configuration Information

Output to CSV File

Outputs information managed on the managing system to a file in CSV format.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Modify

Changes the definition of a job.

Edit Job

Delete

Deletes the selected folder or job.

--

Customize

Displays a window in which you can customize the dialog box used to define jobs.

Customize the Define New Job Dialog Box

Select All

Selects all information displayed in the right pane of the window.

--

Invert Selection

Inverts the selection in the right pane of the window.

--

Execute

Execute Job

Executes a saved job.

Under Job Registration

Suspend/Resume File Transfer

Suspend

Suspends file transfer to and from lower systems.

Suspend File Transfer

Resume

Resumes file transfer to and from lower systems.

Resume File Transfer

View

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Name Only

Shows only the names of jobs.

--

All

Shows all job information.

--

Set Display

Sets the items to be displayed.

Set Display

Arrange by Name

Sorts information by name.

--

Arrange by Creation date

Sorts information by creation date.

--

Arrange by Update date

Sorts information by when it was last updated.

--

Options

Job

Sets a monitoring time for job execution statuses.

Job Environment

Arrangement Pattern

Sets the window layout.

Arrangement Pattern

Window

Cascade

Displays open windows in a cascading arrangement.

--

Tile

Displays open windows in a tiled arrangement.

--

Refresh

Refreshes the window contents.

--

Arrange Windows

Arranges the windows according to the specified layout.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.5 List of Job Status window menus

The following table lists the menus in the Job Status window.

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the Job Status window.

--

Deletion History of System Configuration Information

Displays the history of host deletion from system configuration information.

Deletion History of System Configuration Information

Print Setup

Defines which information is to be printed.

Print Setup

Print Preview

Displays a print preview.

Print Setup

Print

Prints job status information.

Print Setup

Printer Setup

Specifies which printer to use.

--

Output to CSV File

Outputs information managed on the managing system to a file in CSV format.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Delete

Deletes the selected folders and jobs.

--

Select All

Selects all folders and jobs.

--

Invert Selection

Inverts the selection in the right pane of the window.

--

Execute

Re-execute Job

Re-executes the job.

Job Retry

Forcibly Complete Split Distribution

Changes the mode from split distribution to normal distribution, and transfers the remainder of the package in a single transfer.

Confirm Forced Completion

Suspend/Resume File Transfer

Suspend

Suspends file transfer to and from lower systems.

Suspend File Transfer

Resume

Resumes file transfer to and from lower systems.

Resume File Transfer

View

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Set Display

Sets the time period for which to display information.

Set Display

View Detailed Information

Displays detailed information about the selected job.

Details

Specified Information Only

Limits the displayed information to that of a specific tier.

--

All Jobs

Displays all jobs under the selected tier.

--

All Job Details

Displays detailed information for all jobs under the selected tier.

--

All Job Types

If you applied a filter that displays jobs with a specific status, click this menu item to display jobs of all statuses.

--

Filter

Displays jobs with a specific status.

Filter

View ID Job Agents

Displays the status of jobs for which an ID group is specified as the destination.

--

Jobs being Deleted

Displays jobs that are being deleted from relay systems, management relay servers, or agents.

--

Arrange

Changes the order in which information is displayed.

Sort Order

Options

Job

Sets a monitoring time for job execution statuses.

Job Environment

Arrangement Pattern

Sets the window layout.

Arrangement Pattern

Window

Cascade

Displays open windows in a cascading arrangement.

--

Tile

Displays open windows in a tiled arrangement.

--

Refresh

Refreshes the window contents.

--

Arrange Windows

Arranges the windows according to the specified layout.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.6 List of Software Information window menus

The following table lists the menus in the List of Software Information window:

Menu

Function

Displayed dialog box

File

New

System Configuration

Displays the System Configuration window.

--

Destination

Displays the Destination window.

--

Package

Displays the Package window.

--

Job Definition

Displays the Job Definition window.

--

Job Status

Displays the Job Status window.

--

List of Software Information

Displays the List of Software Information window.

--

Close

Closes the List of Software Information window.

--

Create Search List

Creates a search list.

Software Search List

Rename

Renames a search list.

Rename Search List

Create from File

Creates a search list from a search list file (*.DMP).

Read Search List

Save to File

Creates a search list file (*.DMP).

Save Search List

Deletion History of System Configuration Information

Displays the history of hosts deleted from the system configuration information.

Deletion History of System Configuration Information

Printer Setup

Sets up the printer to be used.

--

Output to CSV File

Outputs information managed by the managing server to a CSV file.

CSV File Output

Exit

Closes Remote Install Manager.

--

Edit

Edit

Edits the selected search list.

Software Search List

Delete

Deletes the selected search list.

--

View

Toolbar

Switches between showing and hiding the toolbar.

--

Status Bar

Switches between showing and hiding the status bar.

--

Window

Cascade

Cascades all open windows.

--

Tile

Tiles all open windows horizontally.

--

Arrange Windows

Arranges windows according to a specified layout.

--

Arrange Icons

Arranges minimized windows as icons.

--

Help

Version

Displays version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.7 List of IT Desktop Management 2 Unarchiver window menus

The following table lists the menus in the IT Desktop Management 2 Unarchiver window.

Menu

Function

Displayed dialog box

File

Restore File

Restores an archived or compressed file to its original form.

Restore

Exit Unarchiver

Exits the Unarchiver.

--

Disk

Change Drive

Changes the drive. Use this menu command when the file you want to restore is on another drive.

Select Drive

View

By File Type

Displays only files with a specific extension.

Display File Type

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Font

Changes the font used in the window.

Font

Help

Version (DMUNARC)

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.8 List of JP1/ITDM2 Packager window menus

The following tables list the menus in the three sub-windows of the JP1/ITDM2 Packager window.

(1) Package window

Menu

Function

Displayed dialog box

File

Properties

Displays the properties of the selected cabinet or package.

XXX Properties (where XXX is a cabinet name or package name)

Exit

Exits the Packager.

--

Edit

Delete

Deletes the selected package from the cabinet.

--

View

Items to View

Cabinet/Package

Displays a list of cabinets or packages.

--

Package Attribute

Displays the attributes of cabinets or packages.

--

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Arrange By Name

Sorts the list of cabinets or packages by name.

--

Arrange By ID

Sorts the list of cabinets or packages by package ID.

--

Arrange By Version

Sorts the list of cabinets or packages by version.

--

Arrange By Generation

Sorts date list of cabinets or packages by generation number.

--

Arrange By Creation Date

Sorts the list of cabinets or packages by date.

--

Options

Customize default settings

Configures the environment for packaging, and the default values that appear in the JP1/ITDM2 Packaging dialog box.

Customize Default Settings

Window

Cascade

Arranges the subwindows in a cascading pattern.

--

Tile

Arranges the subwindows in a tiled pattern.

--

Arrange Icons

Arranges the icons of minimized windows.

--

View Current Drive

Displays a new View Current Drive window.

--

Refresh

Refreshes the window contents.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

(2) File window

Menu

Function

Displayed dialog box

File

Exit

Exits the Packager.

--

Disk

Drive

Displays the drive that contains the files you are packaging.

--

Run

Packaging

Packages software.

JP1/ITDM2 Packaging

View

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Arrange By Name

Sorts the displayed files by name.

--

Arrange By Size

Sorts the displayed files by size.

--

Arrange By Creation Date

Sorts the displayed files by date.

--

Set Conditions

Displays the Set Conditions dialog box.

--

Options

Customize default settings

Configures the environment for packaging, and the default values that appear in the JP1/ITDM2 Packaging dialog box.

Customize Default Settings

Window

Cascade

Arranges the subwindows in a cascading pattern.

--

Tile

Arranges the subwindows in a tiled pattern.

--

Arrange Icons

Arranges the icons of minimized windows.

--

View Current Drive

Displays a new View Current Drive window.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

(3) Package Status window

Menu

Function

Displayed dialog box

File

Exit

Exits the Packager.

--

View

Toolbar

Shows or hides the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Options

Customize default settings

Configures the environment for packaging, and the default values that appear in the JP1/ITDM2 Packaging dialog box.

Customize Default Settings

Window

Cascade

Arranges the subwindows in a cascading pattern.

--

Tile

Arranges the subwindows in a tiled pattern.

--

Arrange Icons

Arranges the icons of minimized windows.

--

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.9 List of Package Setup Manager window menus

The following table lists the menus in windows accessible from the Package Setup Manager window.

(1) Package window

Menu

Function

Displayed dialog box

File

Exit

Exits Package Setup Manager.

--

Edit

Change Installation Path

Changes the directory in which the selected package is to be installed.

Change Installation Path

Execute

Install

Installs the selected package.

Specify Installation Method

Settings

Connect to Higher System at Startup

When you select this option, Package Setup Manager acquires information from higher systems at startup.

--

View

Details

Displays detailed information about the selected package.

Package Details

Refresh

Refreshes the window so that the Package Setup Manager window displays the latest packages you have permission to install.

--

Toolbar

Standard Buttons

Displays standard size buttons on the toolbar.

--

Large Buttons

Displays large buttons on the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Columns

Version

Select this option to display a Version column.

--

Size

Select this option to display a Size column.

--

Creation Date

Select this option to display a Creation Date column.

--

By Package Name

By Installation Status

Select this option to display uninstalled packages first in the list.

--

By Name

Select this option to sort packages by name regardless of their status.

--

By Version

Select this option to sort the packages by version.

--

By Size

Select this option to sort the packages by size.

--

By Date

Select this option to sort the packages by their creation date.

--

Installed Software Window

Displays the Installed Package window.

--

font

Changes the font used in the window.

Font

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

(2) Installed Package window

Menu

Function

Displayed dialog box

File

Exit

Exits Package Setup Manager.

--

Edit

Delete Installed Package Information

Deletes the selected package from the list.

--

View

Refresh

Refreshes the window so that the Package Setup Manager window displays the latest information about packages installed on the managed computer.

--

Columns

Package ID

Select this option to display a Package ID column.

--

Version

Select this option to display a Version column.

--

Generation

Select this option to display a Generation column.

--

Installation Date

Select this option to display a Installation Date column.

--

Installation Path

Select this option to display a Installation Path column.

--

Toolbar

Standard Buttons

Displays standard size buttons on the toolbar.

--

Large Buttons

Displays large buttons on the toolbar.

--

Status Bar

Shows or hides the status bar.

--

Package window

Displays the Package window.

--

Font

Changes the font used in the window.

Font

Help

Version

Displays the version information for JP1/IT Desktop Management 2.

--

Legend:

--: Not displayed.

C.10 Automatic Installation Tool window menus

Table C-1 lists the menus available in the Automatic Installation Tool window.

Table C‒1: Menus available in the Automatic Installation Tool window

Menu

Description

Shortcut

File

New

Creates a new AIT file.

Ctrl+N

Open

Opens an existing AIT file.

Ctrl+O

Close

Closes the active AIT file.

-

Save

Saves the active AIT file.

Ctrl+S

Save As

Saves the active AIT file under a new filename.

-

Save All

Saves all the changed AIT files on the window.

-

Print

Prints the active AIT file.

Ctrl+P

Print Preview

Displays the print image of the active AIT file.

-

Print Setup

Displays the Printer Setup dialog box. You can change printer setup.

-

Recent File

Displays a recently used file selected from the list.

-

Exit

Exits the Automatic Installation Tool.

Alt+F4

Edit

Undo

Cancels the immediately preceding edit operation.

Ctrl+Z

Redo

Redoes the immediately preceding edit operation that was canceled.

Ctrl+Y

Cut

Cuts and pastes a string to the clipboard.

Ctrl+X

Copy

Copies and pastes a string to the clipboard.

Ctrl+C

Paste

Pastes a string to the clipboard.

Ctrl+V

Delete

Deletes a selected string.

Delete

Select All

Selects all AIT files.

Ctrl+A

Find

Displays the Find dialog box to find a specified string.

Ctrl+F

Find Next

Continues to find a string in the AIT file following the cursor position.

F3

Find Previous

Continues to find a string in the AIT file preceding the cursor position.

Shift+F3

Replace

Displays the Replace dialog box to replace the found string with a specified string. You can specify the normal expression for a found string.

Ctrl+H

Go To

Displays the Go To dialog box to move the cursor to a specified line.

Ctrl+G

View

Toolbar

Selects the display or non-display of the tool bars below.

Standard tool bar

Build tool bar

Utility tool bar

Displays the Customize dialog box, which allows tool bars and commands to be arranged.

-

Status Bar

Selects the display or non-display of the status bar.

-

Output

Displays the output window.

Alt+F2

Watch

Displays the Watch window during debugging.

Alt+F3

Workbook

WorkBook Mode

Selects the display or non-display of workbook mode during an active file view.

Toggle Icons

Selects the display or non-display of the file workbook tab icon during a workbook mode view.

-

Build

Syntax Check

Checks the syntax of the active AIT file, displaying warning and error messages in the output window.

Ctrl+F7

Execute

Checks the syntax of the active AIT file before the start of execution.

Ctrl+F5

Debug

Go

Executes the AIT file from the current statement to the breakpoint.

F5

Stop Debugging

Terminates debugging to return to normal edit mode.

Shift+F5

Step by Step

Executes only the current statement in the AIT file.

F10

Run to Cursor

Stops execution of the AIT file before the cursor line as if a temporary breakpoint were set in the cursor line.

Ctrl+F10

Add/Remove Breakpoint

Allows you to add or remove a breakpoint at a specified position.

F9

Breakpoints Setup

Displays the Breakpoints Setup dialog box that allows you to add or remove a breakpoint.

Alt+F9 or Ctrl+B

Tools

Recorder

Displays the Recorder dialog box used to record user operations for automatic AIT file generation.

Ctrl+R

Window Properties

Displays the Window Properties dialog box that allows you to attributes of a specified window or control.

Ctrl+W

Package Information

Displays the Package Information dialog box used to generate the PACKAGE_INFO section.

Ctrl+P

Options

Displays the Options dialog box that allows you to set an AIT file format, the number of messages to be displayed during a syntax check, the number of generations to be covered by recorder log output, and other items.

Ctrl+O

Customize

Displays the Customize dialog box that allows you to set tool bar and command positions.

Ctrl+C

Window

New Window

Opens a new active AIT file.

Ctrl+N

Cascade

Cascades all opened windows.

Ctrl+C

Tile

Tiles all opened windows.

Ctrl+T

Arrange Icons

Arranges the window icons in the lower line.

Ctrl+A

Close

Closes the active AIT file.

Ctrl+O

Close All

Closes all AIT files.

Ctrl+L

Help

About Automatic Installation Tool

Displays the version of the Automatic Installation Tool.

Ctrl+A

Legend:

-: Not applicable

D. List of Icons

This appendix lists the icons used in the user interface of JP1/IT Desktop Management 2.

D.1 System Configuration window icons

The types of hosts that make up a system include managers, management relay servers, relay systems, and managed computers. Each type is represented by a different icon in the user interface. The manager icon appears at the highest level of the host hierarchy.

The following icons appear in the System Configuration window:

: Manager

: Management relay server

: Relay system

: Computer

D.2 Destination window icons

There are two types of destinations: groups and hosts. Hosts are configured under groups.

The following icons appear in the Destination window:

: Manager

: Management relay server

: Relay system

: Computer

: Host group

: ID group

D.3 Package window icons

In the Package window, the managing server, cabinets, and packages are represented by icons.

The following icons appear in the Package window:

: Managing system host

: Cabinet (for Windows)

: Cabinet (for UNIX)

: Normal package (packaged normally)

: Normal package (in the process of being packaged, or packaging has failed)

D.4 Job Definition window icons

In the Job Definition window, saved jobs are represented by icons.

The following icons appear in the Job Definition window:

: Manager

: Folder

: Job

D.5 Job Status window icons

Job statuses are represented by icons. Each job type and execution status has a different icon.

The following icons appear in the Job Status window:

: Managing system host

: Job target host

: Folder

: ID group job

: Job status (Waiting for transmission)

: Job status (Being executed or execution completed)

: Job status (Timed out)

: Job type (Install package) #

: Job type (Transfer package to relay computer)

: Job type (Batch delete packages on relay computer)

: Job type (Send package, allow client users to choose)

: Job type (Collect files from agent)

: Job type (Remote-collect files from agent to relay computer)

: Job type (Acquire collected files from relay computer)

: Job type (Delete collected files from relay computer)

: Job type (Get system information from computer (UNIX))#

: Job type (Get software information from computer (UNIX))#

: Job type (Get system configuration information)

: Job type (Hold report)

: Job type (Cancel holding of report)

: Job type (Suspend file transfer)

: Job type (Resume file transfer)

#

This job is also applicable to agents for Mac.

D.6 Package Setup Manager window icons

In the Package Setup Manager window, package statuses and types are represented by icons.

(1) Package window

The Package window displays the following icons to represent the status of a package:

: Package permitted to be installed from the managing server (normal package)

: Package that installed normally on the managed computer

: Package that failed to install on the managed computer

(2) Installed Software window

The Installed Software window displays the following icons to represent the package type:

: Hitachi program product

: Other companies' software

: User programs or data

E. Launching Tools from Remote Install Manager

You can register a tool designed for a specific purpose and launch it from Remote Install Manager. When you start the tool, you can use system configuration information for the host selected in Remote Install Manager in arguments of the tool.

For example, if you register a tool that checks the connection status of a host specified by an IP address, Remote Install Manager can automatically pass the IP address of the selected host to an argument of the tool. This means that there is no need to specify an IP address after the tool has started.

You can start registered tools from the Start Tools menu. You can display this menu from the following windows of Remote Install Manager:

System Configuration window

Destination window

Find dialog box

The subsections below describe how to register and start tools in Remote Install Manager, and provide an operation example.

E.1 Registering tools in the Start Tools menu

Before you can start a tool from the Remote Install Manager menu, you must register the tool in the Tool Registration dialog box. In this dialog box, you can also change the parameters of a registered tool and delete registered tools from the menu.

(1) Registering a tool

To register a tool in the Start Tools menu:

From the Option menu in the System Configuration or Destination window, select Start Tools and then Register Tool.

The Tool Registration dialog box appears.

You can also use the following methods to display the Tool Registration dialog box:

Right-click a host in the System Configuration or Destination window, and from the context menu select Start Tools and then Register Tool.

Right-click a host in the Find dialog box, and from the context menu select Start Tools and then Register Tool.

Figure E‒1: Tool Registration dialog box

Set the items in the dialog box.

Each item is described below.

Menu name (required)

Specify the menu name that you want to appear in the Start Tools menu, using no more than 255 single-byte characters (or 127 double-byte characters). Each name must be unique. Each name must be unique.

You can specify a shortcut key for the menu name you are registering by using the menu-name(&X) format. Specify (&X) in single-byte characters. The character specified for X becomes the shortcut key. For example, to register the menu name Connection Checking Tool with R as the shortcut key, specify Connection Checking Tool(&R).

Path name of the tool (required)

Specify the full path of the tool you want to register, using no more than 260 single-byte characters (or 130 double-byte characters). You can enter the full path by clicking the Browse button and navigating to the location of the tool on the drive. In this field, you can also specify a host on the network or the reserved words shown in Table E-1.

In the Path name of the tool field, specify an executable file, such as an .exe file, .bat file, or .cmd file. You cannot start a tool if you specify a .txt file or similar in this field. If you specify a nonexistent or inaccessible file, an error occurs when you attempt to start the tool.

Argument

Specify the value to be passed as the argument during tool startup, using no more than 260 single-byte characters (or 130 double-byte characters). You can pass the system configuration information of the host selected in Remote Install Manager as arguments by specifying reserved words. For details about how to specify reserved words, see E.1(2) Specifying reserved words.

Click Registration.

The tool is added to Menu list with the content you specified. You can register a maximum of 10 tools.

Click OK.

The Tool Registration dialog box closes and the tools displayed in the Menu list area are registered in the Start tools menu. If you click Cancel, the tools are not registered.

(2) Specifying reserved words

To specify a reserved word, you can:

Select system configuration information from the menu displayed when you click Argument.

Enter a text string directly in the text box.

The following table lists the system configuration information that can be passed as arguments, and the corresponding reserved words.

Table E‒1: System configuration information and corresponding reserved words

System configuration information

Reserved word

Format of information passed to tool

Operation Key

$(KEY)

When using host names:

host-name

When using IP addresses:

XXX.XXX.XXX.XXX

Host Name

$(NAME)

host-name

IP Address

$(ADDRESS)

XXX.XXX.XXX.XXX

Host ID

$(HOSTID)

#host-ID

MAC Address

$(MACADDRESS)

MAC-address

Route

$(ROUTE)

\route#

Host Type

$(TYPE)

For a relay system:

MASTER

For a managed computer:

CLIENT

Update Date & Time

$(UPDATE)

YYYYMMDD.hhmmss

Creation Date & Time

$(CRTDATE)

YYYYMMDD.hhmmss

Comment

$(COMMENT)

comment

#: An exclamation mark (!) is used as the delimiter for routes in system configuration information. However, \ is used as the delimiter when the route is passed to a tool. For a host at the top of the route, only \ is passed to the tool.

Notes:

When entering reserved words directly, you must use uppercase letters. For example, $(name) is not recognized as a reserved word.

If the system configuration information contains no value, no value replaces the specified reserved word.

The following example passes a host name, host ID, and MAC address as arguments to a tool:

/n $(NAME) /id $(HOSTID) /mac $(MACADDRESS)

When you specify arguments in this way, the tool is executed as follows:

(3) Changing parameters of registered tools

The following describes how to change the menu name, path name, and argument of a tool registered in the Start Tools menu. Note that you cannot change the parameters of multiple tools at the same time.

In the Menu list area in the Tool Registration dialog box, select the menu item whose parameters you want to change.

The information registered in Menu name, Path name of the tool, and Argument appear.

Change the parameters.

Click Registration.

The changes take effect in the Menu list area.

Click OK.

The Tool Registration dialog box closes and the contents of the Menu list area are applied to the Start Tools menu. If you click Cancel, the change are not applied to the Start Tools menu.

(4) Deleting a registered tool

The following describes how to delete a tool registered in the Start Tools menu. You can also select multiple tools and delete them as a batch.

In the Menu list area in the Tool Registration dialog box, select the tool or tools you want to delete.

Click Delete.

The selected tool or tools are deleted from the Menu list area.

Click OK.

The Tool Registration dialog box closes and the contents of the Menu list area are applied to the Start Tools menu. If you click Cancel, the tools are not deleted.

E.2 Starting tools from the Start Tools menu

To start a tool from the Remote Install Manager menu:

Select a host in the System Configuration window or Destination window, or in the Find dialog box.

You can only start a tool when a host is selected. If you select an ID group or host group together with a host, the tool cannot be started for the ID group or host group. If you start a tool with multiple hosts selected, the tool starts for each of the selected hosts. For example, if you start a tool with 10 hosts selected, the same tool starts 10 times. Note that starting a tool with a large number of hosts selected uses a large amount of memory and might cause the system to become unstable.

From the Options menu or the right-click menu, select Start Tools.

In the Find dialog box, Start Tools only appears in the right-click menu.

Figure E‒2: Starting tools from the System Configuration window

Click the tool you want to start.

The tool you clicked starts. If you specified a reserved word in the Path name of the tool or Argument field, the reserved word is replaced with the system configuration information for the selected host.

E.3 Operation example

The figure below shows an operation example in which a tool starts that pings the host at the IP address given as the argument. The tool is started from Remote Install Manager.

Figure E‒3: Operation example of starting a tool from Remote Install Manager

Register the tool.

In the Tool Registration dialog box, register the PING tool in the menu of Remote Install Manager.

Because this tool uses an IP address as an argument, specify $(ADDRESS) in the Argument field.

Start the tool.

In Remote Install Manager, select the host CLT002 and start the PING tool from the menu.

The IP address 192.168.24.12 is passed from the system configuration information of host CLT002 to the argument used by the tool.

Check the execution results of the tool.

Check the execution result of the PING tool which pings host CLT002 at the IP address 192.168.24.12.

F. Editing a Program Product ID File

The program product ID file generated when an AIT file is created is assigned the name PPDEFAIT.DMP and stored in JP1/IT-Desktop-Management-2-installation-folder\DMPRM. When you edit the generated file, make sure that the file has the format explained below.

The program product ID file contains the information to associate the software you want to distribute with the AIT file you created. You must place the program product ID file in a specified location under the name of PPDEFAIT.DMP.

The format of the program product ID file is:

information-map;package-ID;version;product;AIT-file-full-path;file-name-1;file-name-2;...;file-name-n;

In the program product ID file, the definition of a single software package is specified on one line, which must not exceed 499 bytes. If you want to remotely install multiple programs, define them in multiple lines. The items in a line are delimited by a semicolon (;). The following describes the items. When you perform packaging, package-ID, version, and product defined in the program product ID file are displayed in the JP1/ITDM2 Packaging dialog box. You cannot change them with the dialog box.

information-map (Required)

Specify 000001.

package-ID (Required)

This is the package ID of software you want to distribute. Specify the package ID defined in the AIT file you want to package together with the program.

version (Required)

This is the version of software you want to distribute. Specify the version defined in the AIT file.

product (Required)

This is the package name of software you want to distribute. Specify the package name defined in the AIT file.

AIT-file-full-path (Required)

Specify the full path name of the AIT file including the drive name using a character string consisting of up to 256 bytes.

file-name-1 ... file-name-n (Required)

You can specify one or more file names for identifying the software to be distributed. When all the specified files are found during packaging, JP1/Software Distribution considers the software as an item to be distributed.

The following gives an example of the program product ID file when AIT file AR600.ais is located in C:\ADOBE.

000001;ADOBEREADER;0600;Adobe Reader 6.0;C:\ADOBE\AR600.ais;AdbeRdr60_enu_full.exe;

G. Collecting System and Software Information from Agents for UNIX and Agents for Mac

This appendix describes how to collect system and software information from agents for UNIX and agents for Mac.

G.1 Collecting system information from agents for UNIX and agents for Mac

This section describes how to collect and check system information from agents for UNIX and agents for Mac.

(1) Collecting system information

To collect system information, execute a Get system information from computer (UNIX) job from Remote Install Manager. The following explains the system information collection procedure, focusing on screen transitions.

To collect system information:

In the Job Definition window, select File and then Create Job.

The Define New Job dialog box appears.

In the job type selection list, select Get system information from computer (UNIX) and then click the OK button.

The Create Job dialog box appears.

On the Acquisition Target page, select an applicable option for system information to be collected.

For details about how to set up the Acquisition Target page, see G.1(2) Setting up the Acquisition Target page. The types and setting details of other pages in the dialog box are as follows:

Job page

Specifies the job name. For details about how to set up the Job page, see 10.2.3 Setting up the Job page.

Destination page

Specifies the hosts from which system information is to be collected. You must specify at least one host. For details about how to set up the Destination page, see 10.2.4 Setting up the Destination page.

Schedule page

Specifies the dates and times of jobs to be executed on the managing server and managed computer. For details about how to set up the Schedule page, see 10.2.5 Setting up the Schedule page.

Client Control page

Specifies whether to use the Client Control function. For details about how to set up the Client Control page, see 10.2.6 Setting up the Client Control page.

On the Job page, click the Execute, Save, or Save and Execute button to perform the corresponding action for the job.

The job is saved, executed, or both.

If you save a job, you can re-execute the job when it fails, or you can edit the job to create a new job. We recommend that you save jobs after creating them by clicking the Save or Save and Execute button.

Check the job status.

From the File menu of Remote Install Manager, select New and then Job Status to display the Job Status window.

You can use the Collect_Device_Inventory folder to check the execution statuses of jobs related to system information collection. If you select a job that you executed, the corresponding execution status is displayed in the right pane.

After the job has been completed, check the system information that you received.

Use the JP1/IT Desktop Management 2 device window to check the system information that you received. For details about how to check system information, see G.1(4) Checking received system information.

(2) Setting up the Acquisition Target page

The Acquisition Target page is used to select an option for the system information to be collected from UNIX or Mac computers.

If you want to reduce network traffic during job executions, select Acquire only items modified after the last time that system information was acquired.

Figure G‒1: Acquisition Target page

Acquire all items

Select this option if you want to receive all system information items. You must select this option the first time you perform this task.

Acquire only items modified after the last time that system information was acquired

Select this option if you want to receive only the system information items that have been changed since the last time system information was acquired.

(3) Notes on receiving system information

Note the following when executing a Get system information from computer (UNIX) job:

You might not be able to receive system information correctly, depending on the hardware environment of the agent.

Collecting system information might take time.

(4) Checking received system information

You can use the System Details tab and the Hardware Details tab of the JP1/IT Desktop Management 2 device window to check the system information that you received. To check system information:

In the Device List tab of the device window, select the host whose system information is to be displayed.

Select the System Details tab and the Hardware Details tab at the bottom of the window.

System information appears.

The items to be updated when system information is received depend on the settings of the Acquisition Target page that you specify when creating a job, as below.

If Acquire all items is selected:

All existing information is deleted, and the system information reported from the agent is displayed.

If Acquire only items modified after the last time that system information was acquired is selected:

Only the system information modified since the last time system information was acquired is reported from the agent and reflected in the system information.

Information items that an agent is unable to collect are not reported to the managing server. In this case, these items are not displayed when system information is updated.

G.2 Collecting software information from agents for UNIX and agents for Mac

This section describes how to collect software information from agents for UNIX and agents for Mac.

(1) Collecting software information

To collect software information, execute a Get software information from computer (UNIX)) job from Remote Install Manager. The following explains the software information collection procedure, focusing on screen transitions.

To collect software information:

In the Job Definition window, select File and then Create Job.

The Define New Job dialog box appears.

In the job type selection list, select Get software information from computer (UNIX) and then click the OK button.

The Create Job dialog box appears.

On the Search Target page, specify the software for which software information is to be collected.

For details about how to set up the Search Target page, see G.2(2) Setting up the Search Target page. The types and setting details of other pages in the dialog box are as follows:

Job page

Specifies the job name. For details about how to set up the Job page, see 10.2.3 Setting up the Job page.

Destination page

Specifies the hosts from which software information is to be collected. You must specify at least one host. For details about how to set up the Destination page, see 10.2.4 Setting up the Destination page.

Schedule page

Specifies the dates and times of jobs to be executed on the managing server and managed computer. For details about how to set up the Schedule page, see 10.2.5 Setting up the Schedule page.

Client Control page

Specifies whether to use the Client Control function. For details about how to set up the Client Control page, see 10.2.6 Setting up the Client Control page.

On the Job page, click the Execute, Save, or Save and Execute button to save or execute the job.

The job is saved or executed.

If you save a job, you can re-execute the job when it fails, or you can edit the job to create a new job. We recommend that you save a job (after creating it) by clicking the Save or Save and Execute button.

Check the job status.

From the File menu of Remote Install Manager, select New and then Job Status to display the Job Status window.

If you select a job that you executed, the corresponding execution status is displayed in the right pane.

After the job has been completed, check the software information that you received.

Use the JP1/IT Desktop Management 2 device window to check the software information that you received. For details about how to check software information, see G.2(5) Checking received software information.

(2) Setting up the Search Target page

The Search Target page is used to select the software for which software information is to be collected from UNIX or Mac computers.

Figure G‒2: Search Target page

Software to be searched

Specify the software for which software information is to be collected. You can select either of the following items:

Software installed by remote install

Collects information about the software installed by JP1/IT Desktop Management 2 - Manager.

All software

Collects software information as described below.

Search list

If you specify All software from the Software to be searched drop-down list, you can use software search lists (described below) to search for software installed on UNIX or Mac computers.

To use a software search list, you must select either the search list stored on the manager or the search list stored on the agent.

If you perform searches by using the search list stored on the manager, the specified search list is sent to and stored on the destination agent. If a search list already exists on the agent, it will be overwritten by the sent search list. If you want to perform searches by using the same search list as last time, use the search list stored on the agent.

The default is Search list in the agent.

Search list in the agent

If you select this item, you will use the search list that was saved on the agent when you performed software searches by using a search list last time.

Optional software list

If you select this item, you will use a search list that enables you to optionally register the software to be searched.

You can create multiple optional software lists, such as those prepared for each group or OS of agents where searches are to be performed. If you specify an optional software list directly in the field, you cannot enter the following characters: \ / * " : ! | < > ' . ? single-byte space.

For details about how to create software search lists, see G.2(4) Creating a software search list.

Do not use

Select this item when you want to perform searches without using a search list.

If you perform a job with this item selected, all the search lists stored on the target agent will be deleted.

If you want to use a search list for the next and subsequent searches, perform searches by using the search list stored on the manager.

If software information is collected periodically by using a search list, different information will be collected if a different search list is used. To prevent this problem, we recommend that you customize the Create Job dialog box to set the search list to be used every time to the default.

For details about how to customize the Create Job dialog box, see 10.6.2 Customizing the Create Job dialog box.

File system to be searched

If you select All software from the Software to be searched drop-down list, select the target file system for searches from either of the following:

Local file systems

Select this item when you want the local file system to be the search target.

Local file systems and Network file systems

Select this item when you want the local file system and the network file system to be the search targets.

(3) Notes on receiving software information

Note the following when collecting software information:

To collect software information from UNIX or Mac computers and manage it in the JP1/IT Desktop Management 2 windows, you must edit the configuration file (jdn_manager_config.conf). For details about how to edit the configuration file, see the section that describes the procedure for changing the settings for managing software information from agents for UNIX or agents for Mac in the JP1/IT Desktop Management 2 Configuration Guide.

If you collect software information first and then change the settings on the Search Target page and execute a job again, both pieces of software information collected will be merged.

You might not be able to collect software information containing any characters that cannot be converted to characters in the current code page.

When you change agent settings to change the system configuration, the information in the software search list is not inherited. Therefore, if you are using a software search list to perform a software search, use the software search list again for the agent when you change the system configuration.

(4) Creating a software search list

You can use the Software Search List dialog box to check the contents of software search lists.

Use either of the following methods to display the Software Search List dialog box:

Select a desired search list in the List of Software Information window, right-click, and then select Edit from the context menu that appears.

In the List of Software Information window, select File and then Create Search List.

Figure G‒3: Software Search List dialog box (Optional Software page)

The Optional Software page displays the contents of optional software lists. You can also edit the contents of the optional software list that you created.

Creating an optional software list

To create a new optional software list:

In the List of Software Information window, select File and then Create Search List.

The Software Search List dialog box appears.

Click the Add button.

The Add Software to List dialog box appears.

Figure G‒4: Add Software to List dialog box

Enter information about the software to be searched. You must specify the following items:

Package name

Enter 1 to 50 single-byte characters (or 1 to 25 double-byte characters). You cannot use backslashes (\) or semicolons (;).

Package ID

Enter 1 to 44 single-byte characters. You can use the following characters: A to Z, 0 to 9, underscores (_), and hyphens (-).

File name

Enter 1 to 256 single-byte characters (or 1 to 128 double-byte characters). You cannot use backslashes (\) or semicolons (;).

If you click the Browse button and specify a file, information about the corresponding software is set automatically. At this time, the Last update section is set to the local time on the managing server.

Click the Add button.

The specified items are added to the Optional Software page. You can continue adding other items.

Click the Cancel button.

The Add Software to List dialog box closes.

Click the Save button.

The Specify Search List Name dialog box appears.

Specify a name and click the OK button.

The settings are saved, and the Software Search List dialog box closes. The search list that you created appears in the List of Software Information window.

Creating an optional software list with a file

You can create an optional software list by using the Software Search List dialog box as well as a file specifying search list items. You can also output the optional software list displayed in the List of Software Information window to a file.

File format of optional software lists

The file format of optional software lists is shown below. An optional software list specifies a single line of information for each software program to be searched, in the following format. The file is in text format.

Entering a hash mark (#) in the first column of a line causes the line to be treated as a comment.

Format

information-map;program-identifier;file-name;package-ID;[version]; package-name;[last-file-update-time];[file-size];[generation-number]

Description

information-map (Required)

You must specify single-byte 001.

program-identifier (Required)

Specify a program ID as the corresponding single-byte character shown below.

P: Hitachi program products

I: Other companies' software

Space: User programs and data

Any specification other than the above is treated as if there were no specification.

file-name (Required)

Specify one of the files making up the software to be searched, by using up to 256 single-byte characters (or up to 128 double-byte characters). To ensure more accurate searches, we recommend that you specify a representative file of the software to be searched.

package-ID (Required)

Specify a unique string for the software to be searched, by using up to 44 characters. You can use the following single-byte characters: A to Z, 0 to 9, and hyphens (-). When you register new software information in an optional software list, specify information that is not used in the existing search list on the agent. For programs, we recommend that you specify them as below.

For Hitachi program products: product-name (such as P-2642-78BL)

For other companies' software: (company-name)-(product-name)

version

Specify the version of the software to be searched, by using up to six characters. You can use the following single-byte characters: A to Z, 0 to 9, and forward slashes (/). If you do not specify a version, the version is retrieved from the version resource of the file to be searched. If the version cannot be retrieved, 000000 is set automatically.

package-name (Required)

Specify the name of the software to be searched, by using up to 50 single-byte characters (or up to 25 double-byte characters). However, you cannot use backslashes (\).

last-file-update-time

Specify the time when the file specified in file-name was last updated. Specify this item when there are multiple versions of the software to be searched.

Use the YYYY/MM/DD/hh/mm/ss format to specify up to the required item:

YYYY: Year (1900 to 2100)

MM: Month (01 to 12)

DD: Day (01 to 31)

hh: Hour (00 to 23)

mm: Minute (00 to 59)

ss: Second (00 to 59)

(Example)

File created on October 1, 2015 at 11 o'clock: 2015/10/01/11

file-size

Specify the size of the file specified in file-name in bytes. Specify this item when there are multiple versions of the software to be searched. Specify the file size by using a number with up to 10 digits from 0 to 2,147,483,647.

generation-number

Specify the generation number of the software to be searched, by using up to four characters. You can use the following single-byte characters: A to Z and 0 to 9. If you do not specify this item, 0000 is set automatically.

Example:

001;I;oracle;ORACLE-DATABASE;0920;Oracle Database;2007/08/09/18/45;66146800;

Creating an optional software list from a file

To create an optional software list from a file specifying search list items:

In the List of Software Information window, select File and then Create from File.

The Load Search List dialog box appears.

Select a file, and click the OK button.

The Specify Search List Name dialog box appears.

Specify a name, and click the OK button.

The specified file is loaded to create a search list.

If there is an error in the file specification, a dialog box is displayed indicating the location of the error. In such a case, correct the file specification, and then retry.

Outputting an optional software list to a file

To output the contents of the optional software list displayed in the List of Software Information window to a file:

In the List of Software Information window, select the optional software list to be output.

Select File and then Save to File.

The Save Search List dialog box appears.

Specify a file name, and then click the OK button.

The contents of the optional software list are output to a file

Editing items in an optional software list

To edit items in a registered optional software list:

On the Optional Software page, select the item to be edited.

Click the Change button.

The Add Software to List dialog box appears.

Edit the registered contents.

In the Add Software to List dialog box, edit the registered contents.

Click the OK button.

The edited contents are reflected in the optional software list.

(5) Checking received software information

You can use the following methods to check the software information that you received.

If the software information of agents for UNIX and agents for Mac is set up so as to be managed in the configuration file (jdn_manager_config.conf)

You can use the Installed Software Details tab of the JP1/IT Desktop Management 2 device window to check the software information that you received. To do this:

In the Device List tab of the device window, select the host whose software information is to be displayed.

Select the Installed Software Details tab at the bottom of the window.

Information about the software installed on the selected host appears.

If the software information of agents for UNIX and agents for Mac is set up so as to be not managed in the configuration file (jdn_manager_config.conf)

You can use the Installed Packages page of the System Configuration or Destination window of Remote Install Manager to check the software information that you received. To do this:

In the left pane of the System Configuration or Destination window, select the host whose software information is to be displayed.

In the right pane of the window, select the Installed Packages tab.

Information about the software installed on the selected host appears.

(6) Deleting received software information

Assume that software information is collected on a managing server by executing a Get software information from computer (UNIX) job, and then unnecessary software programs are deleted from an agent. In such a case, the software information collected on the managing server might not match the software information on the agent. If this happens, temporarily delete the software information from the managing server.

You can delete software information from the managing server in the same way as deleting installed package information. For details, see 7.5 Deleting installed package information. Note that you must read the term package as software.

H. Relaying system integration procedure

This appendix explains the procedure for integrating relay systems (management relay servers and relay servers) in the following types of cases:

A relaying system was established in each department, but the departments were integrated.

Distributed to multiple relaying systems and managed host based on the server machine specs, network, and other hardware performance, but integration is desired in order to improve the network environment and procure high-spec machines for the server machines.

Figure H‒1: Image of integration

The relaying system retains job information received from the connection destination, and ID group registration information of the agent connected to the relaying system. Therefore, when changing the relaying system's connection destination, it is necessary to delete jobs and ID group registration information in advance and recreate them afterward.

H.1 Completing and deleting jobs executed from or through pre-change management relay server

Complete or delete all jobs executed from or through the management relay server before changes are made.

Especially be sure to delete regularly executed jobs.

If integration occurs without jobs being deleted or completed, jobs relayed to lower systems may remain without the possibility of deletion, job result reports may accumulate, and inventory information may be incorrectly managed and not be reported to the integration destination.

Integrate relay systems after confirming job completion and deletion.

For details, see 10.4 Checking the job status and 10.5 Actions after checking the job results.

H.2 Acquiring data with pre-change management relay server

Acquire ID group data with the management relay server before changes are made.

ID groups cannot be moved by file; therefore, check and record the following information:

With a higher-level primary management server, ID group used for management/relay of pre-change management relay server

ID group created with management relay server before change, and registered management relay (for case involving management relay server)

Figure H‒2: ID group check

When using Remote Install Manager, save ID hosts to a file by selecting Save ID Hosts to File from the File menu in the Remote Install Manager's Destination window.

For details, see 5.3.3 Registering managed computers in ID groups.

H.3 Changing connection destination of host managed on pre-change management relay server to post-change management relay server

Change the connection destination of a host under the pre-change management relay server to the post-change management relay server.

When the function for automatic registration into the system configuration is being used and the connection destination of a host under the pre-change management relay server has been changed to the post-change management relay server, it will be reflected in the system configuration.

Changing the relay system connection destination

If a relay system exists under the pre-change management relay server, change the lower relay system's connection destination to the relay system on the post-change management relay server side.

For a Windows relay system, change the connection destination via setup.

For a UNIX relay system, change the connection destination of the configuration file.

Figure H‒3: Changing connection destination of management relay server and relay system under management relay server

Figure H‒4: Changing connection destination of relay system under relay system

If you wish to immediately reflect system configuration information as a batch from Remote Install Manager, create from a file.

(1) Acquiring system configuration information with pre-change management relay server

For management relay server

With the pre-change management relay server, save the system configuration information to a file by selecting Save to File from the File menu in the Remote Install Manager's System Configuration window.

For relay system

Select Save to File from the File menu in the Remote Install Manager's Destination window, and save to a file.

(2) Adding system configuration information with post-change management relay server

Take system configuration information that was being managed by the pre-change management relay server and add it to the post-change management relay server.

For management relay server

Select Save to File from the File menu in the Remote Install Manager's System Configuration window, and acquire system configuration information to a file.

Merge with the system configuration information acquired from the pre-change management relay server.

After merging, select Create from File from the File menu in the Remote Install Manager's System Configuration window, and create system configuration information.

For relay system

Select Save to File from the File menu in the Remote Install Manager's Destination window, and acquire destination information to a file.

Merge with the destination information acquired from the pre-change management relay server.

After merging, select Create from File from the File menu in the Remote Install Manager's Destination window, and create destination information.

For details, see the following:

Changing connection destination using remote installation

3.4.3 Automatically changing the agent connection destination

System configuration information acquisition job

5.1.6 Collecting system configuration information of the systems under management relay servers

System configuration information

5.1.4 Updating system configuration information output to a file

5.2.3 Creating host groups from a file

H.4 Adding data to post-change management relay server

Add ID groups that were being managed by a pre-change management relay server to a post-change management relay server.

Create ID groups that were being managed by a pre-change management relay server.

For an ID group created with a higher system, register the post-change management relay server from the higher system to the ID group management relay.

For an ID group created with a pre-change management relay server, create an ID group on the post-change management relay server.

If a lower relay system has been registered as a management relay with a pre-change management relay server, register to the management relay.

Figure H‒5: ID group registration

When using Remote Install Manager, select Use File for ID Registration from the File menu in the Remote Install Manager's Destination window, and register the ID hosts.

For details, see 5.3.2 Creating ID groups and 5.3.3 Registering managed computers in ID groups.

I. Version Changes

I.1 Changes in version 13-01

None.

I.2 Changes in version 13-00

Windows Server 2022 is added as a supported operating system for the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - Asset Console

JP1/IT Desktop Management 2 - Internet Gateway

Remote Install Manager

Windows 11 is added as a supported operating system for the following products:

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - Network Monitor

Remote Install Manager

Windows Server 2012 is no longer supported by the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - Asset Console

Remote Install Manager

Made it possible to distribute packages on a priority basis.

Made it possible to specify the year in which to execute a job up to 2069.

Made it possible to regularly execute jobs by agent.

Added procedures for integrating relaying systems.

I.3 Changes in version 12-60

Add a description of the installation definition file.

I.4 Changes in version 12-50

CentOS 8, Linux 8, and Oracle Linux 8 were added as applicable operating systems for JP1/IT Desktop Management 2 - Agent.

I.5 Changes in version 12-10

Windows Server 2019 was added as an applicable operating system for the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - Asset Console

JP1/IT Desktop Management 2 - Internet Gateway

Remote Install Manager

Windows updates and a feature update to Windows 10 can now be packaged for distribution by using the Remote Install Manager.

I.6 Changes in version 12-00

Windows Server 2008 R2 is no longer supported by the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - Asset Console

Remote Install Manager

Changes were made so that the connection destination used for file distribution can be automatically switched from one higher system to another.

I.7 Changes in version 11-51

A file larger than 2 gigabytes can now be distributed.

An option for splitting the file to be distributed into pieces with a certain size was added to the dcmpack command.

The catAndValidatePackagingFile command was added.

I.8 Changes in version 11-50

Software and files can now be distributed (remotely installed) to agents for Mac.

An agent can now be installed on a server where Citrix XenApp and Microsoft RDS are installed so that JP1/IT Desktop Management 2 can manage the server.

For automatic ID group maintenance, policies can now be created based on device information (model, manufacturer, IP address, installed software information, and asset management item).

I.9 Changes in version 11-10

Windows Server 2016 was added as an applicable operating system for the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - Asset Console

Remote Install Manager

The following products were added as an applicable operating system for JP1/IT Desktop Management 2 - Agent.

Red Hat Enterprise Linux(R) 5

Agents can now be installed and managed on computers whose OS is Mac.

Functions that are provided:

• Acquisition of system and software information

• Remote control by RFB connection (this function had already been provided in agentless configurations)

• Network control (on-demand connection permission and disconnection)

Functions that are not provided (including functions that are planned to be provided):

• Software and file distribution (remote installation)

• File collection (remote collection)

• Agent configuration and agent deployment

• Security control (security check and automatic enforcement)

• Operation logs

• Device control

A judging method can now be selected during packing if multiple package conditions and software conditions are set.

I.10 Changes in version 11-01

Windows 10 was added as an applicable operating system for JP1/IT Desktop Management 2 - Network Monitor.

The icons and buttons for starting online Help were removed from the operation window.

When duplicate devices or idle devices that are detected by device maintenance and suggested for deletion are either manually or automatically deleted, the system configuration information of the deleted devices is now automatically deleted. The devices are also automatically deleted from the host groups and ID groups to which they belonged. As such, the Auto System Configuration Maintenance menu, the Manual System Configuration Maintenance menu, and the Find duplicate hosts tab were deleted.

The connection destinations of agents can now be specified by using the file for connection destinations (itdmhost.conf).

Notes on executing the Get system configuration information job were added.

The procedure for deleting an IP address in the Rename dialog box (displayable from the System Configuration window) was deleted. A description was added that the items that can be changed in the Change Attributes dialog box vary depending on the ID key setting.

Notes on changing the host name in system configuration information were added.

The procedure for creating a job management folder was modified..

I.11 Changes in version 11-00

Information about JP1/IT Desktop Management 2 - Manager systems with a multi-server configuration was added to the manual. Accordingly, job types and GUI terms were reviewed.

Windows 10 was added as a supported operating system for the following products:

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - RC Manager

Remote Install Manager

Windows Server 2003 and Windows Server 2008 (excluding Windows Server 2008 R2) are no longer supported by the following products:

JP1/IT Desktop Management 2 - Manager

JP1/IT Desktop Management 2 - Agent

JP1/IT Desktop Management 2 - Network Monitor

JP1/IT Desktop Management 2 - RC Manager

The JP1/IT Desktop Management 2 Automatic Installation Tool Administration Guide was merged into this manual.

Agents can now be installed on UNIX computers to manage them.

J. Reference Material for This Manual

J.1 Related publications

This manual is part of a related set of manuals. The manuals in the set are listed below (with the manual numbers):

JP1 Version 13 Asset and Distribution Management: Getting Started (3021-3-L71(E))

JP1 Version 13 JP1/IT Desktop Management 2 Overview and System Design Guide (3021-3-L72(E))

JP1 Version 13 JP1/IT Desktop Management 2 Configuration Guide (3021-3-L73(E))

JP1 Version 13 JP1/IT Desktop Management 2 Administration Guide (3021-3-L74(E))

JP1 Version 13 JP1/IT Desktop Management 2 - Asset Console Configuration and Administration Guide (3021-3-L76(E))

JP1 Version 13 JP1/IT Desktop Management 2 - Asset Console Creating an Access Definition File Guide (3021-3-L77(E))

JP1 Version 13 JP1/IT Desktop Management 2 Messages (3021-3-L78(E))

JP1 Version 13 JP1/IT Desktop Management 2 - Agent Description and User's Guide (For UNIX Systems) (3021-3-L80(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Overview (3021-3-L42(E))

JP1 Version 13 JP1/Automatic Job Management System 3 System Design (Configuration) Guide (3021-3-L43(E))

JP1 Version 13 JP1/Automatic Job Management System 3 System Design (Work Tasks) Guide (3021-3-L44(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Administration Guide (3021-3-L46(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Troubleshooting (3021-3-L47(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Operator's Guide (3021-3-L48(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Command Reference (3021-3-L49(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Linkage Guide (3021-3-L50(E))

JP1 Version 13 JP1/Automatic Job Management System 3 Messages (3021-3-L51(E))

JP1 Version 13 JP1/Base User's Guide (3021-3-L09(E))

JP1 Version 13 JP1/Base Messages (3021-3-L10(E))

JP1 Version 13 JP1/Base Function Reference (3021-3-L11(E))

JP1 Version 13 JP1/Integrated Management 3 - Manager Configuration Guide (3021-3-L03(E))

JP1 Version 13 JP1/Integrated Management 3 - Manager Administration Guide (3021-3-L04(E))

JP1 Version 12 JP1/Integrated Management 2 - Manager Configuration Guide (3021-3-D52(E))

JP1 Version 12 JP1/Integrated Management 2 - Manager Administration Guide (3021-3-D53(E))

JP1 Version 11 JP1/Integrated Management - Manager Configuration Guide (3021-3-A08(E))

JP1 Version 11 JP1/Integrated Management - Manager Administration Guide (3021-3-A09(E))

J.2 Conventions: Abbreviations for product names

This manual uses the following abbreviations for product names:

Abbreviation

Full name or meaning

ActiveX

ActiveX(R)

AMT

Intel Active Management Technology

Citrix XenApp

Citrix XenApp(R)

Citrix Virtual Apps

InstallShield

InstallShield(R)

Itanium 2

Intel(R) Itanium(R) 2 Processor

JP1/AJS

JP1/Automatic Job Management System 2

JP1/Automatic Job Management System 3

JP1/IM

JP1/IM - Manager

JP1/Integrated Management - Manager

JP1/Integrated Management 2 - Manager

JP1/Integrated Management 3 - Manager

JP1/IM - View

JP1/Integrated Management - View

JP1/Integrated Management 2 - View

JP1/Integrated Management 3 - View

Linux

CentOS

CentOS 6

CentOS 7

CentOS 8.1

Oracle Linux

Oracle Linux 6.1 (x86)

Oracle Linux 6.1 (x64)

Oracle Linux 7.1

Oracle Linux 8

Red Hat Enterprise Linux Server

Red Hat Enterprise Linux 5 (x86)

Red Hat Enterprise Linux 5 (AMD/Intel 64)

Red Hat Enterprise Linux 5 Advanced Platform (x86)

Red Hat Enterprise Linux 5 Advanced Platform (AMD/Intel 64)

Red Hat Enterprise Linux Server 6 (32-bit x86)

Red Hat Enterprise Linux Server 6 (64-bit x86_64)

Red Hat Enterprise Linux Server 7 (64-bit x86_64)

Red Hat Enterprise Linux(R) Server 8

Mac

Mac OS

OS X 10.10

OS X 10.11

macOS 10.12

macOS 10.13

macOS 10.14

UNIX

AIX

AIX V6.1

AIX V7.1

AIX V7.2

Solaris

Solaris 10 (SPARC)

Solaris 11 (SPARC)

HP-UX

HP-UX 11i V3 Server (IPF)

Pentium

Intel Pentium(R)

This manual uses the following abbreviations for Microsoft product names:

Abbreviation

Product name

Internet Explorer

Microsoft(R) Internet Explorer

Windows(R) Internet Explorer(R)

MS-DOS

Microsoft(R) MS-DOS(R)

Windows

Windows 7

Windows 7 Enterprise

Microsoft(R) Windows(R) 7 Enterprise

Windows 7 Home Basic

Microsoft(R) Windows(R) 7 Home Basic

Windows 7 Home Premium

Microsoft(R) Windows(R) 7 Home Premium

Windows 7 Professional

Microsoft(R) Windows(R) 7 Professional

Windows 7 Starter

Microsoft(R) Windows(R) 7 Starter

Windows 7 Ultimate

Microsoft(R) Windows(R) 7 Ultimate

Windows 8

Windows 8

Windows(R) 8

Windows 8 Enterprise

Windows(R) 8 Enterprise

Windows 8 Pro

Windows(R) 8 Pro

Windows 8.1

Windows 8.1

Windows(R) 8.1

Windows 8.1 Enterprise

Windows(R) 8.1 Enterprise

Windows 8.1 Pro

Windows(R) 8.1 Pro

Windows 10

Windows 10 Enterprise

Windows(R) 10 Enterprise

Windows 10 Enterprise multi-session

Windows(R) 10 Enterprise multi-session

Windows 10 Pro

Windows(R) 10 Pro

Windows 11

Windows 11 Enterprise

Windows(R) 11 Enterprise

Windows 11 Enterprise multi-session

Windows(R) 11 Enterprise multi-session

Windows 11 Pro

Windows(R) 11 Pro

Windows 11 Pro for Workstations

Windows(R) 11 Pro for Workstations

Windows Server 2003#1

Windows Server 2003#1

Windows Server 2003 Enterprise

Microsoft(R) Windows Server(R) 2003 R2, Enterprise Edition

Microsoft(R) Windows Server(R) 2003, Enterprise Edition

Windows Server 2003 Standard

Microsoft(R) Windows Server(R) 2003 R2, Standard Edition

Microsoft(R) Windows Server(R) 2003, Standard Edition

Windows Server 2003 (x64)

Windows Server 2003 Enterprise (x64)

Microsoft(R) Windows Server(R) 2003 R2, Enterprise x64 Edition

Microsoft(R) Windows Server(R) 2003, Enterprise x64 Edition

Windows Server 2003 Standard (x64)

Microsoft(R) Windows Server(R) 2003 R2, Standard x64 Edition

Microsoft(R) Windows Server(R) 2003, Standard x64 Edition

Windows Server 2008#2

Windows Server 2008#2

Windows Server 2008 Datacenter

Microsoft(R) Windows Server(R) 2008 Datacenter

Microsoft(R) Windows Server(R) 2008 Datacenter without Hyper-V(R)

Windows Server 2008 Enterprise

Microsoft(R) Windows Server(R) 2008 Enterprise

Microsoft(R) Windows Server(R) 2008 Enterprise without Hyper-V(R)

Windows Server 2008 Standard

Microsoft(R) Windows Server(R) 2008 Standard

Microsoft(R) Windows Server(R) 2008 Standard without Hyper-V(R)

Windows Server 2008 R2

Microsoft(R) Windows Server(R) 2008 R2 Datacenter

Microsoft(R) Windows Server(R) 2008 R2 Enterprise

Microsoft(R) Windows Server(R) 2008 R2 Standard

Windows Server 2012#3

Windows Server 2012#3

Windows Server 2012 Datacenter

Microsoft(R) Windows Server(R) 2012 Datacenter

Windows Server 2012 Standard

Microsoft(R) Windows Server(R) 2012 Standard

Windows Server 2012 R2

Microsoft(R) Windows Server(R) 2012 R2 Datacenter

Microsoft(R) Windows Server(R) 2012 R2 Standard

Windows Server 2016

Windows Server 2016 Datacenter

Microsoft(R) Windows Server(R) 2016 Datacenter

Windows Server 2016 Standard

Microsoft(R) Windows Server(R) 2016 Standard

Windows Server 2019

Windows Server 2019 Datacenter

Microsoft(R) Windows Server(R) 2019 Datacenter

Windows Server 2019 Standard

Microsoft(R) Windows Server(R) 2019 Standard

Windows Server 2022

Windows Server 2022 Datacenter

Microsoft(R) Windows Server(R) 2022 Datacenter

Windows Server 2022 Standard

Microsoft(R) Windows Server(R) 2022 Standard

Windows Vista

Microsoft(R) Windows Vista(R) Business

Microsoft(R) Windows Vista(R) Enterprise

Microsoft(R) Windows Vista(R) Home Basic

Microsoft(R) Windows Vista(R) Home Premium

Microsoft(R) Windows Vista(R) Ultimate

Windows XP

Windows XP Home Edition

Microsoft(R) Windows(R) XP Home Edition Operating System

Windows XP Professional

Microsoft(R) Windows(R) XP Professional Operating System

#1

If Windows Server 2003 is noted alongside Windows Server 2003 (x64), the description for Windows Server 2003 does not apply to Windows Server 2003 (x64).

#2

If Windows Server 2008 is noted alongside Windows Server 2008 R2, the description for Windows Server 2008 does not apply to Windows Server 2008 R2.

#3

If Windows Server 2012 R2 is noted alongside Windows Server 2012, the description for Windows Server 2012 does not apply to Windows Server 2012 R2.

J.3 Conventions: Acronyms

Acronym

Full name or meaning

API

Application Programming Interface

BIOS

Basic Input Output System

CD-R

Compact Disc Recordable

CD-ROM

Compact Disc Read Only Memory

CPU

Central Processing Unit

CSV

Comma Separated Value

DB

Database

DHCP

Dynamic Host Configuration Protocol

DLL

Dynamic Linking Library

DNS

Domain Name System

DoS

Denial of Service

DVD

Digital Versatile Disk

DVD-R

Digital Versatile Disk Recordable

FTP

File Transfer Protocol

GUI

Graphical User Interface

HTTP

Hypertext Transfer Protocol

ID

Identifier

IP

Internet Protocol

ISO

International Organization for Standardization

JIS

Japanese Industrial Standards

LAN

Local Area Network

MAC

Media Access Control

MS-DOS

Microsoft Disk Operating System

NIC

Network Interface Card

OS

Operating System

OU

Organizational Unit

PC

Personal Computer

PME

Power Management Event

RWU

Remote-Wake-UP

SD

Secure Digital

SNMP

Simple Network Management Protocol

SSL

Secure Sockets Layer

TCP

Transmission Control Protocol

TCP/IP

Transmission Control Protocol/Internet Protocol

USB

Universal Serial Bus

VPN

Virtual Private Network

WINS

Windows Internet Name Service

WS

Workstation

WWW

World Wide Web

XML

Extensible Markup Language

J.4 Conventions: Fonts and symbols

The Windows menu names used in this manual assume the operating systems shown below:

For managing servers, database servers, computers with Network Monitor enabled, and computers on which controllers are installed:

Windows Server 2008 R2

For computers with agent software installed:

Windows 7

The Start menu is not displayed in Windows Server 2019, Windows Server 2016, Windows 8.1, Windows 8, and Windows Server 2012. Select the menu by opening the Start window from the bottom left corner of the desktop.

The following table explains the text formatting conventions used in this manual:

Text formatting

Convention

Bold

Bold characters indicate text in a window, other than the window title. Such text includes menus, menu options, buttons, radio box options, or explanatory labels. For example:

From the File menu, choose Open.

Click the Cancel button.

In the Enter name entry box, type your name.

Italic

Italic characters indicate a placeholder for some actual text to be provided by the user or system. For example:

Write the command as follows:

copy source-file target-file

The following message appears:

A file was not found. (file = file-name)

Italic characters are also used for emphasis. For example:

Do not delete the configuration file.

Monospace

Monospace characters indicate text that the user enters without change, or text (such as messages) output by the system. For example:

At the prompt, enter dir.

Use the send command to send mail.

The following message is displayed:

The password is incorrect.

The following table explains the symbols used in this manual:

Symbol

Convention

|

In syntax explanations, a vertical bar separates multiple items, and has the meaning of OR. For example:

A|B|C means A, or B, or C.

{ }

In syntax explanations, curly brackets indicate that only one of the enclosed items is to be selected. For example:

{A|B|C} means only one of A, or B, or C.

[ ]

In syntax explanations, square brackets indicate that the enclosed item or items are optional. For example:

[A] means that you can specify A or nothing.

[B|C] means that you can specify B, or C, or nothing.

...

In coding, an ellipsis (...) indicates that one or more lines of coding have been omitted.

In syntax explanations, an ellipsis indicates that the immediately preceding item can be repeated as many times as necessary. For example:

A, B, B, ... means that, after you specify A, B, you can specify B as many times as necessary.

J.5 Conventions: Version numbers

The version numbers of Hitachi program products are usually written as two sets of two digits each, separated by a hyphen. For example:

Version 1.00 (or 1.0) is written as 01-00.

Version 2.05 is written as 02-05.

Version 2.50 (or 2.5) is written as 02-50.

Version 12.25 is written as 12-25.

The version number might be shown on the spine of a manual as Ver. 2.00, but the same version number would be written in the program as 02-00.

J.6 About online help

JP1/IT Desktop Management 2 provides online help in relation to the following subjects:

Window descriptions

This help describes how to use the screen that is currently displayed. You can view these help topics by clicking the Help button in the user interface.

J.7 Conventions: KB, MB, GB, and TB

This manual uses the following conventions:

1 KB (kilobyte) is 1,024 bytes.

1 MB (megabyte) is 1,024² bytes.

1 GB (gigabyte) is 1,024³ bytes.

1 TB (terabyte) is 1,024⁴ bytes.

K. Glossary

A

agent

A program installed on the computers managed by JP1/IT Desktop Management 2. The agent program reports information to JP1/IT Desktop Management 2 - Manager, and controls its host computer based on instructions from JP1/IT Desktop Management 2 - Manager. The name of the agent program is JP1/IT Desktop Management 2 - Agent.

agent configurations

Agent setup information managed on the management server. You can change the setup of an agent remotely by creating agent configurations in the user interface and assigning them to an agent.

AIT file

A file that contains the procedure for installing software interactively using a dedicated installer or other tool. AIT files are created by the Automatic Installation Tool.

application gateway method

A method of building a firewall that prohibits packet relay and uses an application gateway to control access. Users cannot gain direct access to the system from the outside; they must log in through a gateway by entering a user ID and a password.

asset management item

An asset item that can be managed in JP1/IT Desktop Management 2. Examples include user names, email addresses, posts, and installation locations. When you use Remote Install Manager to distribute software, you can specify posts, installation locations, and additional management items of hardware asset information in the automatic maintenance policy for a host group or ID group.

associated label

A kind of control. This text cannot be manipulated or modified by users. Generally, an associated label is also used as a description of another control such as a list box without a caption. An associated label is the text immediately before a control in the tab order.

audit log

A log file shared by all JP1 products. It provides a record of who performed each operation, the type of operation, and when it was performed.

automatic maintenance policy file

A file in XML format that contains the policy for automatic maintenance of host groups and ID groups.

C

cabinet

An area in a managing server that is used to store packages.

cabinet ID

A unique ID for each cabinet. This term is used in the UNIX version of JP1/IT Desktop Management 2 - Agent and is equivalent to the term cabinet ID for the Windows version of JP1/IT Desktop Management 2 - Agent.

caption

Text displayed on the top of a control or as the title of a window.

child window

A window that descends from another window (a parent window). For example, an application uses child windows to divide a single parent window into multiple work areas. Individual controls such as check boxes and text boxes within a dialog box are equivalent to the child windows of a dialog box.

Citrix XenApp and Microsoft RDS server

A server where Citrix XenApp and Microsoft RDS (Remote Desktop Services) are installed. An agent can be installed on a server where Citrix XenApp and Microsoft RDS are installed so that JP1/IT Desktop Management 2 can manage the server.

Client Control function

A function that allows you to start and shut down PCs remotely via a network. By using this function, JP1/IT Desktop Management 2 can remotely turn on remote PCs and install software at night, on weekends, and on holidays. To use the Client Control function, the remote PC must support AMT or Wake on LAN.

collected file

A file collected from a managed computer by remote collection.

control

Graphical objects arranged in a window, such as text boxes and command buttons. Controls are equivalent to the child windows of a window where controls are displayed.

controller

A program that remotely controls a managed computer.

D

date/time picker

A kind of control that enables you to select a date or time.

device information

Information JP1/IT Desktop Management 2 collects from managed devices, such as the hardware usage for the computer and types of software installed on a computer. This information is used to manage devices. You can view device information in the Device Inventory panel of the Inventory module.

distribution using Remote Install Manager

One of the two distribution functions provided by JP1/IT Desktop Management 2. This function uses Remote Install Manager to distribute software. You can also use commands to control software distribution. The other function is ITDM-compatible distribution.

domain

A unit for managing hosts and users in a network.

E

event

Phenomena that computers can detect, such as user operations or program status changes. Events that occur as a result of user operations include mouse clicks, menu selection, keyboard operation, and time lapse. Other events are those that occur within applications or operating systems, such as unprocessed exceptions, or window creation or disappearance.

execution timing

The timing with which a package is installed on a managed computer. You can select When System Starts up, which installs the package when the managed computer is started, or Immediately, which installs the package as soon as the package is transferred to the managed computer.

F

file for higher system addresses

A configuration file that defines the mappings between host names and IP addresses. It is used to identify the IP address of a higher system when a computer that communicates using host names cannot resolve the host name of the higher system.

firewall

A component installed at the boundary between the Internet and an internal system, which prevents unauthorized access to the internal system from the outside.

focus

A temporary attribute of user interface objects such as windows, views, dialog boxes, or buttons. An object that is focused can receive user inputs. For example, when a text box is focused, a string that a user enters is displayed in the text box. Normally, a focused object is highlighted.

H

handle

A unique 4-byte integer. A handle can be used to identify each window or control to be accessed. This value is assigned by the operating system.

host

A networked Windows, UNIX, or Mac computer that is the target of JP1/IT Desktop Management 2 operations.

host group

A method of grouping computers so that jobs can be executed on multiple computers. This method allows you to group hosts from the managing system based on the job, organization, or other common purpose.

host ID

A key that uniquely identifies a host in a system. Because host IDs are not affected by the network configuration, the system administrator can use host IDs to manage hosts more efficiently.

I

ID group

A method of grouping computers so that jobs can be executed on multiple computers. You can assign ID groups to computers from an agent or the managing server.

ID group job

A job for which an ID group is specified as the destination.

ID-management relay computer

A relay system or management relay server that manages ID group jobs and computers belonging to an ID group. When an ID group job is executed, the corresponding ID-management relay computer stores the ID group job on the local system and executes the job for the computers belonging to the ID group.

installation mode

The method used to install packages on managed computers. There are two installation modes: GUI installation mode which uses an installer, and Background installation mode in which the files are simply copied without the use of an installer.

ITDM-compatible distribution

One of the two distribution functions provided by JP1/IT Desktop Management 2. ITDM-compatible distribution uses window operations in the distribution module to distribute software. The other function is distribution by using Remote Install Manager.

J

job

The unit of task execution in JP1/IT Desktop Management 2.

JP1/AJS

A program for running jobs automatically. Using JP1/AJS, you can execute a sequence of processes according to a predefined schedule, or initiate processing when a specific event occurs.

JP1/Base

A program that provides the core functionality for JP1/IM.

JP1/Base sends and receives JP1 events. It also functions as the JP1/IM system agent.

JP1/Base is a prerequisite program for JP1/IM - Manager.

JP1/IM

A program that centrally monitors a distributed system. Information about events such as job processing and errors in the distributed system is reported to JP1/IM as JP1 events. JP1/IM registers and manages JP1 events, and displays them on the system administrator's screen.

JP1 event

Information that is reported to JP1/Base about an event that has occurred in a system.

M

managed computer

A computer on which the JP1/IT Desktop Management 2 - Agent software is installed, or an agent under a relay system in the system configuration information that has the same name as the relay system. A managed computer receives software directly from the managing server or through a relay system or management relay server, and can then install the software on the local system and notify the managing server of the result of the installation process.

management relay server

A JP1/IT Desktop Management 2 - Manager system under the highest managing server in a managing server system with a hierarchical structure. A management relay server can relay jobs (such as remote installation or file transfer) between the managing server and managed computers.

management server

A computer where JP1/IT Desktop Management 2 - Manager is installed. The term management server collectively refers to management servers with a single-server configuration, primary management servers with a multi-server configuration, and site management servers with a multi-server configuration.

managing server

A generic term for JP1/IT Desktop Management 2 - Manager.

multicast address

The IP address of a multicast group. The multicast address is specified when the sender and receivers for multicast distribution are set up.

multicast distribution

A method of job distribution that uses the IP multicast protocol to send packets to many specific computers from a higher system. This method uses less traffic because the higher system only needs to send the job packet to one multicast group location, regardless of how many computers belong to the group.

multicast group

A conceptual group to which jobs are distributed by multicast distribution. A multicast group has its own IP address called a multicast address. When a higher system sends job packets to a multicast group, the packets are then distributed to each computer in that group.

multiple LAN connections

A JP1 function for handling systems that consist of multiple local area networks (LANs). By using this function, you can predefine which LAN JP1 uses for communication on hosts that are connected to multiple LANs. Because JP1 communication can be set up independently of the system and other applications, this function allows for a wide range of network configurations and modes of operation. Hosts connected to multiple LANs may also be called multi-homed hosts or multiple Network Interface Card (NIC) hosts.

JP1/IT Desktop Management 2 supports the following multiple LAN connection environments:

Environments divided into multiple networks

Environments with duplex networks

O

offline installation

The process of installing software using installation media rather than over a network.

offline machine

A Windows computer whose information is not registered in the JP1/IT Desktop Management 2 system configuration information. Examples of offline machines are:

A computer with JP1/IT Desktop Management 2 - Agent installed that is used as a standalone device

A computer on the network with JP1/IT Desktop Management 2 - Agent installed that is not registered in the JP1/IT Desktop Management 2 system configuration information

You can install software on offline machines.

P

package (for distribution using Remote Install Manager)

A unit of software distributed using Remote Install Manager. Packages you create in the Packager are stored in the cabinet of a managing server. You can then use Remote Install Manager or a command to distribute the package.

package ID

A name assigned to a software program during packaging. This term is used in the UNIX version of JP1/IT Desktop Management 2 - Agent and is equivalent to the term package ID for the Windows version of JP1/IT Desktop Management 2 - Agent.

Package Setup Manager

A function that allows users to select and install software programs received from the managing server or relay systems. In Package Setup Manager, you can change the installation directory of the selected software and view a list of software distributed from Remote Install Manager.

Packager

A program that registers in the managing server software to be remotely installed.

package type

The type of package. There are three package types: user programs and data, Hitachi program products, and other companies' software.

packaging

The process of using the Packager to create a package.

packet filtering method

A method of building a firewall that limits the packets that can pass through the firewall. This method offers a variety of configurations, such as allowing access from within the system to the outside but prohibiting access into the system from the outside. This method can limit the number of terminals that are permitted to access the Internet.

policy

Preset conditions that govern the automatic assignment to a host group or ID group of a new host added to the system configuration. Policies are used by the function for automatic registration into the system configuration.

R

relay system

An instance of JP1/IT Desktop Management 2 - Agent that is positioned between a managing server and managed computers, and relays jobs related to remote installation, file transfer, and other tasks.

remote collection

A function that uses Remote Install Manager to collect files from managed computers in a batch process.

Remote Control Agent

A component of the agent program. You can use all remote control functions by establishing a standard connection between the Remote Control Agent and the controller.

remote control function

A function that connects to a remote computer and controls its GUI using keyboard and mouse operations.

Remote Desktop

In this manual, Remote Desktop refers to the Remote Desktop for Administration or Remote Desktop function in Windows Server 2019, Windows Server 2016, Windows 10, Windows 8.1, Windows 8, Windows Server 2012, Windows Server 2008, Windows Server 2003, Windows 7, Windows Vista, or Windows XP.

remote installation

A function that distributes software and files as a batch from a managing server to a user's computer.

Remote Install Manager

A component of JP1/IT Desktop Management 2. Install this component if you want to perform distribution using Remote Install Manager.

S

split distribution

A method of reducing the load on the network by dividing packages into segments of a size specified by the user and transferring them at a specific interval. The user can specify the size of each segment at agent setup or job creation, or even at relay locations along the package transfer route. Split distribution is useful for distributing large packages.

system information

Hardware information for the hosts that make up a JP1/IT Desktop Management 2 system.

T

tab order

The order in which the focus is moved from one control to another by pressing the Tab key.

U

unarchiver

A program that restores archived and compressed files to their original form during remote collection.

unicast distribution

A method of job distribution in which packets are sent from a higher system to each computer individually. Because the higher system has to send each job packet separately to each target computer, the number of times a packet is sent increases in proportion to the number of computers in the system.

updated program

A program provided by Microsoft Corporation that updates aspects of Windows, Internet Explorer, and other Microsoft products.

W

Wake on LAN

A standard for turning on a computer in a local area network (LAN) from another computer in the network.

Index

A

abbreviations for products[1]

Acquiring the updates to be applied to clients[1]

acronyms[1]

action[1]

actions after checking job results[1]

Add/Remove Breakpoint[1]

adding

package[1]

target files[1]

adding operators[1]

Add logging (check box)[1]

agent

automatically changing connection destination[1]

before use[1]

configuring operating environment[1]

connection settings when higher system name cannot be resolved[1]

glossary[1]

menu items[1]

setting polling method[1]

agent (JP1/IT Desktop Management 2 - Agent)

performing operations[1]

agent configurations

glossary[1]

AIT_ASCIIToChar[1]

AIT_ChangeFileAttribute[1]

AIT_CharToASCII[1]

AIT_CheckResolution[1]

AIT_ComboBoxCloseUp[1]

AIT_ComboBoxDropDown[1]

AIT_CtrlClick[1]

AIT_CtrlItemCount[1]

AIT_CtrlItemIndex[1]

AIT_CtrlSetFocus[1], [2]

example of using[1]

AIT_DefaultButtonCount[1]

AIT_DirCopy[1]

AIT_DirCreate[1]

AIT_DirRemove[1]

AIT_DMPSTRC[1]

AIT_Exec[1]

AIT_ExecCommand[1]

AIT_ExistWindow[1]

AIT_Exit[1]

AIT_FileClose[1]

AIT_FileCopy[1]

AIT_FileDelete[1]

AIT_FileEOF[1]

AIT_FileExists[1]

AIT_FileGetLine[1]

AIT_FileGetPos[1]

AIT_FileOpen[1]

AIT_FilePutLine[1]

AIT_FileRename[1]

AIT_FileSetPos[1]

AIT_FileSize[1]

AIT_FindCloseFile[1]

AIT_FindFirstFile[1]

AIT_FindNextFile[1]

AIT_FindSubStr[1]

AIT_FocusWindow[1], [2]

example of using[1]

AIT_GetCtrlText[1]

AIT_GetCtrlTextLen[1]

AIT_GetCurrentDirectory[1]

AIT_GetDate[1]

AIT_GetDtPickerDate[1]

AIT_GetDtPickerTime[1]

AIT_GetEditCurrentLineIndex[1]

AIT_GetEditFirstLineIndex[1]

AIT_GetEditTextLineLen[1]

AIT_GetEnv[1]

AIT_GetErrorText[1]

AIT_GetIndexText[1]

AIT_GetIndexTextLen[1]

AIT_GetKeyState[1]

AIT_GetLastError[1]

AIT_GetMenu[1]

AIT_GetMenuIndex[1]

AIT_GetMenuText[1]

AIT_GetOSType[1]

AIT_GetProfileFirstSection[1]

AIT_GetProfileFirstSectionNames[1]

AIT_GetProfileNextSection[1]

AIT_GetProfileNextSectionNames[1]

AIT_GetProfileString[1]

AIT_GetSubMenu[1]

AIT_GetSubStr[1]

AIT_GetTime[1]

AIT_GetWindowText[1]

AIT_IMEGetConversionStatus[1]

AIT_IMEGetOpenStatus[1]

AIT_IMEGetProperty[1]

AIT_IMEGetStatusWindowPos[1]

AIT_IMESetConversionStatus[1]

AIT_IMESetOpenStatus[1]

AIT_IMESetStatusWindowPos[1]

AIT_IMESimulateHotKey[1]

AIT_InitLog[1]

AIT_IsEmpty[1]

AIT_LogMessage[1]

AIT_MenuItemClick[1]

AIT_MessageBox[1]

AIT_MinWnd[1]

AIT_MouseClick[1]

AIT_MouseDblClk[1]

AIT_MouseDown[1]

AIT_MouseDragDrop[1]

AIT_MouseMoveTo[1]

AIT_MouseUp[1]

AIT_PlayKey[1], [2]

example of using[1]

AIT_PostMessage[1]

AIT_RegCloseKey[1]

AIT_RegCreateKey[1]

AIT_RegDeleteKey[1]

AIT_RegDeleteValue[1]

AIT_RegGetDWORDValue[1]

AIT_RegGetStringValue[1]

AIT_RegisterWindowMessage[1]

AIT_RegKeyExists[1]

AIT_RegOpenKey[1]

AIT_RegSetDWORDValue[1]

AIT_RegSetStringValue[1]

AIT_RegValueExists[1]

AIT_SelectIPAddressField[1]

AIT_SelectListItem[1]

AIT_SelectMultipleListItem[1]

AIT_SelectText[1]

AIT_SetActWnd[1]

AIT_SetCheck[1]

AIT_SetComboEditSelText[1]

AIT_SetCurrentDirectory[1]

AIT_SetDefaultWaitTimeout[1]

AIT_SetDtPickerDate[1]

AIT_SetDtPickerTime[1]

AIT_SetKeyState[1]

AIT_SetProfileString[1]

AIT_SetScrollPos[1]

AIT_SetSpinPos[1]

AIT_SetWndPos[1]

AIT_SetWndPosSize[1]

AIT_Sleep[1]

AIT_StatusBox[1]

AIT_StatusBoxClose[1]

AIT_StrLeft[1]

AIT_StrLength[1]

AIT_StrLower[1]

AIT_StrLTrim[1]

AIT_StrRight[1]

AIT_StrRTrim[1]

AIT_StrTrim[1]

AIT_StrUpper[1]

AIT_TaskbarClk[1]

AIT_TaskbarHasFocus[1]

AIT_TaskbarSetFocus[1]

AIT_VerifyCharPos[1]

AIT_VerifyCount[1]

AIT_VerifyDateTime[1]

AIT_VerifyDefaultButton[1]

AIT_VerifyEnabled[1], [2]

example of using[1]

AIT_VerifyExistence[1], [2]

example of using[1]

AIT_VerifyFirstVisible[1]

AIT_VerifyFocus[1]

AIT_VerifyIndex[1]

AIT_VerifyKeyState[1]

AIT_VerifyLine[1]

AIT_VerifyLocation[1]

AIT_VerifyMenuChecked[1]

AIT_VerifyMenuEnabled[1]

AIT_VerifyNoOfCtrls[1]

AIT_VerifyPos[1], [2]

example of using[1]

AIT_VerifySelected[1]

AIT_VerifyState[1]

AIT_VerifyText[1]

AIT_Wow64DisableWow64Redirection[1]

AIT_Wow64RevertWow64Redirection[1]

ait.log[1]

aitapi.log[1]

aitexec.log[1]

AIT file[1], [2]

checking and modifying automatically generated AIT file[1]

correctly identifying end of installation operations[1]

creating[1]

debugging[1]

editing[1]

example of completed AIT file[1]

format[1]

glossary[1]

note on using text to identify window[1]

notes about creating and using[1]

procedure for creating[1]

structure[1], [2]

AIT File[1]

AIT language

binary operators supported by[1]

unary operators supported by[1]

API for finding window[1]

API for operating window[1]

API function reference[1]

API functions[1]

details[1]

for character string operations[1]

for checking resolution[1]

for check operations[1]

for date/time operations[1]

for directory operations[1]

for file operations[1]

for INI file operations[1]

for interfacing with JP1/IT Desktop Management 2[1]

for message operations[1]

for Recorder operations[1]

for redirect operations[1]

for registry operations[1]

for taskbar operations[1]

for utility operations[1]

for window operations[1]

application gateway firewall[1]

application gateway method

glossary[1]

apply policies to all hosts[1]

asset management item

glossary[1]

assigning host names[1]

assignment[1]

associated label

glossary[1]

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

audit logs

configuration for output[1]

events for which information is output[1]

glossary[1]

output format[1]

related to distribution by using Remote Install Manager[1]

storage format[1]

automatic ID group maintenance[1]

Automatic Installation Tool

functionalities[1]

automatic maintenance of destination group[1]

automatic maintenance policy files[1]

editing[1]

glossary[1]

inputting[1]

outputting[1]

automatic operations (JP1/AJS linkage)

collecting files from remote managed computers[1]

processing files[1]

redistributing files[1]

remotely installing files[1]

automatic updating of connection destinations[1]

B

Background installation mode[1], [2]

backup files

commands to manage backup files[1]

deleting[1]

backup status list

outputting[1]

backup system configuration information file[1]

base_fullpath[1]

batch specifying

schedule information[1]

binary operator[1]

bitwise AND operator[1]

bitwise operators[1]

bitwise OR operator[1]

break (statement)[1]

breakpoint[1]

Breakpoints Setup dialog box[1]

Build (menu)[1]

C

cabinet

glossary[1]

managing[1]

cabinet_id[1]

cabinet_name[1]

Cabinet for saving package[1]

cabinet ID

glossary[1]

Cabinet ID[1]

Cabinet name[1]

caption

glossary[1]

catAndValidatePackagingFile.exe command, combining split files[1]

Change ID Group Attribute dialog box[1]

Change Transmission Route dialog box[1]

changing

host attribute[1]

host name[1]

ID-management relay computer[1]

installation condition[1]

password[1]

system configuration information under management relay servers[1]

changing settings

for installed software[1]

checking

cabinet[1]

execution results[1]

log files[1], [2]

MAIN.LOG file[1], [2]

package[1]

stored packages[1]

Windows event log[1]

checking free disk space and other requirements

before installation[1]

checking installation applicability

according to user-specific conditions[1]

checking results of installation

on offline machine[1]

checking software installed on managed computer

before installation[1]

child window

glossary[1]

Citrix XenApp and Microsoft RDS server

glossary[1]

client_shutdown[1]

client_wake_up[1]

Client Control

notes on hardware[1]

notes on shutdown[1]

notes on startup[1]

notes on system configuration[1]

required settings[1]

Client Control function[1]

glossary[1]

Client Control page[1]

collected files[1]

glossary[1]

restoring[1]

collecting

files[1]

software information from agent for Mac[1]

software information from agent for UNIX[1]

system and software information from agent for Mac[1]

system and software information from agent for UNIX[1]

system configuration information under management relay server[1]

system information from agent for Mac[1]

system information from agent for UNIX[1]

Collection timing[1]

command error information (JP1/AJS linkage)

checking[1]

command execution (JP1/AJS linkage)

input/output information[1]

commands

distribution function that uses remote install manager[1]

dmpbkdel command[1]

dmpbklst command[1]

dmprcvry command[1]

managing backup files[1]

offline installation execution[1]

output file[1]

commands (JP1/AJS linkage)

input format[1]

types[1]

communication environment file

configuring[1]

comparison operators[1]

compile[1]

compress[1], [2]

compress_type[1]

Compress package data[1]

condition[1]

connection destination

automatically changing on agents[1]

automatically setting and changing[1]

constants[1]

continue (statement)[1]

control

glossary[1]

controller

glossary[1]

conventions

abbreviations for products[1]

acronyms[1]

fonts and symbols[1]

version numbers[1]

Create Destination dialog box[1]

Create Host dialog box[1]

Create ID Group dialog box[1]

Create Job dialog box

customizing[1]

pages[1]

creating

AIT file[1]

cabinet[1]

host groups[1], [2]

ID group file[1]

program product ID file[1]

system conditions[1]

system configuration information[1]

creating and executing

job[1]

CSV file output

managed information[1]

CSV File Output[1]

CSV File Output dialog box[1]

customizing

packaging environment[1]

D

data types[1]

bool[1]

float[1]

integer[1]

string[1]

date/time picker

glossary[1]

dcmcoll.exe command, collecting files[1]

dcmsusp.exe command, exporting to a CSV-formatted file[1]

dcmgpmnt.exe command, applying policies to all hosts in host group[1]

dcminst.exe command, creating and executing jobs[1]

dcmjbrm.exe command, deleting jobs[1]

dcmjexe.exe command, executing jobs[1]

dcmpack.exe command, executing packaging[1]

dcmpkget.exe command, making backup of packages[1]

dcmpkput.exe command, recovering packages by using backups[1]

dcmpkrm.exe command, deleting packages[1]

dcmrmgen.exe command, deleting job definitions[1]

dcmrtry.exe command, re-executing jobs[1]

dcmstat.exe command, acquiring job execution status[1]

dcmstsw.exe command, monitoring job execution status[1]

dcmsusp.exe command, suspending and resuming file transfer[1]

debugging[1]

AIT file[1]

stopping execution of AIT file at breakpoints[1]

stopping execution of AIT file at specific point[1]

stopping execution of AIT file before cursor line[1]

stopping execution of script in units of statements[1]

values of variables, changing[1]

values of variables, monitoring[1]

DEFINE[1]

Define New Job dialog box

customizing[1]

opening[1]

Delete by administrator[1]

Delete by instruction from higher manager[1]

Delete by uninstallation result[1]

Delete from System Configuration Information[1]

Delete Installed Package Information[1]

Delete Packages from Relay Computer[1]

deleting

cabinet[1]

computers[1]

hosts[1]

installed package information[1]

large numbers of computers[1]

package[1], [2]

target files[1]

deleting file

on management relay server[1]

on relay system[1]

deletion cause[1]

deletion history

deleting[1]

displaying[1]

managing[1]

outputting to CSV file[1]

restoring deleted hosts[1]

Deletion History of System Configuration Information dialog box[1]

deletion time[1]

destination_id[1]

destination group

automatic maintenance[1]

Destination page[1]

destinations

adding[1]

grouping[1]

notes on editing[1]

remarks on specifying[1]

searching for[1]

Destination window[1]

creating host groups[1]

ID-management Relay Computer tab[1]

registering hosts[1]

detailed package information

displaying[1]

detecting

file updates[1]

device information

glossary[1]

DHCP[1]

dialog box

Batch Setting for Installation Conditions[1]

Change Attributes[1]

Customize Default Settings[1]

External Program Options[1]

Register/Delete ID Group on ID-management Relay Computer[1]

directory[1]

displaying

all job details[1]

all jobs[1]

job status for each ID-management relay computer[1]

specified information only[1]

displaying or hiding

processing message dialog box[1]

Display processing message[1]

distributed software

installing[1]

distributing

software[1]

Distributing a file larger than 2 gigabytes[1]

distributing jobs

during suspension[1]

distribution

automatically distributing software to new computers[1]

distributable software[1]

Remote Install Manager[1]

split package distribution[1]

use in firewall environment[1]

use in multi-LAN environment[1]

using Remote Install Manager[1], [2]

with distribution or installation time specified[1]

distribution function

that uses remote install manager[1]

Distribution interval[1]

distribution using Remote Install Manager

glossary[1]

dmhost.txt[1]

dmz_path[1]

DNS[1]

domain

glossary[1]

do-while (statement)[1]

E

Edit ID group folder[1]

editing

program product ID file[1]

End status is notified by[1]

ERROR[1]

error handling[1]

example of coding[1]

error job

checking detailed information[1]

checking efficiently[1]

event

glossary[1]

event flag[1]

example of

changing connection destination of relay system defined as ID-management relay computer[1]

removing relay system defined as ID-management relay computer[1]

using API function[1]

example of using API

deleting carriage return and linefeed characters[1]

extracting character[1]

manipulating HKEY_CURRENT_USER registry key during remote installation[1]

Execute (Build menu)[1]

executing

automatically by linking with JP1/AJS[1]

Get system information from client job[1]

grouped hosts[1]

remote collection[1]

executing held jobs

how to[1]

execution timing

controlling[1]

glossary[1]

Immediately[1]

When System Starts up[1]

When System Stops[1]

Execution timing[1]

exit[1]

expiration_date[1]

expiration_days[1]

Expiration of package storage at the relay computer[1]

extended attributes

detailed information[1]

external_program_error_handler[1]

external_program_executed_after_installation[1]

external_program_executed_before_installation[1]

external_program_handler[1]

external program

execution privileges[1]

External Program[1]

F

facility for automatically registering the system configuration[1]

FILE_COLLECTION tag, specifying file to be collected[1]

file_path[1]

FILE_PROPERTIES tag, restoring file access permission[1]

file configuration

at restoration destination[1]

file for connection destinations[1]

file for higher system addresses

format[1]

glossary[1]

File Properties[1]

files

identifying software to be distributed[1]

remote collection[1]

storing created files[1]

file updates

detecting[1]

find

by dates[1]

by name[1]

Finder[1]

firewall

glossary[1]

supported types[1]

using distribution function[1]

flag[1]

focus

glossary[1]

folders[1]

changing names of[1]

deleting[1]

important notes on deleting[1]

ITDM2_Startup[1]

JP1_IT Desktop Management 2 - Agent[1]

managing, saved[1]

font conventions[1]

forced completion

split distribution jobs[1]

forced completion of split distribution[1]

format[1]

format of API function explanations[1]

format of message explanations[1]

for-next (statement)[1]

For Windows[1]

found hosts

copying from search results to Destination window[1]

function calls[1]

G

generating

PACKAGE_INFO section[1]

program product ID file[1]

generation[1]

Generation[1]

global variables[1]

example of using[1]

glossary[1]

agent[1]

agent configurations[1]

AIT file[1]

application gateway method[1]

asset management item[1]

associated label[1]

audit logs[1]

automatic maintenance policy file[1]

cabinet[1]

cabinet ID[1]

caption[1]

child window[1]

Citrix XenApp and Microsoft RDS server[1]

Client Control function[1]

collected file[1]

control[1]

controller[1]

date/time picker[1]

device information[1]

distribution using Remote Install Manager[1]

domain[1]

event[1]

execution timing[1]

file for higher system addresses[1]

firewall[1]

focus[1]

handle[1]

host[1]

host group[1]

host ID[1]

ID group[1]

ID group job[1]

ID-management relay computer[1]

installation mode[1]

ITDM-compatible distribution[1]

job[1]

JP1/AJS[1]

JP1/Base[1]

JP1/IM[1]

JP1 event[1]

managed computer[1]

management relay server[1]

management server[1]

managing server[1]

multicast address[1]

multicast distribution[1]

multicast group[1]

multiple LAN connections[1]

offline installation[1]

offline machine[1]

package (for distribution using Remote Install Manager)[1]

package ID[1]

Packager[1]

Package Setup Manager[1]

package type[1]

packaging[1]

packet filtering method[1]

policy[1]

relay system[1]

remote collection[1]

Remote Control Agent[1]

remote control function[1]

Remote Desktop[1]

remote installation[1]

Remote Install Manager[1]

split distribution[1]

system information[1]

tab order[1]

unarchiver[1]

unicast distribution[1]

updated program[1]

Wake on LAN[1]

goto (statement)[1]

group[1]

group_membership[1]

GUI installation mode[1], [2]

H

handle

glossary[1]

handling of termination notification

from external program[1]

Hitachi program product installation[1]

Hitachi program products[1]

holding jobs

how to[1]

notes[1]

host

glossary[1]

host_name[1]

host group

glossary[1]

overview[1]

host group (job execution)[1]

host group file[1], [2]

creating[1]

host groups

applying policies[1]

assigning policies[1]

creating from files[1], [2]

creating in Destination window[1]

editing[1]

example of creating[1]

hierarchy[1]

methods of creating[1]

modifying[1]

modifying by adding from a file[1]

outputting to files[1]

renaming[1]

host ID[1]

glossary[1]

host names

assigning[1]

defining[1]

hosts

deleting[1]

deleting found hosts from system configuration information[1]

editing[1]

moving[1]

searching by date[1]

searching by name[1]

hosts file[1]

I

ID group

glossary[1]

ID group (job execution)[1]

ID group file

creating[1]

ID group information

revising[1]

ID group job[1]

checking status[1]

glossary[1]

important notes on checking status of[1]

ID groups

automatic maintenance[1]

creating[1], [2]

Creating on a management server[1]

deleting[1]

editing[1]

example of changing connection destination of computer[1]

example of deleting computer from ID group linked with system configuration information[1]

notes on automatic maintenance[1]

notes on using[1]

outputting to file[1]

overview[1]

procedures[1]

registering from managing server[1]

registering managed computers directly[1]

registering managed computers from file[1]

removing registered computers[1]

setting policies[1]

use in hierarchical system[1]

using[1]

ID key

determining[1]

ID-management relay computer[1], [2]

action to take when automatic notification is delayed[1]

glossary[1]

if-else-endif (statement)[1]

IME operations[1]

information file for higher connection destinations[1], [2]

creating[1], [2]

creation example[1]

distributing to managed computers[1]

format[1]

notes[1]

relationship to other functions[1]

timing of connection destination changes[1]

information that can be printed

in the Destination window[1]

in the Job Status window[1]

in the Package window[1]

in the System Configuration window[1]

input/output information

command execution (JP1/AJS linkage)[1]

input format

commands (JP1/AJS linkage)[1]

installation

conditions[1]

operations, recording[1]

stand-alone computers[1]

installation_date_and_time[1]

INSTALLATION_METHOD tag, specifying installation mode[1]

installation_mode[1]

installation_timing[1]

Installation date/time[1]

Installation Method[1]

installation mode

glossary[1]

Installation mode[1]

installation modes[1]

Installation target directory[1]

Installed Packages window[1]

installer

specifying[1]

installer windows

acquiring properties[1]

checking properties of[1]

checking sequence of[1]

installing software

at specified time[1]

Install now[1]

Install package job[1]

INSTALLSOFTWARE_CONDITIONS tag, specifying software conditions[1]

Install when the system starts[1]

instruction end event

extended attributes[1]

instruction end event (linkage with JP1/IM)[1]

invalid flag[1]

IP addresses

defining[1]

IT Desktop Management 2 Unarchiver window[1]

ITDM2_Startup folder[1]

ITDM2LINST[1]

ITDM-compatible distribution

glossary[1]

items that can be output[1]

to CSV file[1]

items you should check[1]

J

JOB_ATTRIBUTE tag, setting job attributes[1]

JOB_CLIENT_CONTROL tag, specifying client control[1]

JOB_DESTINATION_ID tag, specifying ID groups[1]

JOB_DESTINATION tag, specifying job destination[1]

job_entry_date[1]

job_execution_date[1]

job_expiration_date[1]

job_folder[1]

job_generator[1]

JOB_SCHEDULE tag, specifying job schedules[1]

JOB_SPLIT_DELIVERY tag, specifying split package distribution[1]

Job Definition window[1]

job distribution

scope of suspension and resumption[1]

job end event (linkage with JP1/IM)[1]

job execution

after managed computer awakes from sleep mode[1]

notes[1]

job execution status

action to take after checking[1]

checking[1]

job hold facility[1]

using[1]

jobno[1]

Job page[1]

Job Retry dialog box[1]

jobs

Acquire collected files from relay computer[1], [2]

Batch delete packages on relay computer[1]

being deleted, displaying[1]

Cancel holding of report[1]

changing names of [1]

checking execution statuses[1]

Collect files from agent[1], [2]

controlling execution timing[1]

creating[1]

Delete collected files from relay computer[1], [2]

deleting[1], [2]

detailed settings[1]

example of job execution[1]

executing[1], [2], [3]

executing automatically by linking with JP1/AJS[1]

executing on grouped hosts[1]

execution sequence[1]

flow of job execution[1]

Get software information from computer (UNIX)[1]

Get system information from client[1]

Get system information from computer (UNIX)[1]

glossary[1]

Hold report[1]

important notes on deleting[1]

Install package[1]

managing[1], [2]

managing, saved[1]

mechanism of suspension and resumption[1]

modifying, saved[1]

overview[1]

Remote-collect files from agent to relay computer[1], [2]

Resume file transfer[1]

resuming[1]

saving[1], [2], [3]

Send package, allow client users to choose[1], [2]

Suspend file transfer[1]

suspending[1]

Transfer package to relay computer[1]

types that can be created[1]

with an error, re-executing[1]

job status

color[1]

displaying[1]

displaying all jobs under hierarchy[1]

displaying detailed information of all jobs under folder hierarchy[1]

displaying information in each hierarchy[1]

displaying jobs with a specific[1]

example transition of[1]

important notes on checking[1]

selecting displayed date/time items[1]

settings required for checking[1]

Setting up a monitoring interval of[1]

sorting information by specifying condition[1]

transition[1]

types of[1]

Job Status window[1]

items[1]

result[1]

status[1]

jobs under folder hierarchy

displaying detailed information[1]

job suspended function[1]

job type

relationship with specified destination[1]

JP1_IT Desktop Management 2 - Agent folder[1]

JP1/AJS

glossary[1]

linkage for automatic job execution[1]

JP1/Base

glossary[1]

JP1/IM

glossary[1]

JP1/IT Desktop Management 2 - Agent

distributing by remote installation[1]

JP1/IT Desktop Management 2 - Agent (agent)[1]

JP1/IT Desktop Management 2 Job Hold dialog box[1]

JP1/IT Desktop Management 2 Job Suspended dialog box[1]

JP1 events

attributes[1]

basic attributes[1]

extended attributes[1]

glossary[1]

types[1]

Jump to First Child Window[1]

Jump to Next Window[1]

Jump to Parent Window[1]

Jump to Previous Window[1]

K

keywords[1]

L

label (statement)[1]

linkage

with Packager[1]

with Remote Install Manager[1]

linking order[1]

List of Software Information window[1]

log data for entire JP1/IT Desktop Management 2 - Agent[1]

log data relating to automatic change of connection destinations[1]

log files[1]

logical AND operator[1]

logical operators[1]

logical OR operator[1]

M

macros[1]

for check operations[1]

for directory operations[1]

for error logging[1]

for file operations[1]

for IME operations[1]

for message operations[1]

for registry operations[1]

for utility operations[1]

for window operations[1]

MAIN[1]

maintaining

system configuration information[1]

maintenance

automatic ID group maintenance[1]

automatic maintenance of destination group[1]

example of maintenance[1]

examples of managing newly added computers[1]

host groups[1]

maintaining performance levels[1]

notes on automatic ID group maintenance[1]

system configuration information[1]

managed computers

deploying in environment where higher system name cannot be resolved[1]

displaying execution status for[1]

glossary[1]

grouping[1]

registering in ID group[1]

setting up[1]

unregistering from ID group[1]

managed information

outputting[1]

outputting to CSV file[1]

printing[1]

manage host names[1]

management relay server

glossary[1]

management server

glossary[1]

managing

ID group on management relay server[1]

jobs[1]

same ID group for multiple managing servers[1]

system configuration information[1]

managing server

glossary[1]

menu items[1]

operating[1]

starting[1]

stopping[1]

managing software information of agents for Mac[1]

managing software information of agents for UNIX[1]

managing system information of agents for Mac[1]

managing system information of agents for UNIX[1]

Managing Updates[1]

menu item

Package Setup Manager[1]

Register in ID Group[1]

menus

Remote Install Manager[1]

Unarchiver[1]

messages

checking[1]

displayed during editing[1]

displayed during execution of AIT files[1]

displayed during parsing of AIT files[1]

Monitor the time of the external program[1]

moving

hosts[1]

multi-assignment[1]

multicast address[1]

glossary[1]

multicast distribution[1], [2]

concept[1]

configuring[1]

creating jobs[1]

executing[1]

glossary[1]

jobs distributed using multicast distribution[1]

notes[1]

overview[1]

required network configuration[1]

required system configuration[1]

routes used[1]

settings[1]

setup[1]

standard system configuration[1]

multicast group[1]

glossary[1]

multi-LAN environment

using distribution function[1]

multiple LAN connections

glossary[1]

multiplying operators[1]

multi-polling[1]

multi-polling environment

creating on agent[1]

notes[1]

N

network

adjusting number of computers targeted by jobs[1]

adjusting number of concurrently connected hosts[1]

adjusting number of concurrently connected relay systems[1]

minimizing load[1]

setting up TCP/IP environment[1]

network environment[1]

node identification key[1]

using host names[1]

using IP addresses[1]

notes

installation process stops responding[1]

installing other companies' software[1]

installing software manually[1]

on executing remote collection[1]

password protection[1]

split distribution[1]

notes on

changing system configuration information[1]

packaging[1]

split distribution[1]

starting external program on agent for UNIX[1]

using JP1/IT Desktop Management 2 - Agent[1]

notes on performing

offline installation[1]

remote installation[1]

notes on use

reserved words[1]

O

offline installation[1], [2]

glossary[1]

procedure[1]

offline machine

glossary[1]

omitting

AIT file[1]

on using agent functions

notes[1]

operating

Package Setup Manager[1]

operators[1]

adding operators[1]

bitwise operators[1]

comparison operators[1]

logical AND operator[1]

logical operators[1]

logical OR operator[1]

multiplying operators[1]

priority[1]

unary minus[1]

unary not[1]

unary plus[1]

Options[1]

OPTION tag, specifying options[1]

other companies' software[1]

OUTPUT_CONSTRAINTS tag, specifying the output information[1]

Output Deletion History to CSV File dialog box [1]

output file

commands[1]

outputting

audit logs related to distribution by using Remote Install Manager[1]

management information[1]

to CSV file[1]

output window[1], [2]

overview

automatic operations linked with JP1/AJS[1]

P

package

deleting from management relay server[1]

deleting from relay system[1]

deleting on management relay server[1]

deleting on relay system[1]

managing[1]

scheduling execution of multiple packages[1]

transferring to managing relay server[1]

transferring to relay system[1]

transferring to relay system or management relay server[1]

package_code[1]

package_id[1]

PACKAGE_INFO[1]

PACKAGE_INFO section

generating[1], [2]

package_name[1]

package (for distribution using Remote Install Manager)

glossary[1]

Package conditions[1]

Package Conditions[1]

package ID

glossary[1]

Package ID[1]

Package information[1]

Package Information dialog box[1]

Package Information tool[1]

package installation

using Package Setup Manager[1]

Package name[1]

Packager

glossary[1]

Package Setup Manager[1]

automatic installation[1]

glossary[1]

manual installation[1]

operating[1]

Package Setup Manager window

configuration[1]

package type[1]

glossary[1]

Package type[1]

Package window[1]

packaging

another company's software[1]

available installation conditions[1]

glossary[1]

method[1]

procedure[1]

PACKAGING_INFORMATION tag, setting package information[1]

PACKAGING_SOURCE tag, specifying file to be packaged[1]

packaging directory[1]

packaging Hitachi program products

from Hitachi Integrated Installer[1]

packet filtering firewall[1]

packet filtering method

glossary[1]

page

Acquisition Target[1]

AIT File Settings[1]

Directory[1]

External Program[1]

File Properties[1]

Installation Method[1]

Options[1]

Package Attributes[1]

Package Conditions[1]

Packaging Information[1]

Processing Message[1]

Schedule[1]

Search Target[1]

Select Components[1]

Software Conditions[1]

System Conditions[1]

parameter file (JP1/AJS linkage)

creating[1]

format[1]

parameter files

commands[1]

tags[1]

parameters

condition[1], [2], [3]

pausing and resuming recording[1]

performing

remote installation[1]

performing installation

on computers that are not running[1]

on offline machine[1]

performing operations

agent (JP1/IT Desktop Management 2 - Agent)[1]

performing remote installation

by bypassing faulty relay system[1]

permission[1]

policy[1]

applying to host groups[1]

assigning to host groups[1]

creating from files[1]

example of creating[1]

glossary[1]

setting ID group policies[1]

polling

creating multi-polling environment on agent[1]

hot standby[1]

multiple hosts[1]

selecting polling method[1]

setting up multi-polling environment on agent[1]

PPDEFAIT.DMP[1]

PPDEFAIT.DMP (program product ID file)[1]

preparing

installation media[1]

preventing damage to old version

due to remote installation failure[1]

printable

items[1]

printing

managed information[1]

management information[1]

method[1]

priority[1]

priority of operators[1]

problem

taking action[1]

procedure for packaging

other software programs[1]

processing_dialog[1]

program flow control[1]

program product ID file[1], [2]

creating[1]

editing[1]

format[1]

generating[1]

properties, acquiring

control[1]

window[1]

R

reboot[1]

recorded results

specifying[1]

Recorder[1]

procedure for recording your installation operations[1]

Recorder dialog box[1]

recording

installation operation requesting OS to be restarted[1]

recording installation operations[1]

reducing amount of packets

sent by job[1]

registering

ID group in ID-management relay computer[1]

managed computer in ID group[1], [2]

registering managed computer in ID group

notes[1]

when managed computer is connected to ID-management relay computer[1]

when managed computer is not connected to ID-management relay computer[1]

Relaying system integration procedure[1]

relay system

executing job avoiding failed [1]

glossary[1]

operation during remote installation[1]

using[1]

remote collection

general procedure[1]

glossary[1]

job types[1]

operation examples[1]

operations[1]

overview[1]

Remote Control Agent

glossary[1]

remote control function

glossary[1]

using[1]

Remote Desktop

glossary[1]

remote installation[1]

detecting errors[1]

distributing JP1/IT Desktop Management 2 - Agent[1]

glossary[1]

job types[1]

operation example[1]

procedure[1]

remote installation (JP1/AJS linkage)

retrying[1]

remote installation process

general procedure[1]

remote installation using AIT file[1]

procedure for[1]

Remote Install Manager

arranging windows[1]

basic operations[1]

closing[1]

glossary[1]

launching tools[1]

opening new window[1]

overview of distribution[1]

starting[1]

window structure[1]

removing

ID group from ID-management relay computer[1]

renaming

cabinet[1]

Replace existing package[1]

reserved words

examples of use[1]

how to specify[1]

notes on use[1]

Restart computer after installation[1]

restarting

running job[1]

restoration

retrying[1]

restore[1]

Restore dialog box[1]

Restore old version when upgrade failed[1]

restoring

collected files[1]

files[1]

restrictions

installation with non-Administrator user permissions[1]

Resume file transfer job[1]

retention period[1]

return code

example of coding for setting[1]

setting[1]

revising

ID group information[1]

rimfindn.log[1]

routes

changing[1]

row[1]

S

Schedule[1]

scheduled distribution[1]

Schedule page[1]

SCHEDULE tag, specifying schedule of remote installation[1]

finding[1]

searching

by date[1]

by name[1]

copying found hosts from search results to Destination window[1]

deleting hosts from search results[1]

searching for

system configuration information[1]

sections[1]

overview[1]

Select Components[1]

Set Display dialog box[1]

setting distribution date and time

in two stages[1]

setting up

Collect File page[1]

facility for automatically registering the system configuration[1]

Job Distribution Attributes page[1]

Package page[1]

software

distribution by remote installation[1]

installation tailored to user circumstances[1]

installing on stand-alone computers[1]

notes on manual installation[1]

SOFTWARE_CONDITIONS tag, specifying package conditions[1]

Software Conditions[1]

software installation status

checking[1]

software to be distributed

files for identifying[1]

Sort Order dialog box[1]

source_path[1]

special characters[1]

specifying

files for identifying software to be distributed[1]

installer[1]

output range[1]

output range for CSV file[1]

package details[1]

remote collection options[1]

split_size[1]

split distribution[1]

forced completion[1]

glossary[1]

split distribution jobs

forcibly completing[1]

split package distribution[1]

Split size[1]

splitting package

before distribution[1]

Start external program[1]

Start external programs on the agent[1]

starting

Packager[1]

starting Automatic Installation Tool[1]

Start Remote Control dialog box[1]

status of waiting for registering in ID group[1]

canceling[1]

status of waiting for unregistering from ID group[1]

canceling[1]

Step by Step (Debug menu)[1]

Stop Debugging (Debug menu)[1]

storing created files[1]

Suspend file transfer job[1]

suspending

running job[1]

switch-endswitch (statement)[1]

symbol conventions[1]

Syntax Check[1]

system

examples of operation[1]

SYSTEM_CONDITIONS tag, specifying system conditions[1]

System conditions[1]

System Conditions[1]

system configuration information[1]

checking[1]

creating[1]

creating automatically[1]

creating in System Configuration window[1]

editing[1]

example of linking with ID group information[1]

example of maintenance[1]

example of managing newly added computers[1]

linking with ID group information[1]

maintaining[1]

maintenance[1]

managing[1]

managing deletion history[1], [2]

modifying[1]

notes on automatic creation[1]

notes on building system[1]

notes on editing[1]

notes on linking with ID group information[1]

outputting to file[1]

procedure for linking with ID group information[1]

restoring deleted hosts[1]

TCP/IP settings for automatic creation[1]

updating by outputting to a file[1]

system configuration information file[1]

using to update system configuration information[1]

System Configuration window[1]

Attributes tab[1]

Installed Packages tab[1]

List tab[1]

system design[1]

system information

glossary[1]

T

tab

Attributes[1]

List[1]

Package Contents[1]

tab order

glossary[1]

tags

FILE_COLLECTION[1]

FILE_PROPERTIES[1]

INSTALLATION_METHOD[1]

INSTALLSOFTWARE_CONDITIONS[1]

JOB_ATTRIBUTE[1]

JOB_CLIENT_CONTROL[1]

JOB_DESTINATION[1]

JOB_DESTINATION_ID[1]

JOB_SCHEDULE[1]

JOB_SPLIT_DELIVERY[1]

OPTION[1]

OUTPUT_CONSTRAINTS[1]

PACKAGING_INFORMATION[1]

PACKAGING_SOURCE[1]

SCHEDULE[1]

SOFTWARE_CONDITIONS[1]

SYSTEM_CONDITIONS[1]

types[1]

USER_PROGRAM_INSTALLATION_CONDITIONS[1]

tags (JP1/AJS linkage)

how to specify[1]

taking action if problem occurs[1]

TCP/IP

checking settings[1]

TCP/IP environment

setting up[1]

template[1]

terminating Automatic Installation Tool[1]

termination notification

from external program[1]

timeout[1]

time-out

AIT file[1]

Time-out[1]

toolbar buttons

Jump to First Child Window[1]

Jump to Next Window[1]

Jump to Parent Window[1]

Jump to Previous Window[1]

tools

launching from Remote Install Manager[1]

operation example of starting[1]

registering in Start Tools menu[1]

starting from Start Tools menu[1]

Transfer package to relay computer job[1]

troubleshooting[1]

AIT[1]

jobs[1]

JP1/IT Desktop Management 2 - Agent[1]

JP1/IT Desktop Management 2 - Manager[1]

type conversion[1]

U

unarc_path[1]

unarchiver[1]

glossary[1]

unary minus[1]

unary not[1]

unary operator[1]

unary plus[1]

unicast distribution[1]

concept[1]

glossary[1]

UNIX Shared[1]

unregistering[1]

managed computer from ID group[1]

unsuspended[1]

updated program

glossary[1]

USER_PROGRAM_INSTALLATION_CONDITIONS tag, specifying external programs[1]

user permissions[1]

user programs and data[1]

using reserved words

examples[1]

V

variables[1]

version_revision[1]

Version/revision[1]

version number conventions[1]

viewing

information about deleted computers[1]

W

wait[1]

wait_code[1]

wait_time[1]

Wake on LAN

glossary[1]

required settings[1]

Watch window[1]

When System Stops[1]

When the agent starts[1]

while-loop (statement)[1]

While the agent is running[1]

window

conditions for identifying[1]

window flag[1]

window processing[1]

example of automatically generated codes[1]

Window Properties dialog box[1]

Window Properties tool[1]

WINS[1]

working directory[1]