# File lib/metacat.rb, line 199
  def read(docid, options = {}, &block) # :yields: xml or data_table fragment
    data = {
      'action'  =>  'read',
      'qformat' =>  'xml',
      'docid'   =>  docid
    }
    metacat_get(data) do |response|
      if response.content_type == 'text/xml'
        doc = REXML::Document.new(response.read_body)
        if(doc.root.name == 'error')
          if(doc.root.text.match('permission'))
            raise MetacatPermissionDenied, doc.root.text
          elsif(doc.root.text.match('does not exist'))
            # Nothing found, return nil
            return nil
          else
            raise 'Unrecognized response from metacat: '+doc.root.text
          end
        else # xml data
          return doc
        end
      else # probably a data table
        if (options.has_key?('only_eml') && options['only_eml'] == true)
          return nil
        else
          if block_given?
            response.read_body { |buffer| yield buffer }
          else
            response.read_body
          end
        end
      end      
    end
  end