8.10.2 NetExec (call an executable file on the local PC or remote PC)

Purpose

Calls an executable file (EXE file, BAT file, COM file, SPT file, CMD file, or linked file) on the local PC, or on a remote PC, according to specified parameters. You can specify whether to wait for the called application to complete.

Syntax

NetExec ([CompName], FileName, Flag, [ExecDirName], [ExecPlace], [Option] [, Param1, Param2, ...])

Arguments

CompName

Specify the computer at which to call the executable file, using a character string or a variable that stores this value.^#

This value is optional. If you omit this value, the computer on which the command is executed is assumed.

JP1/Script must be installed on the remote computers you want to specify. For details about accounts for accessing computers, see 2.2 Accounts for communication with other computers.

Note: Specify the following values if the target computer is in a cluster system environment:

If the JP1/Script service, Script Launcher, or Script Launcher service has been registered as a resource, specify a logical host name or a logical IP address.
If the JP1/Script service, Script Launcher, or Script Launcher service has not been registered as a resource, specify a physical host name or a physical IP address.

FileName

Specify the executable file as a character string or as a variable that stores this value.

You can specify any of the following types of files:

Executable file (.EXE)
MS-DOS batch file (.BAT)
MS-DOS executable file (.COM)
JP1/Script script file (.SPT)
Command script (.CMD)
Linked file

