adshread command (issues a specified reply-request message as a reply-waiting event)

Format

adshread [-d] variable-name reply-request-message

To Page Top

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.

To Page Top

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).

To Page Top

Return codes

To Page Top

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).

To Page Top

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

To Page Top