com.bmc.mainview.nvbapi
Class Conversation

java.lang.Object
  extended by com.bmc.mainview.nvbapi.Conversation
Direct Known Subclasses:
LiveConv

public abstract class Conversation
extends java.lang.Object

An active conversation with MVI-3. Requests are sent in over a conversation, and responses flow back. Conversations are created by a factory method in a HostServer object.

Version:
2.0
Author:
F. Schneider
See Also:
HostServer.conversationFactory()

Field Summary
static VersionNumber HYPERLINKLEVEL
          Documents the minimum server level at which hyperlinks could be requested
static int MAPPED
          Indicates that each row of data is to be returned as a String in the value of each row.
 XML status
          The status returned from the previous request.
static int TAGGED
          Indicates that the fields of returned data are to be broken out into Ele objects in the EleList of each row.
 
Method Summary
 void access(ServicePoint sp)
          Sets the target that this conversation will send requests to.
abstract  XML access(java.lang.String context, java.lang.String system, java.lang.String server, java.lang.String product)
          Sets the target that this conversation will send requests to.
abstract  void actionExecute(int row, java.lang.String command)
          Requests that a product action be performed.
abstract  void actionExecute(int row, java.lang.String command, java.lang.String parm)
          Requests that a product action be performed.
abstract  void actionExecute(int row, java.lang.String command, java.lang.String[] parms)
          Requests that a product action be performed.
abstract  void actionExecute(java.lang.String command)
          Requests that a product action be performed.
abstract  void actionExecute(java.lang.String command, java.lang.String parm)
          Requests that a product action be performed.
abstract  void actionExecute(java.lang.String command, java.lang.String[] parms)
          Requests that a product action be performed.
 void addListener(ConversationListener listener)
          Add a ConversationListener to monitor events on the conversation
 void close()
          Terminates the conversation
 XML dataGet(int type)
          Requests data from the current view
 XML dataGet(int type, java.lang.String startrow, java.lang.String numRows)
          Requests data from the current view
 XML dataGet(int type, java.lang.String startrow, java.lang.String numRows, java.lang.String qwhere)
          Requests data from the current view
abstract  XML dataGet(int type, java.lang.String startrow, java.lang.String numRows, java.lang.String qwhere, java.lang.String where)
          Retrieve the data from the current view
abstract  void dictionarySet(java.lang.String symbol, java.lang.String value)
          Sets a dictionary value for use by the back-end selector code.
abstract  java.lang.String[] extractMessages()
          Get messages from a previous request
abstract  java.lang.String extractSymbol(java.lang.String symbol)
          Get a MAINVIEW Symbol
 ViewDefinition getCurrentView()
          Get the definition of the current view
abstract  HostServer getHost()
           
 int getTimeout()
          Get the amount of time to wait for a response from the host.
 XML mapGet()
          Get the list of fields in a MAPPED view
abstract  XML mapGet(boolean hyperlinks)
          Get the list of fields in a MAPPED view
 boolean removeListener(ConversationListener listener)
          Remove a previously added ConversationListener
 void setCurrentView(ViewDefinition view)
          Change the view that the conversation is working with.
 void setRefreshOff()
          Allow data get operations to use the current sample
 void setRefreshOn()
          Allow data get operations to get a new sample
 void setTimeout(int timeout)
          Set the amount of time to wait for a response from the host.
abstract  void streamSend(java.lang.String name, java.lang.String stream)
          Send a data stream to the back end.
abstract  void timeSet(long time)
          Gives access to the historical data stored on the mainframe
 void viewSet(java.lang.String view, boolean returnAll)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 void viewSet(java.lang.String view, boolean returnAll, java.lang.String viewParm)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 void viewSet(java.lang.String view, boolean returnAll, java.lang.String[] viewParm)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 void viewSet(ViewDefinition vdef, boolean returnAll)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 void viewSet(ViewDefinition vdef, boolean returnAll, java.lang.String viewParm)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 void viewSet(ViewDefinition vdef, boolean returnAll, java.lang.String[] viewParm)
          Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TAGGED

public static final int TAGGED
Indicates that the fields of returned data are to be broken out into Ele objects in the EleList of each row.

See Also:
Constant Field Values

MAPPED

public static final int MAPPED
Indicates that each row of data is to be returned as a String in the value of each row.

See Also:
Constant Field Values

HYPERLINKLEVEL

public static final VersionNumber HYPERLINKLEVEL
Documents the minimum server level at which hyperlinks could be requested


status

public XML status
The status returned from the previous request. Status always has the following attributes: The following attributes may also appear:

Method Detail

addListener

public void addListener(ConversationListener listener)
Add a ConversationListener to monitor events on the conversation

Parameters:
listener - the listener
See Also:
ConversationListener, ConversationEvent

