com.ibm.etools.iseries.comm
Class ISeriesListFields

java.lang.Object
  com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor
      com.ibm.etools.iseries.comm.ISeriesListFields

All Implemented Interfaces:

IISeriesAPIProcessor, IISeriesListProcessor

public class ISeriesListFields
extends ISeriesAbstractHostAPIProcessor
implements IISeriesListProcessor

A class for listing fields in a *FILE object on an ISeries. This is done by calling the system API QUSLFLD.

You must first decide how much information you want returned for each field found in the given file(s) and then call the appropriate method for that list type.

LIST_NAMES -> return only the field names. Use getListNameOnly(ISeriesAbstractFilterString)

LIST_BASIC -> return commonly needed field information. getList(ISeriesAbstractFilterString) The output of the list request is a List of objects that implement an interface that is dependent on the type of list requested:

LIST_NAMES -> returns objects that implement IISeriesHostFieldNameOnly

LIST_BASIC -> returns objects that implement IISeriesHostFieldBasic

For some callers, it is important for performance to get a list of their own objects, versus a list of objects of a hard-coded class that just needs to be subsequently traversed and the data copied. To enable this, use the method getList(ISeriesAbstractFilterString, IISeriesHostListBaseFactory, IISeriesHostListStatusCallback). This requires an object implementing IISeriesHostListFieldFactory which is used to create each object returned in the list. Depending on the list type (LIST_NAME, LIST_BASIC) specified in the third parameter, either the createNameOnlyObject or createFielddObject method will be called to create each object returned. These must return objects that implement IISeriesHostFieldNameOnly or IISeriesHostFieldBasic respectively.

Finally, it is possible to list fields in not just one file, but multiple files if a generic library, file or record name is specified. In this case, GUI callers can specify an object to call back to as the list processing starts for each record. This is handy for updating status dialogs. The method to use in this case is: getList(ISeriesAbstractFilterString, IISeriesHostListBaseFactory, IISeriesHostListStatusCallback).

Nested Class Summary

Nested classes/interfaces inherited from class com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor

ISeriesAbstractHostAPIProcessor.HostAPIErrorCodeStructure

Field Summary

static String	Copyright
protected static IISeriesHostListFieldFactory	DEFAULT_LISTFIELD_FACTORY_NAMEARRAY For listing names only returning a string array.
static int	LIST_BASIC Return list with basic information per field (IISeriesHostFieldBasic)
static int	LIST_NAMES Return list of names only.

Fields inherited from class com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor

cancel, cancellableSubTasks, cancelQuerier, CREATE_FALSE, CREATE_TRUE, dbcsConvert, DEFAULT_OBJECT_FACTORY_BASIC, DEFAULT_OBJECT_FACTORY_BRIEF, DEFAULT_OBJECT_FACTORY_EXHAUSTIVE, DEFAULT_OBJECT_FACTORY_NAMEONLY, errorcodeObj, hostAPILibraries, INFOLEVEL_BASIC, INFOLEVEL_BRIEF, INFOLEVEL_EXHAUSTIVE, INFOLEVEL_NAME, INFOLEVEL_NAMEARRAY, INITIAL_SPACESIZE, LOG_DIR, LOG_FILENAME, logFile, logFileStream, logLineCounter, logStandardOut, NEED_USERSPACE_NO, NEED_USERSPACE_YES, objName, objType, QVDEOBJLinfo, returnObjectFactory, todos, tracePrefix, warnings

Constructor Summary

ISeriesListFields()
Constructor used when you do not have an AS400 object already.

ISeriesListFields(AS400 system)
Constructor when there is an existing AS400 object.

Method Summary

