Rational Developer for Power Systems Software
V7.6

com.ibm.etools.iseries.comm
Class ISeriesListRecords

java.lang.Object
  extended by com.ibm.etools.iseries.comm.ISeriesAbstractHostAPIProcessor
      extended by com.ibm.etools.iseries.comm.ISeriesListRecords
All Implemented Interfaces:
IISeriesAPIProcessor, IISeriesListProcessor

public class ISeriesListRecords
extends ISeriesAbstractHostAPIProcessor
implements IISeriesListProcessor

A class for listing records in a *FILE object on an iSeries. This is done by calling the system API QUSLRCD.

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

  • LIST_NAMES -> return only the record names. Use getListNameOnly(ISeriesAbstractFilterString)
  • LIST_BASIC -> return information common to records in database and device files getList(ISeriesAbstractFilterString)
  • LIST_DEVICE -> returns information unique to record in device files getRecordListForDeviceFiles(ISeriesRecordFilterString) 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 IISeriesHostRecordNameOnly
  • LIST_BASIC -> returns objects that implement IISeriesHostRecordBasic
  • LIST_DEVICE -> returns objects that implement IISeriesHostRecordDevice

    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 IISeriesHostListRecordFactory which is used to create each object returned in the list. Depending on the list type (LIST_NAME, LIST_BASIC or LIST_DEVICE) specified in the third parameter, either the createNameOnlyObject, createRecordObject or createDeviceRecordObject method will be called to create each object returned. These must return objects that implement IISeriesHostRecordNameOnly, IISeriesHostRecordBasic or IISeriesHostRecordDevice respectively.

    Finally, it is possible to list records in not just one file, but multiple files if a generic file name is specified. In this case, GUI callers can specify an object to call back to as the list processing starts for each file. 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 IISeriesHostListRecordFactory DEFAULT_LISTRECORD_FACTORY_NAMEARRAY
              For listing names only returning a string array.
    static int LIST_BASIC
              Return list with basic information per record (IISeriesHostRecordBasic)
    static int LIST_DEVICE
              Return list with device-file-specific information per record (IISeriesHostRecordDevice)
    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
    ISeriesListRecords()
              Constructor used when you do not have an AS400 object already.
    ISeriesListRecords(AS400 system)
              Constructor when there is an existing AS400 object.
     
    Method Summary
    protected  void buildList(int nbrRows, int listStartingPosition, int sizePerRow)
              Build the list.
     boolean getFileOverride()
              Query whether this list processor honors file override information
    protected  String getFilterString()
              Return the filter string used for this list request.
    protected  ISeriesRecordFilterString 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 listRecordFactory)
              Retrieve a list of records, returning objects created by a supplied object factory.
     List getList(ISeriesAbstractFilterString fsObj, IISeriesHostListBaseFactory listRecordFactory, IISeriesHostListStatusCallback callback)
              Retrieve a list of records, 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  void getListFromAS400(String filterString)
              Call QUSLRCD on AS/400 to get the list.
     ISeriesListRecordsHeader 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.
    protected  IISeriesHostListRecordFactory getListRecordFactory()
              Get object factory used to create new objects.
     int getListType()
              Retrieve file override value.
     List getRecordList(ISeriesRecordFilterString fsObj)
              Retrieve a list of records, returning information common to records of both database and device files.
     List getRecordList(ISeriesRecordFilterString fsObj, IISeriesHostListRecordFactory listRecordFactory)
              Retrieve a list of records, returning objects created by a supplied object factory.
     List getRecordList(ISeriesRecordFilterString fsObj, IISeriesHostListRecordFactory listRecordFactory, IISeriesHostListStatusCallback callback)
              Retrieve a list of records, informing the caller when processing starts for each part of a multi-generic list.
     List getRecordListForDeviceFiles(ISeriesRecordFilterString fsObj)
              Retrieve a list of records for a device file.
     List getRecordListNameOnly(ISeriesRecordFilterString fsObj)
              Retrieve a list of records, returning only the name per record.
    protected  void populateObj()
              Build a return object with information for one record object.
     void setFileOverride(boolean override)
              Specify whether file overrides are honored or not during list processing.
    protected  void setFilterStringObj(ISeriesRecordFilterString fsObj)
              Set the filter string used for this list request.
    protected  void setListRecordFactory(IISeriesHostListRecordFactory factory)
              Set list record 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 record (IISeriesHostRecordBasic)

    See Also:
    Constant Field Values

    LIST_DEVICE

    public static final int LIST_DEVICE
    Return list with device-file-specific information per record (IISeriesHostRecordDevice)

    See Also:
    Constant Field Values

    DEFAULT_LISTRECORD_FACTORY_NAMEARRAY

    protected static final IISeriesHostListRecordFactory DEFAULT_LISTRECORD_FACTORY_NAMEARRAY
    For listing names only returning a string array. Optimum performance.

    Constructor Detail

    ISeriesListRecords

    public ISeriesListRecords()
    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.


    ISeriesListRecords

    public ISeriesListRecords(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 records, returning only the name per record.

    Same as getListNameOnly(ISeriesAbstractFilterString)

    Specified by:
    getListNameOnly in interface IISeriesListProcessor
    Returns:
    List of ISeriesHostRecordNameOnly 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 records, returning only minimal info per record. For records, 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 records, returning information common to records of both database and device files.

    Specified by:
    getList in interface IISeriesListProcessor
    Returns:
    List of ISeriesHostRecordBasic objects.
    Throws:
    Exception

    getList

    public List getList(ISeriesAbstractFilterString fsObj,
                        IISeriesHostListBaseFactory listRecordFactory)
                 throws Exception
    Retrieve a list of records, 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:
    getRecordList(ISeriesRecordFilterString, IISeriesHostListRecordFactory)

    getList

    public List getList(ISeriesAbstractFilterString fsObj,
                        IISeriesHostListBaseFactory listRecordFactory,
                        IISeriesHostListStatusCallback callback)
                 throws Exception
    Retrieve a list of records, 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:
    getRecordList(ISeriesRecordFilterString, IISeriesHostListRecordFactory, IISeriesHostListStatusCallback)

    getRecordListNameOnly

    public List getRecordListNameOnly(ISeriesRecordFilterString fsObj)
                               throws Exception
    Retrieve a list of records, returning only the name per record. A type-safe overload.

    Returns:
    List of ISeriesHostRecordNameOnly objects.
    Throws:
    Exception

    getRecordList

    public List getRecordList(ISeriesRecordFilterString fsObj)
                       throws Exception
    Retrieve a list of records, returning information common to records of both database and device files. A type-safe overload.

    Returns:
    List of ISeriesHostRecordBasic objects.
    Throws:
    Exception

    getRecordListForDeviceFiles

    public List getRecordListForDeviceFiles(ISeriesRecordFilterString fsObj)
                                     throws Exception
    Retrieve a list of records for a device file.

    Returns:
    List of ISeriesHostRecordDevice objects.
    Throws:
    Exception

    getRecordList

    public List getRecordList(ISeriesRecordFilterString fsObj,
                              IISeriesHostListRecordFactory listRecordFactory)
                       throws Exception
    Retrieve a list of records, returning objects created by a supplied object factory.

    A type-safe overload.

    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. The entire list of all records is concatenated together and returned as a single list.

    Parameters:
    fsObj - ISeriesRecordFilterString filter string object identify what list to get. To construct one of these, pass a string of the form library/file RCDNAME(record) to its constructor. The record name can simple, * or generic as in A*.
    listRecordFactory - An object implementing the IISeriesHostListRecordFactory interface. This interface prescribes three methods, and the one called depends on the type of list requested:
    1. LIST_NAMES calls createNameOnlyObject.
    2. LIST_BASIC calls createRecordObject.
    3. LIST_DEVICE calls createDeviceRecordObject.
    Throws:
    Exception

    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 basic.

    Parameters:
    listType - One of LIST_NAMES, LIST_BASIC, LIST_DEVICE depending if you want:
  • only record names returned.
  • record information common to records of both database and device files
  • record information specific to records of device files

  • getRecordList

    public List getRecordList(ISeriesRecordFilterString fsObj,
                              IISeriesHostListRecordFactory listRecordFactory,
                              IISeriesHostListStatusCallback callback)
                       throws Exception
    Retrieve a list of records, informing the caller when processing starts for each part of a multi-generic list.

    A type-safe overload.

    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 record list is a request where either the library or the file name are themselves generic, requiring multiple calls to the host record list API.

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

    Throws:
    Exception

    getListHeader

    public ISeriesListRecordsHeader getListHeader()
    This method returns the Record list header information. This is information pertaining to the file containing the records, and is the header part of the information returned by the system API QUSLRCD 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:
    ISeriesListRecordsHeader object

    getListFromAS400

    protected void getListFromAS400(String filterString)
                             throws Exception
    Call QUSLRCD on AS/400 to get the list. Updates theRecordList 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. Overridden from parent. Updates theRecordList global list.

    Throws:
    Exception

    populateObj

    protected void populateObj()
    Build a return object with information for one record object.

    Parameters:
    lib - obj to populate
    int - index into the String where item starts.
    param - int

    setListRecordFactory

    protected void setListRecordFactory(IISeriesHostListRecordFactory factory)
    Set list record factory used to create new objects. This is given to us by the caller, or else we use a default.


    getListRecordFactory

    protected IISeriesHostListRecordFactory getListRecordFactory()
    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(ISeriesRecordFilterString fsObj)
    Set the filter string used for this list request.


    getFilterStringObject

    protected ISeriesRecordFilterString 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

    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.