Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Bio::DB::SoapEUtilitieUsereContributed Perl Bio::DB::SoapEUtilities::Result(3)

       Bio::DB::SoapEUtilities::Result - Accessor object for SoapEUtilities

	$fac = Bio::DB::SoapEUtilities->new();
	$result	= $fac->esearch( -db =>	'gene',	-term => 'hedgehog')->run;
	$count = $result->count; # case	important; $result->Count could	be arrayref
	@ids = $result->ids;

       This module attempts to make Entrez Utilities SOAP responses as user-
       friendly	and intuitive as possible. These responses can be complex
       structures with much useful data; but users will	generally desire the
       values of some key fields. The Result object provides access to all
       response	values via systematically named	accessor methods, and commonly
       used values as convenience methods. The 'raw' SOAP message (a SOAP::SOM
       object as returned by SOAP::Lite) is also provided.

       Convenience accessors
	   If a	list of	record ids is returned by the call, "ids()" will
	   return these	as an array reference:

	    @seq_ids = $result->ids;

	   The total count of returned records is provided by "count()":

	    $num_recs =	$result->count;

	   If "usehistory" was specified in the	SOAP call, the NCBI-assigned
	   web environment (that can be	used in	future calls) is available in
	   "webenv", and the query key assigned	to the result in "query_key":

	    $next_result = $fac->efetch( -WebEnv => $result->webenv,
					 -QueryKey => $result->query_key );

       Walking the response
	   This	module uses "AUTOLOAD" to provide accessor methods for all
	   response data.  Here	is an example of a SOAP	response as returned
	   by a	"method()" call	off the	SOAP::SOM object:

	       DB<5> x $result->som->method
	    0  HASH(0x2eac9a4)
	       'Count' => 148
	       'IdList'	=> HASH(0x4139578)
		 'Id' => 100136227
	       'QueryKey' => 1
	       'QueryTranslation' => 'sonic[All	Fields]	AND hedgehog[All Fields]'
	       'RetMax'	=> 20
	       'RetStart' => 0
	       'TranslationSet'	=> ''
	       'TranslationStack' => HASH(0x4237b4c)
		  'OP' => 'GROUP'
		  'TermSet' => HASH(0x42c43bc)
		     'Count' =>	2157
		     'Explode' => 'Y'
		     'Field' =>	'All Fields'
		     'Term' => 'hedgehog[All Fields]'
	       'WebEnv'	=> 'NCID_1_150423569_130.14.22.101_9001_1262703782'

	   Some	of the data values here	(at the	tips of	the data structure)
	   are actually	arrays of values ( e.g., the tip "IdList =" Id>	),
	   other tips are simple scalars. With this in mind, "Result" accessor
	   methods work	as follows:

	   Data	values (at the tips of the response structure) are acquired by
	   calling a method with the structure keys separated by underscores
	   (if necessary):

	    $query_key = $result->QueryKey; # $query_key == 1
	    $ids = $result->IdList_Id;	    # @$ids is an array	of record ids

	   Data	sets below a particular	node in	the response structure can
	   also	be obtained with similarly constructed method names. These
	   'internal node accessors' return a hashref, containing all data
	   leaves below	the node, keyed	by the accessor	names:

	       $data_hash = $result->TranslationStack

	       DB<3> x $data_hash
	    0  HASH(0x43569d4)
	       'TranslationStack_OP' =>	ARRAY(0x42d9988)
		  0  'AND'
		  1  'GROUP'
	       'TranslationStack_TermSet_Count'	=> ARRAY(0x4369c64)
		  0  148
		  1  148
		  2  2157
	       'TranslationStack_TermSet_Explode' => ARRAY(0x4368998)
		  0  'Y'
		  1  'Y'
	       'TranslationStack_TermSet_Field'	=> ARRAY(0x4368260)
		  0  'All Fields'
		  1  'All Fields'
	       'TranslationStack_TermSet_Term' => ARRAY(0x436c97c)
		  0  'sonic[All	Fields]'
		  1  'hedgehog[All Fields]'

	   Similarly, the call " $result-"TranslationStack_TermSet > would
	   return a similar hash containing the	last 4 elements	of the example
	   hash	above.

	   Creating accessors is somewhat costly, especially for fetch
	   responses which can be deep and complex (not	unlike BioPerl
	   developers).	Portions of the	response tree can be ignored by
	   setting "-prune_at_node" to a arrayref of nodes to skip. Nodes
	   should be specified in SOAP::SOM format, e.g.

	    ...::Result->new( -prune_at_nodes => ['//GBSeq_references']	);

	   Accessor creation can be skipped altogether by passing "-no_parse
	   =" 1> to the	"Result" constructor. This is recommended if a result
	   is being passed to a	Bio::DB::SoapEUtilities::FetchAdaptor. The
	   original SOAP message with all data is always available in

	   Other methods


	   An array of available data accessor names. This contains only the
	   data	"tips".	The internal node accessors are	autoloaded.


	   True	if no SOAP fault.


	   Returns the SOAP fault error	string.


	   The original	"SOAP::SOM" message.


	   The EUtility	associated with	the result.

   Mailing Lists
       User feedback is	an integral part of the	evolution of this and other
       Bioperl modules.	Send your comments and suggestions preferably to the
       Bioperl mailing list.  Your participation is much appreciated.			- General discussion  -	About the mailing lists

       Please direct usage questions or	support	issues to the mailing list:

       rather than to the module maintainer directly. Many experienced and
       reponsive experts will be able look at the problem and quickly address
       it. Please include a thorough description of the	problem	with code and
       data examples if	at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of
       the bugs	and their resolution. Bug reports can be submitted via the

AUTHOR - Mark A. Jensen
       Email maj -at- fortinbras -dot- us

       The rest	of the documentation details each of the object	methods.
       Internal	methods	are usually preceded with a _

	Title	: parse_methods
	Usage	:
	Function: parse	out the	accessor methods
	Returns	: self (Result object)
	Args	: $alias_hash (hashref), $prune_at_nodes (scalar or arrayref)

	Title	: util
	Usage	:
	Function: Name of the utility producing	this result object.
	Returns	: scalar string
	Args	:

	Title	: som
	Usage	:
	Function: get the original SOAP::SOM object
	Returns	: a SOAP::SOM object
	Args	: none

	Title	: ok
	Usage	:
	Returns	: true if no SOAP fault
	Args	:

	Title	: errstr
	Usage	:
	Returns	: fault	string of SOAP object
	Args	: none

	Title	: accessors
	Usage	:
	Function: get the list of created accessors for	this
	Returns	: array	of scalar strings
	Args	: none
	Note	: does not include valid AUTOLOADed accessors; see

	Title	: webenv
	Usage	:
	Function: contains WebEnv key referencing this
		  result's session
	Returns	: scalar
	Args	: none

	Title	: query_key()
	Usage	:
	Function: contains the web query key assigned
		  to this result
	Returns	: scalar
	Args	:

	Title	: fetch_type
	Usage	:
	Function: Get the efetch database name according to WSDL
	Returns	: scalar string	(db name) or undef if N/A
	Args	: none

       Hey! The	above document had some	coding errors, which are explained

       Around line 137:
	   You can't have =items (as at	line 141) unless the first thing after
	   the =over is	an =item

perl v5.32.1			  2021-03-01Bio::DB::SoapEUtilities::Result(3)


Want to link to this manual page? Use this URL:

home | help