protected void	buildList(int nbrRows, int listStartingPosition, int sizePerRow) Build the list.
protected void	buildList0200(int nbrRows, int listStartingPosition, int listSize) Build the list.
List	getFieldList(ISeriesFieldFilterString fsObj) Retrieve a list of fields, returning all the information available for fields.
List	getFieldList(ISeriesFieldFilterString fsObj, IISeriesHostListFieldFactory listFieldFactory) Retrieve a list of fields, returning objects created by a supplied object factory.
List	getFieldList(ISeriesFieldFilterString fsObj, IISeriesHostListFieldFactory listFieldFactory, IISeriesHostListStatusCallback callback) Retrieve a list of fields, informing the caller when processing starts for each part of a multi-generic list.
List	getFieldListNameOnly(ISeriesFieldFilterString fsObj) Retrieve a list of fields, returning only the name per field.
boolean	getFileOverride() Query whether this list processor honors file override information
protected String	getFilterString() Return the filter string used for this list request.
protected ISeriesFieldFilterString	getFilterStringObject() Return the filter string object used for this list request.
List	getList(ISeriesAbstractFilterString fsObj) As per the IISeriesListProcessor interface requirements.
List	getList(ISeriesAbstractFilterString fsObj, IISeriesHostListBaseFactory listFactory) Retrieve a list of fields, returning objects created by a supplied object factory.
List	getList(ISeriesAbstractFilterString fsObj, IISeriesHostListBaseFactory listFactory, IISeriesHostListStatusCallback callback) Retrieve a list of fields, informing the caller when processing starts for each part of a multi-generic list.
List	getListBrief(ISeriesAbstractFilterString fsObj) As per the IISeriesListProcessor interface requirements.
protected IISeriesHostListFieldFactory	getListFieldFactory() Get object factory used to create new objects.
protected void	getListFromAS400(String filterString) Call QUSLFLD on AS/400 to get the list.
ISeriesListFieldsHeader	getListHeader() This method returns the Record list header information.
String[]	getListNameArray(ISeriesAbstractFilterString fsObj) Retrieve list of names-only as an array of strings.
List	getListNameOnly(ISeriesAbstractFilterString fsObj) As per the IISeriesListProcessor interface requirements.
int	getListType() Retrieve file override value.
protected void	populateObj(byte[] dftValue) Build a return object with information for one field object.
void	setFileOverride(boolean override) Specify whether file overrides are honored or not during list processing.
protected void	setFilterStringObj(ISeriesFieldFilterString fsObj) Set the filter string used for this list request.
protected void	setListFieldFactory(IISeriesHostListFieldFactory factory) Set list field factory used to create new objects.
void	setListType(int listType) Set the list type.
void	setSystem(AS400 system) Set the AS/400 object used for this list processor.

Methods inherited from class com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor

addCancellableSubTask, addWarning, cancel, clearWarnings, closeUserSpace, computeSize, createUserSpaceOnHost, determineInfoLevel, getClientCCSID, getDefaultObjectFactory, getErrorCodeStructure, getHostCCSID, getLibrary, getLogFileStream, getObjectFactory, getObjectName, getObjectType, getSystem, getUserSpace, getUserSpaceAPIName, getUserSpaceIFSName, getUserSpaceLibrary, getUserSpaceName, getWarnings, isCancelled, isTraceOn, logException, logHostMessages, logMessage, logMessage, logMessage, logTodo, openUserSpace, padString, parseBin8Date, parseChar13Date, parseChar7Date, parseChar8Date, readUserSpace, readUserSpace, registerCancelQuerier, removeCancellableSubTask, setClientCCSID, setHostCCSID, setLibrary, setLogFileDirectory, setObjectFactory, setObjectName, setObjectType, setTracing, setUserSpaceLibrary, setUserSpaceName

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.ibm.etools.iseries.comm.interfaces.IISeriesAPIProcessor

getWarnings

Field Detail

Copyright

public static final String Copyright

See Also:

Constant Field Values

LIST_NAMES

public static final int LIST_NAMES

Return list of names only.

See Also:

Constant Field Values

LIST_BASIC

public static final int LIST_BASIC

Return list with basic information per field (IISeriesHostFieldBasic)

See Also:

Constant Field Values

DEFAULT_LISTFIELD_FACTORY_NAMEARRAY

protected static final IISeriesHostListFieldFactory DEFAULT_LISTFIELD_FACTORY_NAMEARRAY

For listing names only returning a string array. Optimum performance.

Constructor Detail

ISeriesListFields

public ISeriesListFields()

