com.ibm.jzos
Class MvsConsole

java.lang.Object
  extended by com.ibm.jzos.MvsConsole
All Implemented Interfaces:
WtoConstants

public class MvsConsole
extends java.lang.Object
implements WtoConstants

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

Uses JNI wrappers to the C Library __console2() api.


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
MvsConsole()
           
 
Method Summary
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 java.lang.String getStartParameters()
          Answer a String contain any parameters on the MVS Start command that started the current started task.
static MvsConsoleResult interact(java.lang.String msg, java.lang.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(java.lang.String msg, int routcdeBitMask, int descrBitMask)
          Convenience method for writing a WTO.
static int wto(WtoMessage wtoMessage)
          Write a WTO message.
static int wto(WtoMessage wtoMessage, java.lang.String encoding)
          Write a WTO message with a specific encoding.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MvsConsole

public MvsConsole()
Method Detail

getStartParameters

public static java.lang.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:
java.lang.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(java.lang.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,
                      java.lang.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(java.lang.String msg,
                                        java.lang.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.