com.ibm.etools.iseries.comm
Class ISeriesAbstractHostAPIProcessor

java.lang.Object
  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