Module ibm.jzos

Package com.ibm.jzos

Class MvsConsole

java.lang.Object

com.ibm.jzos.MvsConsole

All Implemented Interfaces:

WtoConstants

public class MvsConsole
extends Object
implements WtoConstants

A class with static methods to interface with the MVS console.

The class uses the C Library __console2() API with the __CONSOLE_FORMAT_2 structure format. __CONSOLE_FORMAT_2 provides single console support and does not support interfacing with multiple consoles. For more information, refer to __console2() in z/OS XL C/C++ Run-Time Library Reference, SA22-7821.

Field Summary

Fields inherited from interface com.ibm.jzos.WtoConstants

DESC_CRITICAL_EVENTUAL_ACTION_REQUESTED, DESC_DYNAMIC_STATUS_DISPLAYS, DESC_EVENTUAL_ACTION_REQUIRED, DESC_IMMEDIATE_ACTION_REQUIRED, DESC_IMMEDIATE_COMMAND_RESPONSE, DESC_IMPORTANT_INFORMATION_MESSAGES, DESC_JOB_STATUS, DESC_MESSAGE_PREVIOUSLY_AUTOMATED, DESC_OPERATOR_REQUEST, DESC_OUT_OF_LINE_MESSAGE, DESC_RETAIN, DESC_SYSTEM_FAILURE, DESC_SYSTEM_STATUS, FLAG_CONSOLE_HARDCOPY, ROUTCDE_DASD_POOL, ROUTCDE_DISK_LIBRARY, ROUTCDE_EMULATORS, ROUTCDE_MASTER_CONSOLE_ACTION, ROUTCDE_MASTER_CONSOLE_INFORMATION, ROUTCDE_PROGRAMMER_INFORMATION, ROUTCDE_SYSPROG_INFORMATION, ROUTCDE_SYSTEM_SECURITY, ROUTCDE_TAPE_LIBRARY, ROUTCDE_TAPE_POOL, ROUTCDE_TELEPROCESSING_CONTROL, ROUTCDE_UNIT_RECORD_POOL

Constructor Summary

Constructors

Constructor	Description
MvsConsole()

Method Summary

Modifier and Type	Method	Description
static void	deleteMessage(int msgId)	Delete a WTO message.
static void	deleteMessages(int[] msgIds)	Delete multiple WTO messages.
static void	deleteMessagesWithToken(int deleteToken)	Delete all WTO messages with a given token id.
static String	getStartParameters()	Answer a String contain any parameters on the MVS Start command that started the current started task.
static MvsConsoleResult	interact(String msg, String encoding, int[] routcde, int[] descr, long flags, int token, int deleteToken, int[] deleteIds, boolean waitForCmd)	Interact with the system console by issuing/deleting WTO messages and/or waiting for modify/stop commands.
static boolean	isListening()	Returns true if an MvsCommandListener has been established.
static MvsCommandCallback	registerMvsCommandCallback(MvsCommandCallback callback)	Register an MVS operator command callback.
static void	startMvsCommandListener()	Called by JZOS to allow this Java application intercept MVS Operator commands.
static MvsConsoleResult	waitForCmd()	Wait for a command from the operators console.
static int	wto(WtoMessage wtoMessage)	Write a WTO message.
static int	wto(WtoMessage wtoMessage, String encoding)	Write a WTO message with a specific encoding.
static int	wto(String msg, int routcdeBitMask, int descrBitMask)	Convenience method for writing a WTO.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MvsConsole

public MvsConsole()

Method Details

getStartParameters

public static String getStartParameters()

Answer a String contain any parameters on the MVS Start command that started the current started task.

Returns:

String started task parameters; answers null if not started as a started task.

isListening

public static boolean isListening()

Returns true if an MvsCommandListener has been established.

startMvsCommandListener

public static void startMvsCommandListener()

Called by JZOS to allow this Java application intercept MVS Operator commands. If direct interaction is required by the application, this method should be called once the JVM has been launched. Note that this method cannot be called if a listener is already present. To prevent JZOS from starting a listener, set the JZOS environment variable JZOS_ENABLE_MVS_COMMANDS to false.

Throws:

IllegalStateException - if there is already a listener running

registerMvsCommandCallback