When you specify a path or file name containing a space, there is no need to enclose the entire path or file name in double quotation marks (").

To specify only a file name, specify the folder containing the target executable file for the PATH environment variable of the computer specified in CompName.

Flag

Specify True to wait for the specified executable file to complete; otherwise, specify False.

If you specified False in Flag, the script waits for the executable file to complete if it is still running when the script terminates. If you want to terminate the script without waiting for the executable file to complete, use the Exit command with Skip specified in Option. See Example 2 in 8.10.1 Exec (call an executable file on the local PC).

ExecDirName

Specify the current directory containing the executable file specified in FileName, expressed as a character string or the name of the variable that contains the applicable value.

This value is optional. When it is omitted, the command assumes the directory of the executable file.

This value is applicable if the executable file specified in FileName is not a JP1/Script file.

ExecPlace

Specify True to execute the executable file specified in FileName in the service space, or False to execute it in the logon space.

This value is optional. If you omit this value, True is assumed.

You can specify True only if the JP1/Script service is active on the computer specified in CompName. If you specify False, Script Launcher or Script Launcher service must be active on the specified computer.

Option

If you specified a JP1/Script script file (.SPT) in FileName, you can specify the following optional value:

Value	Meaning
`CopyFile`	Copies the script file from the calling side to the computer specified in `CompName`. At the destination computer, a folder with the name of the calling computer is created in the `DATA` folder^# in the installation folder. The script file is copied to this folder. The script's execution environment file (`.SPV`) is not copied. If the destination folder contains an execution environment file that has the same name as the script file, that execution environment file is deleted when the script file is copied. In JP1/Script 06-00 and later versions, if the script file has an associated menu information file (`.SPN`) of the same file name, that menu information file is copied with the script file. When these files are copied, any file that has the same name as these files is deleted from the destination folder. When the `NetExec` command terminated, the copied script file and menu information file are deleted. The analysis trace file and execution trace file which were output after execution of the copied script are copied back to the script execution folder on the calling side. Note the following if you specify `CopyFile` in `Option`. Any information specified in the execution environment file will be invalid. Therefore, the command lines specified in the execution environment file are invalid in the script file started by the `NetExec` command. You cannot start multiple script files by using the `NetExec` command with `CopyFile` specified. Regardless of the `Flag` setting, if you specify `CopyFile` in `Option`, do not log off Windows or shut down the system until the copied script file completes execution. # The folder is created in the script execution environment folder (`system-drive\ProgramData\Hitachi\Script\Data`).

Value

Meaning

CopyFile

Copies the script file from the calling side to the computer specified in CompName.

At the destination computer, a folder with the name of the calling computer is created in the DATA folder^# in the installation folder. The script file is copied to this folder. The script's execution environment file (.SPV) is not copied. If the destination folder contains an execution environment file that has the same name as the script file, that execution environment file is deleted when the script file is copied.

In JP1/Script 06-00 and later versions, if the script file has an associated menu information file (.SPN) of the same file name, that menu information file is copied with the script file. When these files are copied, any file that has the same name as these files is deleted from the destination folder.

When the NetExec command terminated, the copied script file and menu information file are deleted. The analysis trace file and execution trace file which were output after execution of the copied script are copied back to the script execution folder on the calling side.

Note the following if you specify CopyFile in Option.

Any information specified in the execution environment file will be invalid. Therefore, the command lines specified in the execution environment file are invalid in the script file started by the NetExec command.
You cannot start multiple script files by using the NetExec command with CopyFile specified.
Regardless of the Flag setting, if you specify CopyFile in Option, do not log off Windows or shut down the system until the copied script file completes execution.

#: The folder is created in the script execution environment folder (system-drive\ProgramData\Hitachi\Script\Data).

This value is optional. If you omit this value, the Exec command runs the script file residing on the computer specified in CompName.

This value is invalid if you specify an executable file other than a JP1/Script script file (.SPT) in FileName.

Param1 to Param31

Specify the necessary parameters for executing the file specified in FileName. Write each parameter as a string or number, or as a variable that stores this value.

In JP1/Script 06-00 and later versions, you can specify a one-dimensional array variable that stores all the required parameters.

For the parameter coding conventions, see 6.2 Rules for writing command lines.

If the strings listed below are specified in the parameters, they are treated as the defaults when the window is displayed for the application being started. These parameters are not applicable to an application that displays its window explicitly.

Parameter	Meaning
`/SPT:HIDE`	Hides the application window.
`/SPT:MIN`	Minimizes the application window to an icon.
`/SPT:MAX`	Maximizes the application window.

The parameters you specify in Param1 to Param31 are passed as command line parameters to the executable file. The strings /SPT:HIDE, /SPT:MIN, and /SPT:MAX are not passed as command line parameters.

Description

The NetExec command executes an executable file on a specified computer.

If you specify True in Flag, the script waits for the called application to complete. If you specify False, the next command is processed without waiting for the application to complete.

The command returns True on successful execution, or False if an error occurs.

If you specify True in Flag and the execution result is True, the executable file's exit code is stored as a signed numeric in the _EXEC_RTN_ reserved variable. Nothing is stored in this reserved variable if you specify False in Flag or if the execution result is False.

If you specify False in Flag, the executable file ID is stored in the _EXEC_ID_ reserved variable.

Note 1

Depending on the type of executable file called by the NetExec command, the execution result might differ even with the same type of error. For example, the command returns False if a non-existent EXE file is called, but returns True if a non-existent SPT file is called.

To determine whether the NetExec command with True specified in Flag terminated successfully, you must also refer to the exit code of the executable file stored in the _EXEC_RTN_ reserved variable in addition to the execution result. For the recommended determination method, see Example 1 in 8.10.1 Exec (call an executable file on the local PC).

When a remote computer is specified in the CompName argument, operation is guaranteed only in a LAN environment. Operation in other environments such as a WAN environment cannot be guaranteed. Operation is not possible via a firewall.

Beginning with JP1/Script 07-01, if an error occurs during NetExec execution, an error log file is output to the STXNetExec_Client or STXNetExec_Server folder, which is created under the LOG folder of the installation folder.

To suppress the output of error log files, specify 0 in the following registry:

Registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Hitachi\JP1/Script\SPTX\

Option

Value name

Net_Trace

Value data type

REG_DWORD

Value

0: Do not output error log files.

1: Output error log files (default value).

When the setting takes effect

The setting takes effect the next time the script file is executed.

To change the output destination folder for error log files, specify the new folder name in the value of the following registry:

Value name: Net_Trace_Directory
Value data type: REG_SZ
Value: Output destination folder for error log files (initial value: script log folder)
When the setting takes effect: The setting takes effect the next time the script file is executed.

Note 2

When you start an executable file that requires administrator permissions, the Windows User Account Control dialog box might appear. For details, see 1.8.2 Command behavior.

Executable files called by the NetExec command do not inherit the process environment variable of the calling process. Therefore, the values set on the calling side cannot be referenced.

Note 3

If you specify a non-existent computer name in CompName or specify a non-existent executable file name in FileName, the command returns True, and 0 is stored in the _RTN_ reserved variable.

This also occurs in the following cases:

Access to the executable file failed.
A network error occurred.
The JP1/Script service has stopped.
Script Launcher or the Script Launcher service is not running.

Note 4

In JP1/AJS, programs that display a GUI to wait for the user's input cannot be directly executed as jobs. However, you can execute a program with a GUI in JP1/AJS by using a JP1/Script script file as follows:

Create a script file that executes the NetExec command (with False specified for ExecPlace) to call a program with a GUI.
Use a JP1/AJS job to execute the above script file.

Example

' Execute a script file residing on the computer
' "SOP4A065(SCRIPT)" in the logon space.
comp1="SOP4A065(SCRIPT)"
prm1="/SPALV(2)"
prm2="/SPXLV(2)"
rtn1=NetExec (comp1,_TEMP_+"NETWORK.SPT", True, , False,
_, prm1, prm2)
' Terminate the script.
If rtn1 = True Then
  ' If the NetExec command terminates normally, return
  ' the exit code of the called script file.
  Exit (_EXEC_RTN_)
Else
  ' If the NetExec command terminates abnormally, return
  ' the error detail code.
  Exit (_RTN_)
End

JP1/Script version

Supported from JP1/Script 05-00.

To Page Top