Module ibm.jzos
Package com.ibm.jzos

Class 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:

    • A CatalogSearch instance is constructed with a filter key and an optional workarea size.
    • Selection criteria are set via any of the setXX() methods. Specific fields can be requested via addFieldName(String).
    • The search is initiated by calling the search() method.
    • This class implements the Iterator interface, so next() and hasNext() can be used to iterate over the returned results.
    • Each call to 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.
    • For dataset entries, the 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.
    • The search is complete when hasNext() returns false.

    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, including specific steps for handling individual error conditions, see Appendix C of the following:

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

    Since:
    2.1.0

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CatalogSearch.Entry
      A static nested class of CatalogSearch which holds a catalog search entry.

    • Field Summary

      Fields 
      Modifier and Type Field 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 Summary

      Constructors 
      Constructor 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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.util.Iterator

        forEachRemaining

    • Field Detail

      • CATALOG_TYPE

        public static final byte CATALOG_TYPE
        Type value returned for Catalogs.
        See Also:
        Constant Field Values

      • FLAG_CSINTICF

        public static final byte FLAG_CSINTICF
        Catalog flag information - Not Supported.
        See Also:
        Constant Field Values

      • FLAG_CSINOENT

        public static final byte FLAG_CSINOENT
        Catalog flag information - No entry found for this catalog.
        See Also:
        Constant Field Values

      • FLAG_CSINTCMP

        public static final byte FLAG_CSINTCMP
        Catalog flag information - Data gotten for this catalog is not complete.
        See Also:
        Constant Field Values

      • FLAG_CSICERR

        public static final byte FLAG_CSICERR
        Catalog flag information - Whole catalog not processed due to error.
        See Also:
        Constant Field Values

      • FLAG_CSICERRP

        public static final byte FLAG_CSICERRP
        Catalog flag information - Catalog partially processed due to error.
        See Also:
        Constant Field Values

      • FLAG_CSIPMENT

        public static final byte FLAG_CSIPMENT
        Catalog Entry flag information - Primary entry.
        See Also:
        Constant Field Values

      • FLAG_CSIENTER

        public static final byte FLAG_CSIENTER
        Catalog Entry flag information - Error indication is set for this entry and error code follows CSIENAME.
        See Also:
        Constant Field Values

      • FLAG_CSIEDATA

        public static final byte FLAG_CSIEDATA
        Catalog Entry flag information - Data is returned for this entry.
        See Also:
        Constant Field Values

      • DEFAULT_WORK_AREA_LENGTH

        public static final int DEFAULT_WORK_AREA_LENGTH
        The default work area size for returned entry information.
        See Also:
        Constant Field Values

      • MIN_WORK_AREA_LENGTH

        public static final int MIN_WORK_AREA_LENGTH
        The minimum allowable work area size
        See Also:
        Constant Field Values

      • MAX_WORK_AREA_LENGTH

        public static final int MAX_WORK_AREA_LENGTH
        The maximum allowable work area size
        See Also:
        Constant Field Values

      • MAX_FIELD_NAMES

        public static final int MAX_FIELD_NAMES
        The maximum number of field names that may be specified on a search
        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

      • setFilterKey

        public void setFilterKey​(java.lang.String filterKey)
        Sets the filter key for the search.

        If performed on an active resumable search, the remainder of the current work area will be discarded.

        Throws:
        java.lang.IllegalStateException - if performed on an active search that cannot be resumed.
        Since:
        2.3.2
        See Also:
        isResume(), discardCurrentWorkArea()

      • getFilterKey

        public java.lang.String getFilterKey()
        Return the current filter key.
        Returns:
        the filter key
        Since:
        2.3.2

      • setCatalogName

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

        The default value is spaces (not set).

        If performed on an active resumable search, the remainder of the current work area will be discarded.

        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 performed on an active search that cannot be resumed.
        See Also:
        setSingleCatalog(boolean), isResume(), discardCurrentWorkArea()

      • getCatalogName

        public java.lang.String getCatalogName()
        Return the catalog name.
        Returns:
        the catalog name
        Since:
        2.3.2

      • setResumeName

        public void setResumeName​(java.lang.String resumeName)
        Set the resume name for an active, resumable search.

        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.

        Parameters:
        resumeName - the entry (Dataset) name to resume after
        Throws:
        java.lang.IllegalStateException - if the search is not active or performed on an active search that cannot be resumed.
        Since:
        2.3.2
        See Also:
        isResume(), discardCurrentWorkArea()

      • getResumeName

        public java.lang.String getResumeName()
        Return the resume name.
        Returns:
        the resume name.
        Throws:
        java.lang.IllegalStateException - if the search is not active or performed on an active search that cannot be resumed.
        Since:
        2.3.2

      • setEntryTypes

        public void setEntryTypes​(java.lang.String entryTypes)
        Set the entry types to be returned with the search.
        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. 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.

        Throws:
        java.lang.IllegalStateException - if performed on an active search that cannot be resumed.
        See Also:
        isResume(), discardCurrentWorkArea()

      • getEntryTypes

        public java.lang.String getEntryTypes()
        Return the entry types. A zero length string is returned if no entry types have been set.
        Returns:
        the entry types
        Since:
        2.3.2

      • setClusterNameMatch

        public void setClusterNameMatch​(boolean clusterNameMatch)
        Sets the cluster name match flag.

        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.

        Parameters:
        clusterNameMatch - true for data and index names to always be returned when the cluster name matches the filter key.
        Throws:
        java.lang.IllegalStateException - if performed on an active search that cannot be resumed.
        Since:
        2.3.2
        See Also:
        isResume(), discardCurrentWorkArea()

      • isClusterNameMatch

        public boolean isClusterNameMatch()
        Return true if the cluster name match flag is set
        Returns:
        the cluster name match flag
        Since:
        2.3.2

      • 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

      • isFullwordLengths

        public boolean isFullwordLengths()
        Return true if the variable field data lengths are fullwords (4 bytes). Return false if variable field data lengths are halfwords (2 bytes).
        Returns:
        the fullwordLengths flag
        Since:
        2.3.2

      • isResume

        public boolean isResume()
        Return the resume flag, set by catalog search when more search results exist than could fit in the supplied work area.
        Returns:
        the resume flag
        Throws:
        java.lang.IllegalStateException - if the search is not active
        Since:
        2.3.2

      • setSingleCatalog

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

        If performed on an active resumable search, the remainder of the current work area will be discarded.

        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 performed on an active search that cannot be resumed.
        See Also:
        isResume(), discardCurrentWorkArea(), setCatalogName(String)

      • isSingleCatalog

        public boolean isSingleCatalog()
        Return true if the single catalog flag is set. If true, only one catalog will be searched. If false (the default) multiple catalogs will be searched.
        Returns:
        the single catalog flag.
        Since:
        2.3.2

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

        If performed on an active resumable search, the remainder of the current work area will be discarded.

        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 performed on an active search that cannot be resumed.
        See Also:
        isResume(), discardCurrentWorkArea()

      • removeFieldName

        public void removeFieldName​(java.lang.String fieldName)
        Remove a field name that had previously been set.

        If performed on an active resumable search, the remainder of the current work area will be discarded.

        Parameters:
        fieldName - the field to remove from search results
        Throws:
        java.lang.IllegalStateException - if performed on an active search that cannot be resumed.
        Since:
        2.3.2
        See Also:
        isResume(), discardCurrentWorkArea()

      • getFieldNames

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

      • search

        public void search()
        Initiate the catalog search. Once this method is called, the Iterator interface methods 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)

        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.
        Returns:
        the return code
        Throws:
        java.lang.IllegalStateException - if the search is not active

      • getReason

        public int getReason()
        Return the reason area reason code. Will be zero unless an RcException has been thrown.
        Returns:
        the reason code
        Throws:
        java.lang.IllegalStateException - if the search is not active

      • getModuleId

        public java.lang.String getModuleId()
        Return the reason area module id. Will be zero length string unless an RcException has been thrown.
        Returns:
        the module id
        Throws:
        java.lang.IllegalStateException - if the search is not active

      • 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
        Returns:
        true if there is at least one more entry available from the search
        Throws:
        java.lang.IllegalStateException - if the search is not active

      • next

        public java.lang.Object next()
        Return the next Entry from the search.
        Specified by:
        next in interface java.util.Iterator
        Returns:
        the next entry
        Throws:
        java.lang.IllegalStateException - if the search is not active
        java.util.NoSuchElementException - if all entries have been returned
        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

      • workAreaHasNext

        public boolean workAreaHasNext()
        Indicates if the current work area has been completely processed.

        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.

        Returns:
        true if the current work area has been completely processed.
        Throws:
        java.lang.IllegalStateException - if the search is not active
        Since:
        2.3.2

      • discardCurrentWorkArea

        public void discardCurrentWorkArea()
        Discard the unprocessed work area data.

        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.

        Throws:
        java.lang.IllegalStateException - if the search is not active
        Since:
        2.3.2
        See Also:
        for information about processing all search results for a given catalog search.