adshread command (issues a specified reply-request message as a reply-waiting event)
- Organization of this page
Format
adshread [-d] variable-name reply-request-message
Description
This command issues a specified reply-request message as a reply-waiting event. The reply-waiting event that is issued is displayed in JP1/IM - View, from where the operator can enter a reply. The reply that is entered is stored in the specified variable.
If you are running the debugger with the standard input and output redirected to the user-reply functionality, the specified reply-request message is output to the standard output and the reply is received from the standard input.
The JP1 event is issued after waiting for a fixed amount of time (specified in the USERREPLY_JP1EVENT_INTERVAL parameter) to elapse since the last JP1 event was issued. For details about the USERREPLY_JP1EVENT_INTERVAL parameter, see USERREPLY_JP1EVENT_INTERVAL parameter (specifies the minimum interval at which JP1 events are to be issued) in 7. Parameters Specified in the Environment Files.
Arguments
- -d
-
Specifies that during debugging, the I/O is to be redirected so that the output destination for the specified reply-request message is the standard output and the reply is received from the standard input. This option is ignored except during debugging.
A character string that begins with a hyphen (-) is treated as an option specification until a character string that begins with a character other than a hyphen (-) is encountered. If an invalid option is specified, an option error results.
- variable-name ~<environment variable name>
-
Specifies a shell variable for storing the reply from the operator. Only one shell variable can be specified. If you specify more than one shell variable, everything that is specified following the first shell variable will be interpreted as part of the reply-request message.
The shell variable can accept an ASCII character string of 0-512 bytes.
When you run the debugger with the standard input and output redirected to the user-reply functionality, the portion in excess of 512 bytes in a character string consisting of more than 512 bytes that is specified in the reply from the standard input will be ignored. In addition, if a character string that contains a linefeed is specified, everything following the linefeed will be ignored.
To specify an array in this argument, you must specify each element. You can specify an array with 0 to 65,535 elements.
- Examples:
-
Regular variable specification: adshread ans "Continue (Y/N)?"
Array specification: adshread ans[1] "Continue (Y/N)?"
The following table shows the execution result for this command, depending on the attributes of the specified shell variable:
Attribute of the specified shell variable
Execution result of the command
Read-only
Outputs KNAX6008-E and terminates.
Type is numeric.
Outputs KNAX7404-E and terminates.
Type is character string or an array of character strings.
Updates the value and terminates.
Non-existent variable
Creates a new variable of the character type, sets its value, and terminates.
Variable name is invalid.
Outputs KNAX6003-E and terminates.
Variable is outside the permitted range of array elements
Outputs KNAX6007-E and terminates.
Shell variable that cannot be used in JP1/Advanced Shell
Outputs KNAX6002-E and terminates the job forcibly.
- reply-request-message ~<any character string>((0 to 1,023 bytes))
-
Specifies the reply-request message that is to be issued as a reply-waiting event.
The character encoding of the specified reply-request message must be consistent with the character encoding of the JP1/Base running on the same host. If the character encodings are different, characters might become garbled.
The specified reply-request message is issued as a JP1 event after its contents are converted by the echo -E reply-request-message command. If more than one reply request message is specified, an error results (KNAX7403-E).
Return codes
Return code |
Meaning |
Response |
Whether to retry |
---|---|---|---|
0 |
Normal termination |
None. |
-- |
1 |
One of the following non-resumable errors occurred: Out of memory A variable that cannot be used in variable-name was detected Internal inconsistency detected |
If you have specified a variable that cannot be used as variable-name, change the specification of the variable. If this does not resolve the problem, contact a system administrator. |
N |
2 |
Semaphore (Mutex): An error occurred in shared memory operations. |
Take action based on the information in the error message. See 11.4.4 Handling Error Information Displayed in the User-Reply Functionality. |
N |
3 |
There is no free space in shared memory. |
Check and revise if necessary the setting for the USERREPLY_WAIT_MAXCOUNT parameter. |
Y |
4 |
An error occurred in JP1 event processing. |
Take action based on the information in the error message. See 11.4.4 Handling Error Information Displayed in the User-Reply Functionality. |
Y |
5 |
An error occurred in JP1 event processing. |
Take action based on the information in the error message. See 11.4.4 Handling Error Information Displayed in the User-Reply Functionality. |
N |
6 |
The JP1 event failed to be transmitted to the specified host. |
Check the following:
|
Y |
7 |
The JP1/Base library cannot be found. |
Check if JP1/Base is installed on the host where JP1/Advanced Shell is installed. If JP1/Base is installed and this occurs anyway, re-install JP1/Base. |
N |
8 |
The connection to the JP1/Base event service on the local host failed. |
Check that the JP1/Base event service is running on the host where JP1/Advanced Shell is installed. |
Y |
10 |
The specified format is invalid. |
Check the format of the command. |
N |
128+ signal number (UNIX only) |
The adshread command received a signal and terminated. |
Confirm that the job received a signal and terminated. |
N |
200 (Windows only) |
The adshread command was forcibly terminated. |
Confirm that the job was forcibly terminated. |
N |
Notes
-
Do not run this command in the background. If you run it in the background, flow control (specified by the USERREPLY_JP1EVENT_INTERVAL parameter) will not work. In addition, the reply from the operator will not be stored in the variable specified for the job that is executing the adshread command.
-
Do not execute this command with a pipe specified.
-
Do not specify processing that accepts a value and redirects it to this command.
-
Do not execute this command in an environment without JP1/Base and JP1/IM, unless you are running the debugger with standard input and output redirected to the user-reply functionality.
The following problems might occur during execution:
-
If JP1/Base is not installed on the host running JP1/Advanced Shell, the command will terminate with an error.
-
If the JP1/Base event service is not running on the host running JP1/Advanced Shell, the command will terminate with an error.
-
If JP1/Base or the JP1/Base event service is not running on the host specified in HOSTNAME_JP1IM_MANAGER, the command will terminate with an error.
-
Even if JP1/IM - Manager is not running on the host specified in HOSTNAME_JP1IM_MANAGER, the command works and will successfully transmit a JP1 event once the event reaches the JP1/Base event service on the host specified in HOSTNAME_JP1IM_MANAGER.
-
If the user-reply functionality's management daemon service is not running, the command will terminate with an error.
-
-
If the command terminates with an error from which it is possible to retry the command, the command might succeed when it is re-executed. Before re-executing the command, see the example job definition scripts in 3.7.5 How to handle adshecho and adshread commands that terminate with an error for help in preparing the job definition script.
-
If the adshread command is waiting for a reply-request message and you terminate the job suddenly in a manner other than as described in 3.10.1 How to forcibly terminate jobs, the reply-request message will be left in shared memory and the reply-waiting event might be retained in JP1/IM - View. In such a case, either use the adshchmsg command's -d option to cancel the reply-waiting status for the reply-request message, or restart the user-reply functionality's management daemon or service.
-
Do not specify the adshread command to the action of the trap command if, in the TRAP_ACTION_SIGTERM parameter, you specify TERM or, in the UNIX edition, you specify AUTO (and the job starts from JP1/AJS).
Usage example
-
Output the reply-request message and determine the processing based on the reply from the operator.
adshread ans "Continue (Y/N)?" if [ "$ans" = "Y" ] ; then echo "Continuing processing." elif [ "$ans" = "N" ] ; then echo "Terminating processing." exit 1 else echo "Invalid reply entered. Terminating processing." exit 1 fi