public class CatalogSearch
extends java.lang.Object
implements java.util.Iterator
Usage Information:
addFieldName(String)
.
search()
method.
Iterator
interface, so next()
and hasNext() can be used to iterate over the returned results.
next()
returns a CatalogSearch.Entry
. This entry is either
a catalog entry or dataset entry. A catalog entry is returned at the beginning of
each work area and whenever a new catalog is encountered by the
Catalog Search Interface (CSI). Dataset entries are returned for each dataset that
matches the filter key.
CatalogSearch.Entry.getField(String)
method can be
used to retrieve any of the fields requested with the search criteria. Fields are
returned as instances of CatalogSearchField
.
hasNext()
returns false.
Error handling: This class provides access to all of the error information emitted by the Catalog Search Interface.
RcException
is thrown. If the
return code is either 4 or 8, additional information can be obtained by examining
the catalog search reason area (methods getRc()
and getReason()
).
CatalogSearch.Entry.hasError()
, CatalogSearch.Entry.getRc()
, and CatalogSearch.Entry.getReason()
can be used to obtain more information about entry level errors.
For detailed information on the Catalog Search Interface, including specific steps for handling individual error conditions, see Appendix C of the following:
This Uses JNI wrappers to the Catalog Search Interface (IGGCSI00).
Modifier and Type | Class and Description |
---|---|
static class |
CatalogSearch.Entry
A static nested class of CatalogSearch which holds a catalog search
entry.
|
Modifier and Type | Field and Description |
---|---|
static byte |
CATALOG_TYPE
Type value returned for Catalogs.
|
static int |
DEFAULT_WORK_AREA_LENGTH
The default work area size for returned entry information.
|
static byte |
FLAG_CSICERR
Catalog flag information - Whole catalog not processed due to error.
|
static byte |
FLAG_CSICERRP
Catalog flag information - Catalog partially processed due to error.
|
static byte |
FLAG_CSIEDATA
Catalog Entry flag information - Data is returned for this entry.
|
static byte |
FLAG_CSIENTER
Catalog Entry flag information - Error indication is set for this entry and error code follows CSIENAME.
|
static byte |
FLAG_CSINOENT
Catalog flag information - No entry found for this catalog.
|
static byte |
FLAG_CSINTCMP
Catalog flag information - Data gotten for this catalog is not complete.
|
static byte |
FLAG_CSINTICF
Catalog flag information - Not Supported.
|
static byte |
FLAG_CSIPMENT
Catalog Entry flag information - Primary entry.
|
static int |
MAX_FIELD_NAMES
The maximum number of field names that may be specified on a search
|
static int |
MAX_WORK_AREA_LENGTH
The maximum allowable work area size
|
static int |
MIN_WORK_AREA_LENGTH
The minimum allowable work area size
|
Constructor and Description |
---|
CatalogSearch(java.lang.String filterKey)
Construct a CatalogSearch with a filterKey and default work area.
|
CatalogSearch(java.lang.String filterKey,
int workAreaLength)
Construct a CatalogSearch with a filterKey and custom work area.
|
Modifier and Type | Method and Description |
---|---|
void |
addFieldName(java.lang.String fieldName)
Specify a field name to be returned with the search results.
|
void |
discardCurrentWorkArea()
Discard the unprocessed work area data.
|
java.lang.String |
getCatalogName()
Return the catalog name.
|
java.lang.String |
getEntryTypes()
Return the entry types.
|
java.util.List |
getFieldNames()
Return the list of field names that have been set via
addFieldName(String) . |
java.lang.String |
getFilterKey()
Return the current filter key.
|
java.lang.String |
getModuleId()
Return the reason area module id.
|
int |
getRc()
Return the reason area return code.
|
int |
getReason()
Return the reason area reason code.
|
java.lang.String |
getResumeName()
Return the resume name.
|
boolean |
hasNext()
Return true if there is at least one more entry available from the search, false
otherwise.
|
boolean |
isClusterNameMatch()
Return true if the cluster name match flag is set
|
boolean |
isFullwordLengths()
Return true if the variable field data lengths are fullwords (4 bytes).
|
boolean |
isResume()
Return the resume flag, set by catalog search when more search results exist than could fit
in the supplied work area.
|
boolean |
isSingleCatalog()
Return true if the single catalog flag is set.
|
java.lang.Object |
next()
Return the next Entry from the search.
|
void |
remove()
Unsupported Iterator interface method
|
void |
removeFieldName(java.lang.String fieldName)
Remove a field name that had previously been set.
|
void |
search()
Initiate the catalog search.
|
void |
setCatalogName(java.lang.String catalogName)
Set the name of the catalog to search.
|
void |
setClusterNameMatch(boolean clusterNameMatch)
Sets the cluster name match flag.
|
void |
setEntryTypes(java.lang.String entryTypes)
Set the entry types to be returned with the search.
|
void |
setFilterKey(java.lang.String filterKey)
Sets the filter key for the search.
|
void |
setFullwordLengths(boolean fullwordLengths)
Specify whether the data lengths for variable field data are 4 bytes or 2 bytes.
|
void |
setResumeName(java.lang.String resumeName)
Set the resume name for an active, resumable search.
|
void |
setSingleCatalog(boolean singleCatalog)
Specify whether a single catalog is to be searched.
|
boolean |
workAreaHasNext()
Indicates if the current work area has been completely processed.
|
public static final byte CATALOG_TYPE
public static final byte FLAG_CSINTICF
public static final byte FLAG_CSINOENT
public static final byte FLAG_CSINTCMP
public static final byte FLAG_CSICERR
public static final byte FLAG_CSICERRP
public static final byte FLAG_CSIPMENT
public static final byte FLAG_CSIENTER
public static final byte FLAG_CSIEDATA
public static final int DEFAULT_WORK_AREA_LENGTH
public static final int MIN_WORK_AREA_LENGTH
public static final int MAX_WORK_AREA_LENGTH
public static final int MAX_FIELD_NAMES
public CatalogSearch(java.lang.String filterKey)
filterKey
- the search string.public CatalogSearch(java.lang.String filterKey, int workAreaLength)
filterKey
- the search string.workAreaLength
- the size of the work area to be returned by the
catalog search interface.java.lang.IllegalArgumentException
- if the workAreaLength is too small or
too large.public void setFilterKey(java.lang.String filterKey)
If performed on an active resumable search, the remainder of the current work area will be discarded.
java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public java.lang.String getFilterKey()
public void setCatalogName(java.lang.String catalogName)
The default value is spaces (not set).
If performed on an active resumable search, the remainder of the current work area will be discarded.
catalogName
- the catalogName to search. If null (the default), Catalog Management
will attempt to use the high-level qualifier of the filter key to locate an alias that
matches. If an alias is found, the user catalog for that alias will be searched; then,
the master catalog will be searched. The master catalog will not be searched if
single catalog searching is set. If no alias is found, only the master catalog will be searched.java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.setSingleCatalog(boolean)
,
isResume()
,
discardCurrentWorkArea()
public java.lang.String getCatalogName()
public void setResumeName(java.lang.String resumeName)
This setter can be used to "skip ahead" past a specific Dataset Name when a wide filter key is used, but only specific names need to be processed.
If performed on an active resumable search, the remainder of the current work area will be discarded.
resumeName
- the entry (Dataset) name to resume afterjava.lang.IllegalStateException
- if the search is not active or performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public java.lang.String getResumeName()
java.lang.IllegalStateException
- if the search is not active or performed on an active search that cannot be resumed.public void setEntryTypes(java.lang.String entryTypes)
entryTypes
- determines what type of catalog entries will be returned.
Valid types for CSIDTYPS are:
The valid types can be mixed and in any order. Blanks cannot separate the types. For instance, "ABH" might be specified to get only the non-VSAM, generation data group and generation data set entries. The default (null or empty string) will get types A, B, C, G, H, R, X, U. These are the catalog types. L and W must be explicitly specified in order to get the Tape Volume Catalog entries.
If performed on an active resumable search, the remainder of the current work area will be discarded.
java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public java.lang.String getEntryTypes()
public void setClusterNameMatch(boolean clusterNameMatch)
For VSAM datasets, the data and index names do not always match the cluster name. If this flag is true, the data and index names will be returned when the cluster name matches the filter key, even if they don't match themselves.
The default is false
If performed on an active resumable search, the remainder of the current work area will be discarded.
clusterNameMatch
- true for data and index names to always be returned when the cluster name
matches the filter key.java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public boolean isClusterNameMatch()
public void setFullwordLengths(boolean fullwordLengths)
fullwordLengths
- if true, 4 byte data lengths will be used. If false (the default)
2 bytes lengths will be used.java.lang.IllegalStateException
- if called on an active searchpublic boolean isFullwordLengths()
public boolean isResume()
java.lang.IllegalStateException
- if the search is not activepublic void setSingleCatalog(boolean singleCatalog)
If performed on an active resumable search, the remainder of the current work area will be discarded.
singleCatalog
- if true, only a single catalog will be searched. If false
(the default) multiple catalogs will be searched.java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
,
setCatalogName(String)
public boolean isSingleCatalog()
public void addFieldName(java.lang.String fieldName)
If performed on an active resumable search, the remainder of the current work area will be discarded.
fieldName
- a field to return in the search results.java.lang.IllegalArgumentException
- if more than MAX_FIELD_NAMES
fields are added.java.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public void removeFieldName(java.lang.String fieldName)
If performed on an active resumable search, the remainder of the current work area will be discarded.
fieldName
- the field to remove from search resultsjava.lang.IllegalStateException
- if performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public java.util.List getFieldNames()
addFieldName(String)
.public void search()
hasNext()
and next()
can be used.
Subsequent calls to this method will cause the existing work area to be
discarded. A new work area will be filled by calling the native CatalogSearch
Interface if more search results are available ( isResume()
== true)
RcException
- if an error is encountered. See the class comment and the
Catalog Search documentation for more information on how to interpret the error
information.public int getRc()
java.lang.IllegalStateException
- if the search is not activepublic int getReason()
java.lang.IllegalStateException
- if the search is not activepublic java.lang.String getModuleId()
java.lang.IllegalStateException
- if the search is not activepublic boolean hasNext()
hasNext
in interface java.util.Iterator
java.lang.IllegalStateException
- if the search is not activepublic java.lang.Object next()
next
in interface java.util.Iterator
java.lang.IllegalStateException
- if the search is not activejava.util.NoSuchElementException
- if all entries have been returnedRcException
- if an error is encountered. See the class comment and the
Catalog Search documentation for more information on how to interpret the error
information.public void remove()
remove
in interface java.util.Iterator
public boolean workAreaHasNext()
Note that this test indicates if the current work area has been processed, but does not
report on the overall status of the search. hasNext()
can be used to determine
if a search is complete.
Note that any change to the selection criteria on an active search will cause the current work area to be discarded. This is often the desired result. However, to ensure that all search results for a given catalog search processed, this method should return false prior to changing any of the selection criteria.
java.lang.IllegalStateException
- if the search is not activepublic void discardCurrentWorkArea()
If the search is resumable, a call to next()
will cause CatalogSearch to be invoked,
refilling the work area with new results. If the search is not resumable, hasNext()
will return false.
This method is called automatically when the selection criteria change for an active search.
java.lang.IllegalStateException
- if the search is not activefor information about processing all search results for a given
catalog search.