Constructor used when you do not have an AS400 object already. A new AS400 object will be created when getList is called, unless you subsequently call setSystem(AS400) first.

ISeriesListFields

public ISeriesListFields(AS400 system)

Constructor when there is an existing AS400 object.

Parameters:

AS400 - system to use for the connection.

Method Detail

setFileOverride

public void setFileOverride(boolean override)

Specify whether file overrides are honored or not during list processing.

Parameters:

true=>honor - overrides, false=>do not honor overrides

getFileOverride

public boolean getFileOverride()

Query whether this list processor honors file override information

getListNameOnly

public List getListNameOnly(ISeriesAbstractFilterString fsObj)
                     throws Exception

As per the IISeriesListProcessor interface requirements. Not typesafe. Retrieve a list of fields, returning only the name per field.

Same as getFieldListNameOnly(ISeriesFieldFilterString)

Specified by:

getListNameOnly in interface IISeriesListProcessor

Returns:

List of ISeriesHostFieldNameOnly objects.

Throws:

Exception

getListNameArray

public String[] getListNameArray(ISeriesAbstractFilterString fsObj)
                          throws Exception

Retrieve list of names-only as an array of strings. Super efficient!!

Returns:

Array of names matching filtering criteria. May return null if the list is empty!

Throws:

Exception

getListBrief

public List getListBrief(ISeriesAbstractFilterString fsObj)
                  throws Exception

As per the IISeriesListProcessor interface requirements. Not typesafe. Retrieve a list of fields, returning only minimal info field. For fields, this request is the same as getList(ISeriesAbstractFilterString)!

Specified by:

getListBrief in interface IISeriesListProcessor

Throws:

Exception

getList

public List getList(ISeriesAbstractFilterString fsObj)
             throws Exception

As per the IISeriesListProcessor interface requirements. Not typesafe. Retrieve a list of fields, returning more info than just name.

Same as getFieldList(ISeriesFieldFilterString)

Specified by:

getList in interface IISeriesListProcessor

Returns:

List of ISeriesHostFieldBasic objects.

Throws:

Exception

getList

public List getList(ISeriesAbstractFilterString fsObj,
                    IISeriesHostListBaseFactory listFactory)
             throws Exception

Retrieve a list of fields, returning objects created by a supplied object factory.

As per the IISeriesListProcessor interface requirements. Not typesafe.

Specified by:

getList in interface IISeriesListProcessor

Throws:

Exception

See Also:

getFieldList(ISeriesFieldFilterString, IISeriesHostListFieldFactory)

getList

public List getList(ISeriesAbstractFilterString fsObj,
                    IISeriesHostListBaseFactory listFactory,
                    IISeriesHostListStatusCallback callback)
             throws Exception

Retrieve a list of fields, informing the caller when processing starts for each part of a multi-generic list.

As per the IISeriesListProcessor interface requirements. Not typesafe.

Specified by:

getList in interface IISeriesListProcessor

Throws:

Exception

See Also:

getFieldList(ISeriesFieldFilterString, IISeriesHostListFieldFactory, IISeriesHostListStatusCallback)

getFieldListNameOnly

public List getFieldListNameOnly(ISeriesFieldFilterString fsObj)
                          throws Exception

Retrieve a list of fields, returning only the name per field.

Returns:

List of ISeriesHostFieldNameOnly objects.

Throws:

Exception

getFieldList

public List getFieldList(ISeriesFieldFilterString fsObj)
                  throws Exception

Retrieve a list of fields, returning all the information available for fields.

Returns:

List of ISeriesHostFieldBasic objects.

Throws:

Exception

getFieldList

public List getFieldList(ISeriesFieldFilterString fsObj,
                         IISeriesHostListFieldFactory listFieldFactory)
                  throws Exception

Retrieve a list of fields, returning objects created by a supplied object factory. This is the API callers use when they want to create each object in the returned list, perhaps optimized for their environment. If you are ok with the default returned objects, then just use one of the other getList variations. All others internally call this method with a default factory object. Note this supports multi-generic lists, where the library and/or file are generic. In this case, the list of libraries will be retrieved first, then for each library the list of files. Finally, for every resulting file, the record list as requested is retrieved, and for each record the field list. The entire list of all fields is concatenated together and returned as a single list.

