(a) Description

The Backup function obtains a backup of the software that has already been installed and has a version different from the software you want to remotely install.

(b) Format

Backup()

(c) Arguments

None

(d) Return value

None

(a) Description

The Collection function remotely collects the specified directory or file.

At least three collection functions must be called with a collect file. First, call a Collection function specifying COLLECTION_START as the argument to initialize the setting for remote collection. Then, call a Collection function specifying a file or directory in the argument to set the file or directory to be remotely collected. This Collection function can be repeated up to 100 times to set more than one file or directory. Last, call a Collection function specifying COLLECTION_END as the argument to execute the collection.

(b) Format

Collection(COLLECTION_START)
Collection(String name-of-directory-or-file-to-be-remote-collected)
Collection(COLLECTION_END)

(c) Arguments

• String name-of-directory-or-file-to-be-remote-collected
  Specify the name of the directory or file to be remotely collected, with its full pathname from the drive name. When the pathname specifies a file, the file is remotely collected. When the pathname specifies a directory, all the files in the directory are remotely collected.
  You can specify the pathname either directly with a character string or with a character string-type variable containing a directory name or file name. The drive name can be specified with a number such as 1: and 2:, as well as with an alphabetic character such as c: and D:. When the drive name is specified with a number, 1: indicates the first hard disk drive.
  When the following keywords are specified in the argument of the Collection function, they indicate special directories such as a directory where Windows is installed:
  

  %WINDOWS%

  The directory in which Windows is installed.

  %SYSTEM%

  The System or System32 directory in the directory in which Windows is installed.

  %NETMDMP%

  The directory in which JP1/Software Distribution is installed.

(d) Return value

None

(a) Description

The CreateIcon function adds an icon to Program Manager. Specify the program group to which you want to add an icon, the executable file to be added, and the title of the icon.

This function cannot be used in the background installation mode.

(b) Format

CreateIcon(String program-group-name,
           String pathname-of-executable-file,
           String icon-title)

(c) Arguments

• String program-group-name
  Specify the name of the program group to which an icon is to be added. You can specify a program group name directly or a variable containing a program group name.
  The maximum allowable number of characters in a program group name is 30.
  If the specified program group is not found, a new group is created with the specified name.
  
• String pathname-of-executable-file
  Specify the executable file whose icon is to be added, with its full pathname from the drive name. You can specify a pathname directly, or a variable containing a pathname. The maximum allowable number of characters in the pathname of an executable file is 128.
  The drive name can be specified with a number such as 1: and 2:, as well as an alphabetic character such as c: and D:. When the drive name is specified with a number, 1: indicates the first hard disk drive.
  
• String icon-title
  Specify the title of an icon. You can specify the title of an icon directly or a variable containing the title of an icon. The maximum allowable number of characters in an icon title is 40.
  

(d) Return value

None

(e) Notes

This function cannot be used to install other companies' software or Hitachi program products.

(a) Description

The CreateProgramGroup function creates a program group in Program Manager, with the name you specified.

This function cannot be used in the background installation mode.

(b) Format

CreateProgramGroup(String program-group-name)

(c) Arguments

• String program-group-name
  Specify the name of the program group to be created. You can specify a program group name directly or a variable containing a program group name.
  The maximum allowable number of characters in a program group name is 30.
  

(d) Return value

None

(e) Notes

This function cannot be used to install other companies' software or Hitachi program products.

(a) Description

The CreateShortCut function creates a shortcut at the destination of remote installation. This function can be used only when the destination of remote installation uses Windows Me, Windows 98, or Windows 95.

This function cannot be used in the background installation mode.

(b) Format

CreateShortCut(String pathname-of-shortcut-creating-folder,
String pathname-of-shortcut-original-file,
String shortcut-title)

(c) Arguments

• String pathname-of-shortcut-creating-folder
  Specify the pathname of the folder at the destination of remote installation, in which you want to create a shortcut. You can specify a pathname directly, or a variable containing a pathname. The maximum allowable number of characters in the pathname of this folder depends on the number of characters in shortcut-title. The total number of characters in the pathname of the folder and the shortcut title cannot exceed 255.
  
• String pathname-of-shortcut-original-file
  Specify the full pathname of the executable file whose shortcut is to be created. You can specify a full pathname directly, or a variable containing a full pathname. The maximum allowable number of characters is 259.
  
• String shortcut-title
  Specify the title of a shortcut. You can specify a shortcut title directly or a variable containing a shortcut title. The maximum allowable number of characters in the shortcut title depends on the number of characters in pathname-of-shortcut-creating-folder. The total number of characters in the pathname of the folder and the shortcut title cannot exceed 255.
  