removeListener

public boolean removeListener(ConversationListener listener)
Remove a previously added ConversationListener

Parameters:
listener - the listener to be removed
Returns:
true if the listener had been added and is now removed.
See Also:
addListener(com.bmc.mainview.nvbapi.ConversationListener)

access

public abstract XML access(java.lang.String context,
                           java.lang.String system,
                           java.lang.String server,
                           java.lang.String product)
                    throws java.io.IOException
Sets the target that this conversation will send requests to.

Parameters:
context - the MVI defined context to be used
system - The zOS system name
server - The job name of the PAS (Product Address Space)
product - The MVI product whose views are to be used
Returns:
an XML structure of a "status" element which has the following attributes:
  • state - the registered name of the product, e.g. MVMVS, being accessed
  • ssi - "y|n"
  • provider-level - DataBus level of product selector side where the data is produced. The minimum level to support Threshold Advisor is 9
  • target - target or context name of the product being accessed
  • version - current version number of the NVBAPI
  • api-level - APAR number to indicate certain features are supported by the NVBAPI Server
  • product - registered ID of the product being accessed
  • number-msg - number of messages currently available
  • last-cc - completion code of the last request
  • requestor-level - DataBus level of server side/front-end where the result XML is formatted. The minimum level to support Threshold Advisor is 9.
Throws:
java.io.IOException
See Also:
ServicePoint

access

public void access(ServicePoint sp)
            throws java.io.IOException
Sets the target that this conversation will send requests to.

Parameters:
sp - The MVI Service Point to be used.
Throws:
java.io.IOException

viewSet

public void viewSet(java.lang.String view,
                    boolean returnAll)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
view - The name of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
Throws:
java.io.IOException

viewSet

public void viewSet(ViewDefinition vdef,
                    boolean returnAll)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
vdef - The definition of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
Throws:
java.io.IOException

viewSet

public void viewSet(java.lang.String view,
                    boolean returnAll,
                    java.lang.String viewParm)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
view - The name of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
viewParm - A parameter to modify the view.
Throws:
java.io.IOException

viewSet

public void viewSet(ViewDefinition vdef,
                    boolean returnAll,
                    java.lang.String viewParm)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
vdef - The definition of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
viewParm - A parameter to modify the view.
Throws:
java.io.IOException

viewSet

public void viewSet(java.lang.String view,
                    boolean returnAll,
                    java.lang.String[] viewParm)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
view - The name of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
viewParm - A set of parameters to modify the view.
Throws:
java.io.IOException

viewSet

public void viewSet(ViewDefinition vdef,
                    boolean returnAll,
                    java.lang.String[] viewParm)
             throws java.io.IOException
Selects the view that will be addressed by subsequent mapGet, dataGet or actionExecute calls.

Parameters:
vdef - The definition of the view
returnAll - true to include hidden fields in subsequent mapGet() and dataGet() responses. false to return only visible fields.
viewParm - A set of parameters to modify the view.
Throws:
java.io.IOException

timeSet

public abstract void timeSet(long time)
                      throws java.io.IOException
Gives access to the historical data stored on the mainframe

Parameters:
time - The data and time from which the data is to be retrieved
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(java.lang.String command)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
command -
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(java.lang.String command,
                                   java.lang.String parm)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
command -
parm -
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(java.lang.String command,
                                   java.lang.String[] parms)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
command -
parms -
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(int row,
                                   java.lang.String command)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
row -
command -
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(int row,
                                   java.lang.String command,
                                   java.lang.String parm)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
row -
command -
parm -
Throws:
java.io.IOException

actionExecute

public abstract void actionExecute(int row,
                                   java.lang.String command,
                                   java.lang.String[] parms)
                            throws java.io.IOException
Requests that a product action be performed.

Parameters:
row -
command -
parms -
Throws:
java.io.IOException

dataGet

public XML dataGet(int type)
            throws java.io.IOException
Requests data from the current view

Parameters:
type - The format of the result: Conversation.MAPPED or Conversation.TAGGED
Returns:
An XML structure as described in dataGet(int String, String)
Throws:
java.io.IOException
See Also:
dataGet(int, java.lang.String, java.lang.String)

dataGet

public XML dataGet(int type,
                   java.lang.String startrow,
                   java.lang.String numRows)
            throws java.io.IOException
Requests data from the current view

Parameters:
type - The format of the result: Conversation.MAPPED or Conversation.TAGGED
numRows - The maximum number of rows of data to be retrieved.
Returns:
An XML structure of a "data" element with multiple "row" sub-elements. A "data" element has the following attributes:
  • type - "mapped" or "tagged"
  • numrows
  • total-rows
  • startrow
  • local-date
  • local-time
  • gmt-date
  • gmt-time
  • view
  • form