public static MvsCommandCallback registerMvsCommandCallback(MvsCommandCallback callback)

Register an MVS operator command callback. This callback enables custom behavior based on the parameters received for START, MODIFY and STOP commands. The active callback can be unregistered by passing null as the argument to this method.

Parameters:

callback - an implementation of MvsCommandCallback that has customized handlers for START, MODIFY and STOP.

Returns:

the callback that was in place prior to this call. May be null.

wto

public static int wto(String msg,
 int routcdeBitMask,
 int descrBitMask)
               throws ErrnoException

Convenience method for writing a WTO.

Parameters:

msg - the message to write. If longer than 125 characters, it will be broken into multiple lines of 69 characters, broken on word boundaries using the formatting algorithm in __console2(). Embedded line-separators will cause a new WTO message line.

routcdeBitMask - the ROUTE codes to use for the message. See WtoConstants for details.

descrBitMask - the descriptor codes to use. See WtoConstants for details.

Returns:

the system assigned message id of the WTO. This id can be used to delete the message.

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

wto

public static int wto(WtoMessage wtoMessage)
               throws ErrnoException

Write a WTO message. If wtoMessage has embedded line-separators, a multi-line WTO will be issued with the line-separators determining the individual lines. If a single line is longer than the allowed maximum, it will be formatted to fit on multiple lines.

Parameters:

wtoMessage - the WtoMessage object contain the message, route codes and descriptor codes.

Returns:

the system assigned message id of the WTO. This id can be used to delete the message.

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

wto

public static int wto(WtoMessage wtoMessage,
 String encoding)
               throws ErrnoException

Write a WTO message with a specific encoding.

Parameters:

wtoMessage - the WtoMessage object contain the message, route codes and descriptor codes.

encoding - a String containing the encoding name.

Returns:

the system assigned message id of the WTO. This id can be used to delete the message.

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

deleteMessage

public static void deleteMessage(int msgId)
                          throws ErrnoException

Delete a WTO message.

Parameters:

msgId - an int containing the message id of the message to delete

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

deleteMessages

public static void deleteMessages(int[] msgIds)
                           throws ErrnoException

Delete multiple WTO messages.

Parameters:

msgIds - an int array containing the message ids of the messages to delete

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

deleteMessagesWithToken

public static void deleteMessagesWithToken(int deleteToken)
                                    throws ErrnoException

Delete all WTO messages with a given token id.

Parameters:

deleteToken - the token id, given on the matching WtoMessage objects

Throws:

ErrnoException - if an error occurs with the __console2() interaction.

See Also:

• WtoMessage.setToken(int)

waitForCmd

public static MvsConsoleResult waitForCmd()
                                   throws ErrnoException

Wait for a command from the operators console. This method will block until either a stop or modify command is received from the operator. By default, this method is invoked by the active instance of MvsCommandThread. To receive console events from this thread, register a command callback.

Returns:

an MvsConsoleResult which will contain the type of command received and the modify text, if applicable.

Throws:

ErrnoException - if the call to __console2() fails.

See Also:

• registerMvsCommandCallback(MvsCommandCallback)

interact

public static MvsConsoleResult interact(String msg,
 String encoding,
 int[] routcde,
 int[] descr,
 long flags,
 int token,
 int deleteToken,
 int[] deleteIds,
 boolean waitForCmd)
                                 throws ErrnoException

Interact with the system console by issuing/deleting WTO messages and/or waiting for modify/stop commands.

This method calls the __console2() C-Library function.

Parameters:

msg - the WTO message to write.

encoding - the codepage to use for the WTO message.

routcde - an array of routing codes assigned to the message.

descr - an array of message descriptor codes assigned to the message.

flags - the flags assigned to the message. Can be 0 or FLAG_CONSOLE_HARDCOPY

token - the grouping token to use to tag this message

deleteToken - the grouping token to use to delete messages from the console

deleteIds - an array of message ids to delete from the console.

waitForCmd - a boolean that directs the __console2() command to wait for an operator command

Returns:

an MvsConsoleResult which contains the effect of the __console2() call

Throws:

ErrnoException - if the call to __console2() fails. The errno and errno2 code can be used to determine what the nature of the failure is.