(d) Return value

None

(a) Description

The DelBackup function deletes the backup obtained by the Backup function. If this function is called when the backup is not obtained, the call does not result in an error and is ignored.

(b) Format

DelBackup()

(c) Arguments

None

(d) Return value

None

(a) Description

The DmSetStatus function sets the specified character string as the error status code (the end status for the distribution management system of UNIX). Set an error status code when you want to make the script terminate if the condition is not satisfied. The error status code you set is reported to the distribution management system as the termination code of the installation or collection.

(b) Format

DmSetStatus(System error-status-code)

(c) Arguments

• System error-status-code
  Specify one of the system variables shown in the following table.
  

  Table D-3 System variables

  System variable	Description
  INSTALL_CAPAERROR	A condition is not satisfied when the hard disk capacity is checked: (End status 1 = 0x92) (End status 2 = 0x03)
  INSTALL_HENVERROR	A condition is not satisfied when the hardware environment is checked: (End status 1 = 0x9d) (End status 2 = 0x02)
  INSTALL_SENVERROR	A condition is not satisfied when the version of MS-DOS or Windows is checked: (End status 1 = 0x9d) (End status 2 = 0x03)
  INSTALL_PSVRERROR	A condition is not satisfied when the versions of the prerequisite programs are checked: (End status 1 = 0x9d) (End status 2 = 0x04)

  The higher system can obtain a correct error status only when the DmSetStatus function is issued when any of these errors is detected. These error status codes cannot be used in collection scripts.
  

(d) Return value

None

(a) Description

The GetBackupStatus function returns whether or not the backup is obtained by the remote installation.

(b) Format

System GetBackupStatus()

(c) Arguments

None

(d) Return value

• System system-variable
  A system variable is returned that indicates whether or not the backup is obtained. The return value can be compared using the comparison operator = or <>.
  

  TRUE

  The backup is obtained.

  FALSE

  The backup is not obtained.

(a) Description

The GetErrorStatus function checks where an error occurred in the script. This function can be used only in On InstallError statements and On CollectionError statements.

(b) Format

System GetErrorStatus()

(c) Arguments

None

(d) Return value

• System error-occurrence-place
  A system variable is returned that indicates where an error occurred.
  These system variables can be used in comparison expressions using the sign = or <>. The following table shows error locations.
  

  Table D-4 List of error locations

  System variable	Description
  BACKUP_PROCESS	An error occurred during execution of a Backup function.
  COLLECTION_PROCESS	An error occurred during execution of a Collection function.
  CREATEICON_PROCESS	An error occurred during execution of a CreateIcon function.
  CREATEPROGRAMGROUP_PROCESS	An error occurred during execution of a CreateProgramGroup function.
  CREATESHORTCUT_PROCESS	An error occurred during execution of a CreateShortCut function.
  GETBACKUPSTATUS_PROCESS	An error occurred during execution of a GetBackupStatus function.
  INSTALL_PROCESS	An error occurred during execution of an Install function.
  MISC_PROCESS	An error occurred somewhere else in the script.
  MSGBOX_PROCESS	An error occurred during execution of an MsgBox function.
  NO_ERROR	No error has occurred.
  RESTORE_PROCESS	An error occurred during execution of a Restore function.
  SETSTATUS_PROCESS	An error occurred during execution of a SetStatus function.
  SETUP_PROCESS	An error occurred during execution of a Setup function.
  SHELL_PROCESS	An error occurred in the user program activated by a Shell function, or an error occurred during execution of a Shell function.
  SYSINFOCOPROCESSOR_PROCESS	An error occurred during execution of a SysInfoCoProcessor function.
  SYSINFOCPUTYPE_PROCESS	An error occurred during execution of a SysInfoCpuType function.
  SYSINFOHDEMPTY_PROCESS	An error occurred during execution of a SysInfoHDEmpty function.
  SYSINFOMEMORY_GDIMEMORY_PROCESS	An error occurred during execution of GDI_MEMORY (system information type) of a SysInfoMemory function.
  SYSINFOMEMORY_REALMEMORY_PROCESS	An error occurred during execution of REAL_MEMORY (system information type) of a SysInfoMemory function.
  SYSINFOMEMORY_USERMEMORY_PROCESS	An error occurred during execution of USER_MEMORY (system information type) of a SysInfoMemory function.
  SYSINFOOSVERSION_MSDOS_PROCESS	An error occurred during execution of MSDOS (system information type) of a SysInfoOSVersion function.
  SYSINFOOSVERSION_WINDOWS_PROCESS	An error occurred during execution of WINDOWS (system information type) of a SysInfoOSVersion function.
  VERINFO_PROCESS	An error occurred during execution of a VerInfo function.
  VERINFOEX_PROCESS	An error occurred during execution of a VerInfoEx function.