A "row" element has an "index" attribute. If the data type is "mapped" it contains a CDATA section containing the fields. If the data type is "tagged" it has multiple "ele" subelements.

An "ele" element has the following attributes and a CDATA section:

  • c - The column ID
  • t - The threshold value
Throws:
java.io.IOException

dataGet

public XML dataGet(int type,
                   java.lang.String startrow,
                   java.lang.String numRows,
                   java.lang.String qwhere)
            throws java.io.IOException
Requests data from the current view

Parameters:
type - The format of the result: Conversation.MAPPED or Conversation.TAGGED
numRows - The maximum number of rows of data to be retrieved.
qwhere - An expression to limit the data returned (max length=1024)
Returns:
An XML structure of a data element with multiple row sub-elements
Throws:
java.io.IOException
See Also:
dataGet(int)

dataGet

public abstract XML dataGet(int type,
                            java.lang.String startrow,
                            java.lang.String numRows,
                            java.lang.String qwhere,
                            java.lang.String where)
                     throws java.io.IOException
Retrieve the data from the current view

Parameters:
type - Either TAGGED or MAPPED
startrow - First row to be retrieved
numRows - How many rows to retrieve
qwhere - A MAINVIEW QWHERE clause to filter the query (max length=1024)
where - A MAINVIEW WHERE clause to filter the rows (max length=1024)
Returns:
An XML structure of a data element with multiple row sub-elements
Throws:
java.io.IOException - in case of error.
See Also:
dataGet(int)

extractSymbol

public abstract java.lang.String extractSymbol(java.lang.String symbol)
                                        throws java.io.IOException
Get a MAINVIEW Symbol

Parameters:
symbol -
Returns:
value
Throws:
java.io.IOException

dictionarySet

public abstract void dictionarySet(java.lang.String symbol,
                                   java.lang.String value)
                            throws java.io.IOException
Sets a dictionary value for use by the back-end selector code.

Parameters:
symbol -
value -
Throws:
java.io.IOException

streamSend

public abstract void streamSend(java.lang.String name,
                                java.lang.String stream)
                         throws java.io.IOException,
                                java.lang.IllegalArgumentException
Send a data stream to the back end.

Parameters:
name - Up to 14 character stream name
stream - Arbitrary data stream
Throws:
java.lang.IllegalArgumentException - if name is longer than 14 characters.
java.io.IOException

extractMessages

public abstract java.lang.String[] extractMessages()
                                            throws java.io.IOException
Get messages from a previous request

Returns:
an array of messages
Throws:
java.io.IOException
Since:
2.0.25

setRefreshOn

public void setRefreshOn()
Allow data get operations to get a new sample


setRefreshOff

public void setRefreshOff()
Allow data get operations to use the current sample


getTimeout

public int getTimeout()
Get the amount of time to wait for a response from the host.

Returns:
the timeout delay in milliseconds.

setTimeout

public void setTimeout(int timeout)
                throws java.net.SocketException
Set the amount of time to wait for a response from the host.

Parameters:
timeout - the timeout delay in milliseconds.
Throws:
java.net.SocketException

getCurrentView

public ViewDefinition getCurrentView()
Get the definition of the current view

Returns:
the view definition

setCurrentView

public void setCurrentView(ViewDefinition view)
Change the view that the conversation is working with. Does not issue view-set to the host, so is only useful when switching between forms.

Parameters:
view - A view definition which has been previously set in this conversation.
See Also:
viewSet(ViewDefinition, boolean), getCurrentView(), ViewDefinition.setForm(int)

mapGet

public XML mapGet()
           throws java.io.IOException
Get the list of fields in a MAPPED view

Returns:
An XML structure of a "map" element with multiple "element" sub-elements.
Throws:
java.io.IOException
See Also:
mapGet(boolean)

mapGet

public abstract XML mapGet(boolean hyperlinks)
                    throws java.io.IOException,
                           java.lang.IllegalArgumentException
Get the list of fields in a MAPPED view

Parameters:
hyperlinks - true if hyperlink definitions are to be returned for each field.
Returns:
An XML structue of a "map" element with multiple "element" sub-elements. A "map" element has the following attributes:
  • gdc
  • row-length
  • view
  • form
An "element" has the following attributes:
  • id
  • data-type
  • display-mode
  • summary-type
  • name
  • visible
  • width
  • offset
  • threshold-offset
An "element" has the following sub-elements:
  • hdr1
  • hdr2
  • count-if
  • hyperlink
Throws:
java.io.IOException
java.lang.IllegalArgumentException - if hyperlinks are requested, but the host is at a maintenance level that does not support this function.
See Also:
Hyperlink, dataGet(int), MAPPED

close

public void close()
Terminates the conversation


getHost

public abstract HostServer getHost()