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()
).
In order to interpret these codes, the IBM
lookat facility
can be used along with message ID IDC3009I.
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, see Appendix C of the following:
This Uses JNI wrappers to the Catalog Search Interface (IGGCSI00).
Modifier and Type | Class and Description |
---|---|
class |
CatalogSearch.Entry
A static inner class of CatalogSearch which holds a catalog search
entry.
|
Modifier and Type | Field and Description |
---|---|
static byte |
CATALOG_TYPE |
static int |
DEFAULT_WORK_AREA_LENGTH |
static byte |
FLAG_CSICERR |
static byte |
FLAG_CSICERRP |
static byte |
FLAG_CSIEDATA |
static byte |
FLAG_CSIENTER |
static byte |
FLAG_CSINOENT |
static byte |
FLAG_CSINTCMP |
static byte |
FLAG_CSINTICF |
static byte |
FLAG_CSIPMENT |
static int |
MAX_FIELD_NAMES |
static int |
MAX_WORK_AREA_LENGTH |
static int |
MIN_WORK_AREA_LENGTH |
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() |
java.lang.String |
getEntryTypes() |
java.util.List |
getFieldNames()
Return the list of field names that have been set via
addFieldName(String) . |
java.lang.String |
getFilterKey() |
java.lang.String |
getModuleId()
Return the reason area reason code.
|
int |
getRc()
Return the reason area return code.
|
int |
getReason()
Return the reason area reason code.
|
java.lang.String |
getResumeName() |
boolean |
hasNext()
Return true if there is at least one more entry available from the search, false
otherwise
|
boolean |
isClusterNameMatch() |
boolean |
isFullwordLengths() |
boolean |
isResume() |
boolean |
isSingleCatalog() |
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) |
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 performed on an active search that cannot be resumed.isResume()
,
discardCurrentWorkArea()
public java.lang.String getResumeName()
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. All other positions in CSIDTYPS must be blanks (X'40') when the types are specified. The default (null) 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.
The default value of all spaces => A, B, C, G, H, R, X, U (all non tape volume types)
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()
public 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()
public int getReason()
public java.lang.String getModuleId()
public boolean hasNext()
hasNext
in interface java.util.Iterator
public java.lang.Object next()
next
in interface java.util.Iterator
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 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.