(a) Description

The GetResourceName function obtains the package ID of the software to be installed.

(b) Format

String GetResourceName()

(c) Arguments

None

(d) Return value

• String package-ID
  The package ID of the software to be installed is returned. The return value can be used for character string and comparison operations.
  

(a) Description

The GetResourceVersion function obtains the version and the generation number of the software to be installed.

(b) Format

String GetResourceVersion()

(c) Arguments

None

(d) Return value

• String version
  The version and the generation number of the software to be installed are returned in a vvrrssgggg format.
  

  vvrrss

  Version

  gggg

  Generation number

  Only a user-specified portion is returned. When the user has set only the vvrr portion, only vvrr is returned.
  

(a) Description

The GetSoftwareName function obtains the package name of the software to be installed.

(b) Format

String GetSoftwareName()

(c) Arguments

None

(d) Return value

• String package-name
  The package name of the software to be installed is returned. The return value can be used for character string and comparison operations.
  

(a) Description

The GetStatus function obtains the current value of the status set by the SetStatus function.

(b) Format

Integer GetStatus()

(c) Arguments

None

(d) Return value

• Integer current-status
  The value of the status set by the SetStatus function is returned.
  

(e) Notes

When the status has not set by the SetStatus function, 0 is returned.

(a) Description

The Install function installs (restores) the distributed software.

(b) Format

Install(String destination-directory-character-string)

(c) Arguments

• String destination-directory-character-string
  Specify the name of the destination directory with its full pathname from the drive name. You can specify a directory name directly, or a variable containing a directory name. The maximum allowable number of characters in a directory name is 128.
  The drive name can be specified with a number such as 1: and 2:, as well as an alphabetic character such as c: and D:. When the drive name is specified with a number, 1: indicates the first hard disk drive.
  If you use a Setup function in the same script, always specify the SETUP_DIRECTORY system variable.
  

(d) Return value

None

(e) Examples

Example 1: To specify a drive name with a number:

  :
Install("1:\users\home\instdir")
  :

Example 2: To specify a Setup function also:

  :
Install(SETUP_DIRECTORY)
  :
Setup()
  :

(f) Notes

You cannot write multiple Install functions in the same script.

(a) Description

The LogFile function outputs a specified message to the log files. The output destinations are LOG\MAIN.LOG and LOG\USER.LOG under the directory in which the client is installed. Use MAIN.LOG to check the messages in connection with the message log for the client. Use USER.LOG to check only the messages output by the script writer. This log is also collected in the event log of Windows NT (assigned an event ID of 60000 or more).

Example of an item in LOG\MAIN.LOG:

100 2004/2/3 22:29:12:13 Informational User user-message: PROGRAM XXX UPDATED

Example of an item in LOG\USER.LOG:

150 2004/2/3 22:29:12:13 1128 PROGRAM XXX UPDATED

(b) Format

LogFile(String message)

(c) Arguments

• String message
  Specify the character string as a message to be output to the log files. You can specify a character string directly, or a variable containing a character string. The maximum allowable number of characters in the character string is 128.
  

(d) Return value

None

(e) Notes

Use the LogFile function sparingly. Excessive use of the LogFile function increases disk I/O, and performance may suffer.

(a) Description

The MsgBox function displays a specified message in a dialog box. The button displayed on the dialog box is OK only.

This function cannot be used in the background installation mode.

(b) Format

MsgBox(String message, Integer display-time)

(c) Arguments

• String message
  Specify a message character string to be displayed in a message box. You can specify the character string as a message directly, or a variable containing a character string. The maximum allowable number of characters in the character string is 128.
  
• Integer display-time
  Specify in seconds how long the message box is displayed. You can specify the number of seconds directly, or an integer-type variable containing the number of seconds. Between 1 and 60 inclusive can be specified.
  The message box is automatically closed when the display time specified by this argument passes even if the user does not click OK.
  

(d) Return value

None

(a) Description

The Restore function restores the previous version of the software from its backup created before the software was remotely installed. If this function is called when the backup has not been created, the call does not result in an error and is ignored. When this function is coded in an On InstallError Do statement, the restoration from the backup is performed only if an error occurs during remote installation.

(b) Format

Restore()

(c) Arguments

None

(d) Return value

None

(a) Description

The SetStatus function allows you to store the script processing status as a status code. The status code you store can be obtained by the GetStatus function.

When the script terminates, the status code set last is reported to the distribution management system as the termination code of the installation or collection.

