com.ibm.jzos
Class CatalogSearch

java.lang.Object
  extended by com.ibm.jzos.CatalogSearch
All Implemented Interfaces:
java.util.Iterator

public class CatalogSearch
extends java.lang.Object
implements java.util.Iterator

A class that provides a Java interface to the z/OS Catalog Search Interface.

Usage Information:

Error handling: This class provides access to all of the error information emitted by the Catalog Search Interface.

For detailed information on the Catalog Search Interface, see Appendix C of the following:

This Uses JNI wrappers to the Catalog Search Interface (IGGCSI00).


Nested Class Summary
 class CatalogSearch.Entry
          A static inner class of CatalogSearch which holds a catalog search entry.
 
Field Summary
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 Summary
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.
 
Method Summary
 void addFieldName(java.lang.String fieldName)
          Specify a field name to be returned with the search results.
 java.util.List getFieldNames()
          Return the list of field names that have been set via addFieldName(String).
 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.
 boolean hasNext()
          Return true if there is at least one more entry available from the search, false otherwise
 java.lang.Object next()
          Return the next Entry from the search.
 void remove()
          Unsupported Iterator interface method
 void search()
          Initiate the catalog search.
 void setCatalogName(java.lang.String catalogName)
          Set the name of the catalog to search.
 void setEntryTypes(java.lang.String entryTypes)
           
 void setFullwordLengths(boolean fullwordLengths)
          Specify whether the data lengths for variable field data are 4 bytes or 2 bytes.
 void setSingleCatalog(boolean singleCatalog)
          Specify whether a single catalog is to be searched.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CATALOG_TYPE

public static final byte CATALOG_TYPE
See Also:
Constant Field Values

FLAG_CSINTICF

public static final byte FLAG_CSINTICF
See Also:
Constant Field Values

FLAG_CSINOENT

public static final byte FLAG_CSINOENT
See Also:
Constant Field Values

FLAG_CSINTCMP

public static final byte FLAG_CSINTCMP
See Also:
Constant Field Values

FLAG_CSICERR

public static final byte FLAG_CSICERR
See Also:
Constant Field Values

FLAG_CSICERRP

public static final byte FLAG_CSICERRP
See Also:
Constant Field Values

FLAG_CSIPMENT

public static final byte FLAG_CSIPMENT
See Also:
Constant Field Values

FLAG_CSIENTER

public static final byte FLAG_CSIENTER
See Also:
Constant Field Values

FLAG_CSIEDATA

public static final byte FLAG_CSIEDATA
See Also:
Constant Field Values

DEFAULT_WORK_AREA_LENGTH

public static final int DEFAULT_WORK_AREA_LENGTH
See Also:
Constant Field Values

MIN_WORK_AREA_LENGTH

public static final int MIN_WORK_AREA_LENGTH
See Also:
Constant Field Values

MAX_WORK_AREA_LENGTH

public static final int MAX_WORK_AREA_LENGTH
See Also:
Constant Field Values

MAX_FIELD_NAMES

public static final int MAX_FIELD_NAMES
See Also:
Constant Field Values
Constructor Detail

CatalogSearch

public CatalogSearch(java.lang.String filterKey)
Construct a CatalogSearch with a filterKey and default work area.

Parameters:
filterKey - the search string.

CatalogSearch

public CatalogSearch(java.lang.String filterKey,
                     int workAreaLength)
Construct a CatalogSearch with a filterKey and custom work area.

Parameters:
filterKey - the search string.
workAreaLength - the size of the work area to be returned by the catalog search interface.
Throws:
java.lang.IllegalArgumentException - if the workAreaLength is too small or too large.
Method Detail

setCatalogName

public void setCatalogName(java.lang.String catalogName)
Set the name of the catalog to search.

Parameters:
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.
Throws:
java.lang.IllegalStateException - if called on an active search
See Also:
setSingleCatalog(boolean)

setEntryTypes

public void setEntryTypes(java.lang.String entryTypes)
Parameters:
entryTypes - determines what type of catalog entries will be returned. Valid types for CSIDTYPS are:
A
non-VSAM data set
B
Generation data group
C
Cluster
G
Alternate index
H
Generation data set
R
VSAM path
X
Alias
U
User catalog connector entry
L
Tape volume catalog library entry
W
Tape volume catalog volume entry
VSAM components, data and index, are returned with the cluster. Thus, there are no type specifications for them, however, ″D″ and ″I″ types will appear in the output information.

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.

Throws:
java.lang.IllegalStateException - if called on an active search

addFieldName

public void addFieldName(java.lang.String fieldName)
Specify a field name to be returned with the search results. This setter may be called multiple times.

Parameters:
fieldName - a field to return in the search results.
Throws:
java.lang.IllegalArgumentException - if more than MAX_FIELD_NAMES fields are added.
java.lang.IllegalStateException - if called on an active search

setFullwordLengths

public void setFullwordLengths(boolean fullwordLengths)
Specify whether the data lengths for variable field data are 4 bytes or 2 bytes.

Parameters:
fullwordLengths - if true, 4 byte data lengths will be used. If false (the default) 2 bytes lengths will be used.
Throws:
java.lang.IllegalStateException - if called on an active search

setSingleCatalog

public void setSingleCatalog(boolean singleCatalog)
Specify whether a single catalog is to be searched.

Parameters:
singleCatalog - if true, only a single catalog will be searched. If false (the default) multiple catalogs will be searched.
Throws:
java.lang.IllegalStateException - if called on an active search
See Also:
setCatalogName(String)

search

public void search()
Initiate the catalog search. Once this method is called, the Iterator interface methods hasNext() and next() can be used.

Throws:
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.

getRc

public int getRc()
Return the reason area return code. Will be zero unless an RcException has been thrown.


getReason

public int getReason()
Return the reason area reason code. Will be zero unless an RcException has been thrown.


getModuleId

public java.lang.String getModuleId()
Return the reason area reason code. Will be blank unless an RcException has been thrown.


hasNext

public boolean hasNext()
Return true if there is at least one more entry available from the search, false otherwise

Specified by:
hasNext in interface java.util.Iterator

next

public java.lang.Object next()
Return the next Entry from the search.

Specified by:
next in interface java.util.Iterator
Throws:
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.

remove

public void remove()
Unsupported Iterator interface method

Specified by:
remove in interface java.util.Iterator

getFieldNames

public java.util.List getFieldNames()
Return the list of field names that have been set via addFieldName(String).

Returns:
List the field names.