Parameters:

fsObj - ISeriesFieldFilterString filter string object identify what list to get. To construct one of these, pass a string of the form library/file RCDNAME(record) FLDNAME(field) to its constructor. The record and field names can simple, * or generic as in A*. Further, the record name can be *FIRST.

listFieldFactory - An object implementing the IISeriesHostListFieldFactory interface. This interface prescribes two methods, and the one called depends on the type of list requested via a previous call to setListType(int):

1. LIST_NAMES calls createNameOnlyObject.
2. LIST_BASIC calls createFieldObject.

Throws:

Exception

See Also:

setListType(int)

getListType

public int getListType()

Retrieve file override value.

Returns:

int

setListType

public void setListType(int listType)

Set the list type. Call before calling any flavor of getList(...). Default is LIST_BASIC.

Parameters:

listType - One of LIST_NAMES, LIST_BASIC depending if you want:

only field names returned.

all field information returned per field.

getFieldList

public List getFieldList(ISeriesFieldFilterString fsObj,
                         IISeriesHostListFieldFactory listFieldFactory,
                         IISeriesHostListStatusCallback callback)
                  throws Exception

Retrieve a list of fields, informing the caller when processing starts for each part of a multi-generic list. This is the same as the getList(ISeriesAbstractFilterString, IISeriesHostListBaseFactory, IISeriesHostListStatusCallback) method, but includes a callback object that is called when processing starts for each part of a multi-generic list request. A multi-generic field list is a request where either the library, file or record name is itself generic, requiring multiple calls to the host to the field list API.

This version of getList is usually used by GUI code that wishes to update a status dialog.

Throws:

Exception

getListHeader

public ISeriesListFieldsHeader getListHeader()

This method returns the Record list header information. This is information pertaining to the file containing the fields, and is the header part of the information returned by the system API QUSLFLD which is used to get the list. THIS METHOD CAN ONLY BE CALLED AFTER CALLING GETLIST. It returns the header information from the previous getList request.

Returns:

ISeriesListFieldsHeader object

getListFromAS400

protected void getListFromAS400(String filterString)
                         throws Exception

Call QUSLFLD on AS/400 to get the list. Updates theFieldList global List

Throws:

Exception

buildList

protected void buildList(int nbrRows,
                         int listStartingPosition,
                         int sizePerRow)
                  throws Exception

Build the list. Parse whole chunk of data by sizePerItem. For each parsed piece, call populateObj to create and populate a returned object, that is added to the list.

This is method for the FLDL0100 format

Overridden from parent.

Updates theFieldList global list.

Throws:

Exception

buildList0200

protected void buildList0200(int nbrRows,
                             int listStartingPosition,
                             int listSize)
                      throws Exception

Build the list. Parse whole chunk of data by sizePerItem. For each parsed piece, call populateObj to create and populate a returned object, that is added to the list.

This is method for the FLDL0200 format

Overridden from parent.

Updates theFieldList global list.

Throws:

Exception

populateObj

protected void populateObj(byte[] dftValue)

Build a return object with information for one field object.

Parameters:

dftValue - the default value byte array already parsed out of the buffer by bldList0200.

setListFieldFactory

protected void setListFieldFactory(IISeriesHostListFieldFactory factory)

Set list field factory used to create new objects. This is given to us by the caller, or else we use a default.

getListFieldFactory

protected IISeriesHostListFieldFactory getListFieldFactory()

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

setFilterStringObj

protected void setFilterStringObj(ISeriesFieldFilterString fsObj)

Set the filter string used for this list request.

getFilterStringObject

protected ISeriesFieldFilterString getFilterStringObject()

Return the filter string object used for this list request.

getFilterString

protected String getFilterString()

Return the filter string used for this list request.

setSystem

public void setSystem(AS400 system)

Description copied from class: ISeriesAbstractHostAPIProcessor

Set the AS/400 object used for this list processor.

Overrides:

setSystem in class ISeriesAbstractHostAPIProcessor