(b) Format

SetStatus(Integer status-code)

(c) Arguments

• Integer status-code
  Specify a status code for indicating the script processing status. You can specify a status code directly or an integer-type variable containing a status code. A value of 0 to 255 can be specified as a status code.
  

(d) Return value

None

(e) Notes

A status code of 0 is assumed until the first SetStatus function is executed in the script.

(a) Description

The Setup function activates a setup program using the files restored by the Install function.

Most of the setup programs for Windows applications are GUI based. To use a GUI-based setup program with JP1/Software Distribution, create either an AIT file or a recorder file (a Visual Test script). This file is necessary for the system to respond to the screens at the client automatically. The Automatic Installation Tool executable program library automatically responds to the GUI setup program, using the AIT file, or the Visual Test executable program library automatically responds using the recorder file.

For details about how to create an AIT file or recorder file, see the manual Automatic Installation Tool Description and Reference.

This function cannot be used in the background installation mode.

(b) Format

Setup()

(c) Arguments

None

(d) Return value

None

(e) Notes

• Normally, this function is used for setup of other companies' software or Hitachi program products. However, this function can be used to respond automatically for user programs and data if a GUI-based setup program is used.
• You cannot write multiple Setup functions in the same script.

(a) Description

The Shell function activates an external program.

(b) Format

Shell(String full-pathname-of-program)

(c) Arguments

