Rational Developer for Power Systems Software
V7.6

com.ibm.etools.iseries.comm
Class ISeriesAbstractHostAPIProcessor

java.lang.Object
  extended by com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor
All Implemented Interfaces:
IISeriesAPIProcessor
Direct Known Subclasses:
ISeriesAbstractListProcessor, ISeriesCheckCommand, ISeriesCheckObject, ISeriesConvertEditCode, ISeriesListDatabaseFields, ISeriesListEditDescriptions, ISeriesListFields, ISeriesListObjectLocks, ISeriesListRecords, ISeriesListSpoolFiles, ISeriesRetreiveCDRAInfo, ISeriesRetrieveDatabaseFileDescription, ISeriesRetrieveDatabaseMemberDescription, ISeriesRetrieveDisplayFileDescription, ISeriesRetrieveFileOverrideInformation, ISeriesRetrieveSaveFileDescription, ISeriesRetrieveSortSeqTable, ISeriesSyntaxCheckSQLStatements, ListModuleInformation, ListNetworkInterfaces, ListServiceProgramInformation

public abstract class ISeriesAbstractHostAPIProcessor
extends Object
implements IISeriesAPIProcessor

A base class for all classes that call a system API to retrieve or update information on an ISeries.

It turns out that there are a number of common parameters and structures in many of the ISeries system APIs. This class tries to simplify the work to call a new system API by offering built in functionality for all those commonly used parameters and structures.

The approach taken is to use nested classes for the common structures, and a series of methods for other common processing needs such as working with a user space which most APIs require.

The following nested classes are offered for common structures:

