8.3.2 adshappexec command (GUI application execution command) [only for Windows execution environment]

Syntax

adshappexec [-m] [-d work-folder] [-v name-to-be-displayed]{-w executable-application-name | -n Executable-application-name} [-- argument-1 argument-2...]

Description

This command requests activation of the executable application to the application execution agent. You can activate this command by specifying the executable file name for the PC job definition of JP1/AJS.

This command outputs the return value of the executable application to the standard output and message (detailed results of JP1/AJS). When using this command in a succeeding job as the return value of the job, the command stores the value in the variable with command substitution.

Arguments

-m

This command suppresses the message output to the standard error output.

You can use this command in environments where the standard input/output cannot be used.

This command outputs an argument specification error of the command and license check error even if when the -m option has been specified.

-d work-folder ~ <path name>((1 to 247 bytes))

This command specifies the work folder for execution of the executable application.

When the work folder has not been specified, this command activates the executable application with the current path for execution of the adshappexec command.

If a work folder contains a space, specify the name including the space by enclosing the name with double quotation marks (") when executing the application from the job definition script.

-v name-to-be-displayed ~ <path name>((1 to 247 bytes))

You can specify the display name that will appear when you left-click on the [Application Execution Agent] icon.

If a space is included in the executable application name, specify the name including the space by enclosing the name with double quotation marks (") when you executing the application from the job definition script.

If the name to be displayed is omitted, the executable application name is output.

We recommend specifying this argument to distinguish applications when multiple executable applications are operated.

-w executable-application-name ~ <path name>((1 to 247 bytes))

The application execution agent will not finish until the executable application is finished.

Specifies the file name of the executable application for the executable application name.

If a space is included in the executable application name, specify the name including the space by enclosing the name with double quotation marks (") when executing the application from the job definition script.

-n executable-application-name ~ <path name>((1 to 247 bytes))

The application execution agent finishes without waiting for the executable application to finish.

When you use this argument, the executable application can be started without being affected by the restrictions applied to the number of simultaneous executions.

Specifies the file name of the executable application for the executable application name.

-- argument-1 argument-2... ~ <argument>((1 to 1023 bytes))

Specifies the parameter after -- that is specified when executing the executable application.

Do not specify an argument when specifying an associated executable application.

You can specify any number of arguments as long as the total length of the arguments is within 1,023 bytes.

Return codes

Return code	Meaning
0	Normal termination.
Other than 0	Termination with an error.

There are return codes for 3 processes in the adshappexec command. The return code for each process is handled as follows:

Figure 8‒1: Handling of the return code for each process

The output of the return value at the position where the error has occurred are as follows:

(a) Error when handling the adshappexec command

This command sets the return value of the command. This command outputs the message to the standard error output (detailed results when executed from JP1/AJS - View).

(b) Error when the application execution agent is processing requests from the adshappexec command

This command sets the return value of the command. This command outputs the message to the standard error output (detailed results when executed from JP1/AJS - View) by using the application execution agent.

(c) Return value of the executable application

This command outputs the return value to the standard output. In addition, the return value of the executable application is output to the standard error output (detailed results when executed from JP1/AJS - View).

Even if the executable application returns a return value other than 0, the adshappexec command will not be abnormally terminated.

To confirm the return value of the executable application, confirm the messages of the standard output.

(d) Error when the application execution agent is not processing requests from the adshappexec command

This command sets the return value of the adshappagent command as an error of the application execution agent.

This command outputs a message to the message box or the log of the application-execution agent functionality depending on the location where the error has occurred.

Notes

You must execute the adshappexec command while the application execution command is running. An error occurs if the application execution command is executed before the application execution agent is run. In addition, an error occurs if you finish the application execution agent while executing the adshappexec command.
You must specify the -w argument and -n argument of the adshappexec command.

The argument specified last is enabled in the following cases:
- If the -w option and the -r option are specified at the same time
- If the -w option is specified multiple times
- If the -r option is specified multiple times
The executable application does not inherit the environment variable and environment variable file name that are setting items of the PC jobs of JP1/AJS. In addition, the executable application uses the environment variable of the user running the application.
A maximum of 5 executable applications that specify the -w argument of the adshappexec command can be run at the same time. If you start more than 5 executable applications, you must wait until executable applications are finished.

When waiting for the completion of an executable application, it may take more than a minute from when the executable application that is being executed ends to when the executable application is started.
If the same option is specified multiple times, the last specification is enabled.
When executing the application having the following specifications by using the -w argument, the adshappexec command may not terminate even when the specified file is terminated.
- Even if you close the file specified for the executable application, the executable application itself will not be terminated.
In such case, the adshappexec command is terminated if the application itself is terminated.

Example: If you close only the Excel file that is specified as the executable application and do not terminate Excel itself
Depending on the specification related to the start of processes of the executable application, the adshappexec command may be terminated without waiting for termination of the application even if the -w argument is specified.

The adshappexec command may terminate under the following cases:

(1) If KNAX7259-W is output

Example: If Excel itself has already been operated before executing the Excel file as an executable application

In this case, run the executable application while Excel is not being run or adopt the operation in which the -w argument will not be used.

(2) If KNAX7259-W is not output

Example: If you execute explorer.exe as an executable application

In this case, adopt the operation in which the -w argument will not be used.
Note the following points when performing a forced termination:
- When the job is forced to terminate while executing the adshappexec command:
  
  The running executable application keeps running.
- When TERM is specified with the TRAP_ACTION_SIGTERM
  
  Do not specify the adshappexec command for the operation definition of the trap command.
  
  When an executable application that performs interactive operation is specified, the executable application will wait for a reply and the job definition script might not end.

Examples

When executing and waiting for termination of the executable application:
```
adshappexec -w "c:\appfolder\app.exe"...1
Terminate echo app...2
```
Execute c:\appfolder\app.exe (process 1) and wait for termination (process 2).
When executing and not waiting for termination of the executable application:
```
adshappexec -n "c:\appfolder\app.exe"...1
Run echo app...2
```
Execute c:\appfolder\app.exe (process 1) and execute the process 2 without waiting for the application to finish.
When determining the return value of the executable application that uses the extended shell command
```
exeapprc=$(adshappexec -w c:\\appfolder\\app.exe)
if [[ $? != 0 ]] ... 1
then
  echo adshappexec error
  exit
fi
echo $exeapprc
if [[ $exeapprc != 0 ]] ... 2
then
  echo app.exe error
  exit
fi
```
Process 1 judges the return value of the adshappexec command.

Process 2 judges the return value of c:\\appfolder\\app.exe (executable application).

To Page Top