• String full-pathname-of-program
  Specify the full pathname of the external program to be started. You can specify a full pathname directly, or a character-type variable containing a full pathname. A space included in a full pathname must be enclosed in two consecutive double quotes (").
  The full pathname needs to begin from a drive name. If you omit a drive name, the drive where JP1/Software Distribution is installed is assumed. The drive name can be specified with a number such as 1: and 2:, as well as an alphabetic character such as c: and D:. When the drive name is specified with a number, 1: indicates the first hard disk drive. If an argument of an external program contains a double quote ("), replace it with two consecutive double quotes (").
  You can include the arguments to the external program in the full pathname.
  When remote installation is performed in the background installation mode (in Windows NT), the external program to be activated must be a program that does not have a console mode (does not have windows). If a program that has a GUI is started in the background installation mode (Windows NT), the GUI is not displayed.
  

(d) Return value

None

(e) Examples

Example 1

Shell("c:\winnt\system32\notepad.exe")

Example 2

Dim S As String
S = "1:\users\home\prog01.exe file01.txt"
Shell(S)

Example 3

Shell("""c:\Program Files\prog2.exe""")

Example 4

Shell("""c:\Program Files\Test\aaa.exe"" /f C:\temp\bbb.exe /I: /S ""ccc.txt""")

(f) Notes

• Because remote collection is executed in the background, the collection script cannot specify the program on the GUI in those cases in which Windows NT is being used as the operating system.
• When an external program is to notify the installation script of an error, the end notification must be transmitted to a predetermined external program.
• If the processing results from an external program are not to be reported to the installation script, Packager or Remote Installation Manager should be set up so that it ignores any termination code. If abnormal termination of the external program is reported to the script, the script suspends the processing, and notifies the server that the job failed. In this case, the processing result code from the external programs is assigned to the user status.
• Based on whether a timeout value or a monitoring time value is set, in Packager or Remote Installation Manager, for the external program, the installation program monitors the external program. When a specified monitoring time limit is exceeded, the Shell function returns control. Whether the job is to be indicated as an error can be specified in Packager or Remote Installation Manager.

(a) Description

The SysInfoCoProcessor function returns whether or not the coprocessor exists.

(b) Format

System SysInfoCoProcessor()

(c) Arguments

None

(d) Return value

• System coprocessor-indicator
  A system variable that indicates whether or not the coprocessor exists is returned. The system variable can be used for comparison using the sign = or <>.
  

  EXIST

  Coprocessor exists.

  NOEXIST

  Coprocessor does not exist.

  Windows always returns EXIST.
  

(e) Notes

If you attempt to perform remote installation to Windows without including the presence of the coprocessor in the system conditions, the script results in an error because the system conditions are not satisfied.

(a) Description

The SysInfoCpuType function obtains the CPU type.

(b) Format

System SysInfoCpuType()

(c) Arguments

None

(d) Return value

• System CPU-type
  A system variable that indicates the CPU type is returned.
  
  • I_286: AMD64/Intel EM64T
  • I_386: Intel i386 or the equivalent
  • I_486: Intel i486 or the equivalent
  • I_PENTIUM: Intel Pentium or the equivalent
  • M_MIPS: Intel IPF
  • P_POWERPC: PowerPC
  These return values can be compared as system-type variables by using the equal sign (=) or inequality signs (<>).
  

(e) Notes

For an Intel-compatible CPU, such as Crusoe, I_PENTIUM is returned.

(a) Description

Obtains the amount of free space in a specified hard disk.

(b) Format

Integer SysInfoHDEmpty(System drive-name)

(c) Arguments

• System drive-name
  Specify the name of the drive on which you want to check the free space. You can specify a drive name directly, or a system-type variable containing a drive name.
  The drive name can be specified with a number such as 1: and 2:, as well as an alphabetic character such as c: and D:. When the drive name is specified with a number, 1: indicates the first hard disk drive.
  A drive name always requires a colon (:).
  

(d) Return value

• Integer free-space
  The amount of the free space in the hard disk is returned in megabytes.
  

(a) Description

The SysInfoMemory function obtains the size of a specified type of memory. Specify the type of memory in the argument.

(b) Format

Integer SysInfoMemory (memory-type)

(c) Arguments

• memory-type
  Specify one of the following memory types.
  

  Table D-5 Memory types

  Memory type	Description
  REAL_MEMORY	Obtain the real memory size.
  USER_MEMORY	Obtain the size of memory available for the user. This value differs depending on the number of applications running.
  GDI_MEMORY	Obtain the size of the GDI system resource that can be used. This value is 64 kilobytes at the maximum.

(d) Return value

• Integer memory-size
  The size of the memory is returned. The units of memory differ depending on the memory type as shown below:
  

  REAL_MEMORY

  Megabytes

  USER_MEMORY, GDI_MEMORY

  Kilobytes

(a) Description

The SysInfoOSVersion function obtains the version of the operating system in use. Specify the type of operating system.

(b) Format

String SysInfoOSVersion(operating-system-type)

(c) Arguments

• operating-system-type
  Specify either of the following operating system types:
  

  MSDOS

  Obtain the version of MS-DOS in use.

  WINDOWS

  Obtain the version of the Windows in use.

(d) Return value

• String version
  The version of the operating system in use is returned in the vvrr format. Return values can be used as a character string type in character string operations and comparison operations.
  

  vv

  Version

  rr

  Revision

  Example

  Windows 95 is represented by 0400.

(e) Notes

• The return value can be used for comparison by employing a comparison operator such as > and >= in an If statement.

(a) Description

The VerInfo function returns the version of the software specified by package-ID. Specify ACTIVE_VERSION (currently operating new version) as the version type.

(b) Format

String VerInfo(version-type, String package-ID)

(c) Arguments

• version-type
  Specify the following system variable:
  ACTIVE_VERSION: Currently operating version
  
• String package-ID
  Specify the package ID specified when the package is cataloged using JP1/Software Distribution. You can specify a character string as a package ID directly, or a variable containing a package ID.
  The maximum allowable number of characters in a package ID is 44.
  

(d) Return value

• String software-version
  The version of the specified software is returned in the vvrrssgggg format.
  

  vvrrss

  Version

  gggg

  Generation number

  If the specified software is not found, is returned. Not all of vvrrssgggg is always returned, and only the portion the user has set is returned. When the user has set only the vvrr portion, only vvrr is returned.
  

(e) Notes

This function obtains the version of the software installed using JP1/Software Distribution. For the software directly installed from media such as floppy disks, the version cannot be obtained by this function.

(a) Description

The VerInfoEx function obtains the version of an already installed package from the package name or package ID.

(b) Format

String VerInfoEx(PACKAGE_NAME, String package-name)
String VerInfoEx(PACKAGE_ID, String package-ID)

(c) Arguments

• PACKAGE_NAME or PACKAGE_ID
  Specify the PACKAGE_NAME system variable to check the version of the software from the package name. Specify the PACKAGE_ID system variable to check the version of the software from the package ID.
  
• String package-name or String package-ID
  When PACKAGE_NAME is specified as the first argument, specify a package name. When PACKAGE_ID is specified as the first argument, specify a package ID.
  You can specify a character string directly or a variable.
  The maximum allowable number of characters in a package name or package ID is 44.
  

(d) Return value

• String software-version
  The version of the specified software is return in the vvrrssttgggg format.
  

  vvrrsstt

  Version

  gggg

  Generation number

  If the specified software is not found, a zero-length character string ("") is returned. When the user has not set all of vvrrssttgggg, the portion that the user has not set is padded with spaces.
  

(e) Notes

This function obtains the version of the software installed using JP1/Software Distribution. For the software directly installed from media such as floppy disks, this function can obtain only the versions of the software that can be found by using the software search functions of JP1/Software Distribution.