HostAPIErrorCodeStructure

  • Error code structure (input/output parameter). A 350 byte structure. This nested class makes it easy to return the ProgramParameter object needed for the API call, and to subsequently return the error text if any after the API call.
  • Generic list API header. All system APIs that return lists return a common header at the top of the returned user space. To make it easy to process this, a common nested class HostGenericListHeader is supplied. When an API uses a user space to return information, the approach to using that API is typically this:
    1. create a space on the ISeries in QTEMP with an initial size.
    2. close the space locally so the host list API can access it.
    3. call the host API which populates and if necessary extends the user space.
    4. re-open the space locally and read its contents.
    5. close the space locally again in preparation for the next call.
    The following methods in this base class facilitate this:
  • Constructor: will initialize the user space name and library.
  • getUserSpaceAPIName(): returns byte array with userspace name in format needed by host API parms.
  • createUserSpaceOnHost():will create the user space on the host. Will close the user space object locally so the user space is free to be used by the host API.
  • getUserSpace(): will create a local user space object if there is not one already.
  • closeUserSpace(): closes the local UserSpace object so it is not locked anymore.
  • readUserSpace(int,int) and readUserSpace(byte[], int)


    Nested Class Summary
    static class ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure
              ==================================================================== HostAPIErrorCodeStructure ------------------------- Nested helper class to facilitate creating and subsequent parsing of the common ISeries error code structure that many APIs take as input and populate.
     
    Field Summary
    protected  boolean cancel
               
    protected  List cancellableSubTasks
               
    protected  IISeriesHostListStatusCallback cancelQuerier
               
    static String Copyright
               
    protected static boolean CREATE_FALSE
               
    protected static boolean CREATE_TRUE
               
    protected static Hashtable dbcsConvert
               
    protected static IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_BASIC
               
    protected static IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_BRIEF
               
    protected static IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_EXHAUSTIVE
               
    protected static IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_NAMEONLY
               
    protected  ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure errorcodeObj
               
    protected static Hashtable hostAPILibraries
               
    static int INFOLEVEL_BASIC
               
    static int INFOLEVEL_BRIEF
               
    static int INFOLEVEL_EXHAUSTIVE
               
    static int INFOLEVEL_NAME
               
    static int INFOLEVEL_NAMEARRAY
               
    protected static int INITIAL_SPACESIZE
               
    protected static String LOG_DIR
               
    protected static String LOG_FILENAME
               
    protected static File logFile
               
    protected static PrintWriter logFileStream
               
    protected static int logLineCounter
               
    protected static boolean logStandardOut
               
    protected static boolean NEED_USERSPACE_NO
               
    protected static boolean NEED_USERSPACE_YES
               
    protected  String objName
               
    protected  String objType
               
    static ISeriesHostObjectBasic QVDEOBJLinfo
               
    protected  IISeriesHostObjectFactory returnObjectFactory
               
    protected  List todos
               
    protected  String tracePrefix
               
    protected  List warnings
               
     
    Constructor Summary
    ISeriesAbstractHostAPIProcessor()
              Constructor when there is no AS400 system object.
    ISeriesAbstractHostAPIProcessor(AS400 system)
              Constructor when there is an AS400 system object.
     
    Method Summary
    protected  void addCancellableSubTask(ISeriesAbstractHostAPIProcessor subTask)
              For child classes to register cancellable subtasks they spawn.
    protected  void addWarning(String warning)
              Log a warning that can be retrieved by callers
     void cancel()
              Cancel the listing process.
    protected  void clearWarnings()
              Clear warnings.
    protected  void closeUserSpace()
              Close local userspace object.
    protected  long computeSize(int size, int sizeMultiplier)
              Calculate object size given size and size multiplier
    protected  void createUserSpaceOnHost()
              Create a User Space on the AS/400.
    protected  int determineInfoLevel(IISeriesHostObjectNameOnly obj)
              Examine an object returned by the supplied object factory to determine what information level is requested by the caller.
     int getClientCCSID()
              Get the CCSID used for client side text
    protected  IISeriesHostObjectFactory getDefaultObjectFactory()
              Get default object factory used to create new objects.
    protected  ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure getErrorCodeStructure()
              Return instance of HostAPIErrorCodeStructure
     int getHostCCSID()
              Get the CCSID used for host side text
    protected  String getLibrary()
              Return library that is the context for items in this list.
     PrintWriter getLogFileStream()
              Helper when calling printStackTrace
    protected  IISeriesHostObjectFactory getObjectFactory()
              Get object factory used to create new objects.
    protected  String getObjectName()
              Get the object name to used in the list processing.
    protected  String getObjectType()
              Get the object type to use in the list processing.
     AS400 getSystem()
              Return AS400 object used for this list processor
    protected  UserSpace getUserSpace()
              Create a local UserSpace object, if not already created, and return reference to it.
    protected  byte[] getUserSpaceAPIName()
              Return qualified user space name as a byte array ready to use in a host ProgramCall ProgramParameter.
    protected  String getUserSpaceIFSName()
              Return user space name in IFS format.
    protected  String getUserSpaceLibrary()
              Gets the userspace Library name.
    protected  String getUserSpaceName()
              Gets the userspace Name
     List getWarnings()
              Get warnings issued by this api call.
     boolean isCancelled()
              Queried internally to see if request has been cancelled, and available after the getList call to see if this list was cancelled versus ending normally.
     boolean isTraceOn()
              Query tracing
     void logException(Exception exc)
              Helper method for logging trace information for an exception
    protected  String logHostMessages(ProgramCall pcObj, String apiName)
              Logs system messages in the message queue, after an API call.
     void logMessage()
              Helper method for logging a blank line
     void logMessage(String msg)
              Helper method for logging trace information
    static void logMessage(String tracePrefix, String msg)
              Helper STATIC method for logging trace information
     void logTodo(String todo, String methodName)
              Helper method for logging a TODO item so we don't forget
    protected  void openUserSpace()
              Open local userspace object.
    static String padString(String input, int padlen)
              Pad given string with blanks to given length.
    protected static Date parseBin8Date(long milliseconds)
              Helper method to parse dates returned in epoch format
    protected static Date parseChar13Date(String javaTxt)
              Helper method to parse date+times returned in CYYMMDDHHMMSS format
    protected static Date parseChar7Date(String javaTxt)
              Helper method to parse dates returned in CYYMMDD format
    protected static Date parseChar8Date(String javaTxt)
              Helper method to parse dates returned in system format (char 8) format
    protected  int readUserSpace(byte[] byte400, int start)
              Given an existing and opened user space (in instance variable), this method reads the space until end, starting at the given offset.
    protected  byte[] readUserSpace(int start, int len)
              Given an existing and opened user space (in instance variable), this method reads the next nn bytes from it.
     void registerCancelQuerier(IISeriesHostListStatusCallback caller)
              Register a caller that can handle the "did user cancel?" request that the list processors will periodically call to check for a user cancel request.
    protected  void removeCancellableSubTask(ISeriesAbstractListProcessor subTask)
              For child classes to de-register cancellable subtasks they spawn.
     void setClientCCSID(int ccsid)
              Set the CCSID used for client side text
     void setHostCCSID(int ccsid)
              Set the CCSID used for host side text
    protected  void setLibrary(String library)
              Set the library which is the context for non *LIB requests
    static void setLogFileDirectory(String dir)
              Call this to specify the directory where logging of comm trace info should happen.
    protected  void setObjectFactory(IISeriesHostObjectFactory factory)
              Set object factory used to create new objects.
    protected  void setObjectName(String name)
              Set the object name to use in the list processing.
    protected  void setObjectType(String type)
              Set the object type to use in the list processing.
     void setSystem(AS400 system)
              Set the AS/400 object used for this list processor.
     void setTracing(boolean trace, String prefix)
              Enable/disable tracing
    protected  void setUserSpaceLibrary(String userSpaceLibrary)
              Sets the userspace library name.
    protected  void setUserSpaceName(String userSpaceName)
              Sets the userspace Name.
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    Copyright

    public static final String Copyright
    See Also:
    Constant Field Values

    LOG_FILENAME

    protected static String LOG_FILENAME

    LOG_DIR

    protected static String LOG_DIR

    logLineCounter

    protected static int logLineCounter

    logFileStream

    protected static PrintWriter logFileStream

    logFile

    protected static File logFile

    logStandardOut

    protected static boolean logStandardOut

    tracePrefix

    protected String tracePrefix

    cancel

    protected boolean cancel

    cancelQuerier

    protected IISeriesHostListStatusCallback cancelQuerier

    cancellableSubTasks

    protected List cancellableSubTasks

    warnings

    protected List warnings

    objName

    protected String objName

    objType

    protected String objType

    todos

    protected List todos

    INFOLEVEL_NAME

    public static final int INFOLEVEL_NAME
    See Also:
    Constant Field Values

    INFOLEVEL_BRIEF

    public static final int INFOLEVEL_BRIEF
    See Also:
    Constant Field Values

    INFOLEVEL_BASIC

    public static final int INFOLEVEL_BASIC
    See Also:
    Constant Field Values

    INFOLEVEL_EXHAUSTIVE

    public static final int INFOLEVEL_EXHAUSTIVE
    See Also:
    Constant Field Values

    INFOLEVEL_NAMEARRAY

    public static final int INFOLEVEL_NAMEARRAY
    See Also:
    Constant Field Values

    DEFAULT_OBJECT_FACTORY_NAMEONLY

    protected static final IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_NAMEONLY

    DEFAULT_OBJECT_FACTORY_BRIEF

    protected static final IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_BRIEF

    DEFAULT_OBJECT_FACTORY_BASIC

    protected static final IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_BASIC

    DEFAULT_OBJECT_FACTORY_EXHAUSTIVE

    protected static final IISeriesHostObjectFactory DEFAULT_OBJECT_FACTORY_EXHAUSTIVE

    returnObjectFactory

    protected IISeriesHostObjectFactory returnObjectFactory

    errorcodeObj

    protected ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure errorcodeObj

    CREATE_TRUE

    protected static final boolean CREATE_TRUE
    See Also:
    Constant Field Values

    CREATE_FALSE

    protected static final boolean CREATE_FALSE
    See Also:
    Constant Field Values

    NEED_USERSPACE_YES

    protected static final boolean NEED_USERSPACE_YES
    See Also:
    Constant Field Values

    NEED_USERSPACE_NO

    protected static final boolean NEED_USERSPACE_NO
    See Also:
    Constant Field Values

    INITIAL_SPACESIZE

    protected static final int INITIAL_SPACESIZE
    See Also:
    Constant Field Values

    hostAPILibraries

    protected static Hashtable hostAPILibraries

    dbcsConvert

    protected static Hashtable dbcsConvert

    QVDEOBJLinfo

    public static ISeriesHostObjectBasic QVDEOBJLinfo
    Constructor Detail

    ISeriesAbstractHostAPIProcessor

    public ISeriesAbstractHostAPIProcessor()
    Constructor when there is no AS400 system object.


    ISeriesAbstractHostAPIProcessor

    public ISeriesAbstractHostAPIProcessor(AS400 system)
    Constructor when there is an AS400 system object.

    Parameters:
    AS400 - system to use for the connection.
    Method Detail

    setSystem

    public void setSystem(AS400 system)
    Set the AS/400 object used for this list processor.


    getSystem

    public AS400 getSystem()
    Return AS400 object used for this list processor


    cancel

    public void cancel()
    Cancel the listing process. This is not possible until the host API call returns, but is checked in the subsequent loops that post process the returned host information. For callers to use this, they will have to call getList in a different thread then this method is called in, else they'll be blocked waiting for getList to return.


    registerCancelQuerier

    public void registerCancelQuerier(IISeriesHostListStatusCallback caller)
    Register a caller that can handle the "did user cancel?" request that the list processors will periodically call to check for a user cancel request. To support this the caller must pass an object implementing IISeriesHostListStatusCallback. The method checkForCancel from that interface will be called.


    addCancellableSubTask

    protected void addCancellableSubTask(ISeriesAbstractHostAPIProcessor subTask)
    For child classes to register cancellable subtasks they spawn.


    removeCancellableSubTask

    protected void removeCancellableSubTask(ISeriesAbstractListProcessor subTask)
    For child classes to de-register cancellable subtasks they spawn.


    isCancelled

    public boolean isCancelled()
                        throws Exception
    Queried internally to see if request has been cancelled, and available after the getList call to see if this list was cancelled versus ending normally. If the caller gave us an object to call to query cancel status, we call it now. If this throws a "OperationCancelled" exception, that will very effectively kill our list processing.

    Throws:
    Exception

    setLibrary

    protected void setLibrary(String library)
    Set the library which is the context for non *LIB requests


    setObjectName

    protected void setObjectName(String name)
    Set the object name to use in the list processing. Can be scalar or generic. Empty or null implies *.


    setObjectType

    protected void setObjectType(String type)
    Set the object type to use in the list processing. Must be scalar or *. Empty or null implies *.


    getLibrary

    protected String getLibrary()
    Return library that is the context for items in this list.


    getObjectName

    protected String getObjectName()
    Get the object name to used in the list processing. Can be scalar or generic. Empty or null implies *.


    getObjectType

    protected String getObjectType()
    Get the object type to use in the list processing. Can be scalar or generic. Empty or null implies *.


    setObjectFactory

    protected void setObjectFactory(IISeriesHostObjectFactory factory)
    Set object factory used to create new objects. This is given to us by the caller, or else we use a default.


    getObjectFactory

    protected IISeriesHostObjectFactory getObjectFactory()
    Get object factory used to create new objects. This is given to us by the caller, or else we use a default.


    getDefaultObjectFactory

    protected IISeriesHostObjectFactory getDefaultObjectFactory()
    Get default object factory used to create new objects. This is used when caller does not give us their own factory. Child classes who by default want to return more or less info than prescribed by the IISeriesHostObjectBasic interface should override this method.


    determineInfoLevel

    protected int determineInfoLevel(IISeriesHostObjectNameOnly obj)
    Examine an object returned by the supplied object factory to determine what information level is requested by the caller. For performance reasons, only call this once per list request and store the result.


    setHostCCSID

    public void setHostCCSID(int ccsid)
    Set the CCSID used for host side text


    getHostCCSID

    public int getHostCCSID()
    Get the CCSID used for host side text


    setClientCCSID

    public void setClientCCSID(int ccsid)
    Set the CCSID used for client side text


    getClientCCSID

    public int getClientCCSID()
    Get the CCSID used for client side text


    getUserSpaceLibrary

    protected String getUserSpaceLibrary()
    Gets the userspace Library name.


    setUserSpaceLibrary

    protected void setUserSpaceLibrary(String userSpaceLibrary)
    Sets the userspace library name.


    setUserSpaceName

    protected void setUserSpaceName(String userSpaceName)
    Sets the userspace Name.


    getUserSpaceName

    protected String getUserSpaceName()
    Gets the userspace Name


    getUserSpaceIFSName

    protected String getUserSpaceIFSName()
    Return user space name in IFS format.


    getUserSpaceAPIName

    protected byte[] getUserSpaceAPIName()
    Return qualified user space name as a byte array ready to use in a host ProgramCall ProgramParameter.


    createUserSpaceOnHost

    protected void createUserSpaceOnHost()
                                  throws Exception
    Create a User Space on the AS/400. Please note this subsequently closes and dismisses the local toolbox UserSpace object for it so the space is not locked and hence is available for the host API to do its thing with it. To optimize performance, we will only create our uniquely-named user space once on the host, and never delete it. We can do this because we create it in library QTEMP. This allows subsequent list requests with this same object to go a little faster.

    Throws:
    Exception

    getUserSpace

    protected UserSpace getUserSpace()
    Create a local UserSpace object, if not already created, and return reference to it.


    closeUserSpace

    protected void closeUserSpace()
    Close local userspace object.


    openUserSpace

    protected void openUserSpace()
                          throws Exception
    Open local userspace object.

    Throws:
    Exception

    readUserSpace

    protected byte[] readUserSpace(int start,
                                   int len)
                            throws Exception
    Given an existing and opened user space (in instance variable), this method reads the next nn bytes from it.

    Returns:
    byte array populated with data read.
    Throws:
    Exception

    readUserSpace

    protected int readUserSpace(byte[] byte400,
                                int start)
                         throws Exception
    Given an existing and opened user space (in instance variable), this method reads the space until end, starting at the given offset.

    Parameters:
    byte - array to read into.
    offest - to start reading. Read continues until end of data.
    Returns:
    number of bytes actually read
    Throws:
    Exception

    padString

    public static String padString(String input,
                                   int padlen)
    Pad given string with blanks to given length. If input is greater than given length, truncate.


    parseChar13Date

    protected static Date parseChar13Date(String javaTxt)
    Helper method to parse date+times returned in CYYMMDDHHMMSS format


    parseChar7Date

    protected static Date parseChar7Date(String javaTxt)
    Helper method to parse dates returned in CYYMMDD format


    parseChar8Date

    protected static Date parseChar8Date(String javaTxt)
    Helper method to parse dates returned in system format (char 8) format


    parseBin8Date

    protected static Date parseBin8Date(long milliseconds)
    Helper method to parse dates returned in epoch format


    computeSize

    protected long computeSize(int size,
                               int sizeMultiplier)
    Calculate object size given size and size multiplier


    setTracing

    public void setTracing(boolean trace,
                           String prefix)
    Enable/disable tracing


    isTraceOn

    public boolean isTraceOn()
    Query tracing


    logMessage

    public void logMessage(String msg)
    Helper method for logging trace information


    logMessage

    public void logMessage()
    Helper method for logging a blank line


    logTodo

    public void logTodo(String todo,
                        String methodName)
    Helper method for logging a TODO item so we don't forget


    logException

    public void logException(Exception exc)
    Helper method for logging trace information for an exception


    logMessage

    public static void logMessage(String tracePrefix,
                                  String msg)
    Helper STATIC method for logging trace information


    setLogFileDirectory

    public static void setLogFileDirectory(String dir)
    Call this to specify the directory where logging of comm trace info should happen.


    getLogFileStream

    public PrintWriter getLogFileStream()
    Helper when calling printStackTrace


    logHostMessages

    protected String logHostMessages(ProgramCall pcObj,
                                     String apiName)
    Logs system messages in the message queue, after an API call. Primarily for debugging purposes, although might be useful too for servicing purposes.

    Parameters:
    the - ProgramCall object that was used to make the call.
    the - name of the host API that was called.
    Returns:
    the text of the first message in the queue or null if empty.

    addWarning

    protected void addWarning(String warning)
    Log a warning that can be retrieved by callers


    clearWarnings

    protected void clearWarnings()
    Clear warnings. Should be called at start of getList.


    getWarnings

    public List getWarnings()
    Get warnings issued by this api call. This returns and then clears the warning list.

    Specified by:
    getWarnings in interface IISeriesAPIProcessor
    Returns:
    a List of strings or null if no warnings.

    getErrorCodeStructure

    protected ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure getErrorCodeStructure()
    Return instance of HostAPIErrorCodeStructure


    Rational Developer for Power Systems Software
    V7.6

    Copyright 2011 IBM Corp. All Rights Reserved.

    Note: This documentation is for part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.