[Arsperl-devel] ARSperl/html/manual ars_GetListEntry.html, 1.6, 1.7 ars_GetListEntryWithFields.html
Brought to you by:
jeffmurphy
Menu
▾
▴
[Arsperl-devel] ARSperl/html/manual ars_GetListEntry.html, 1.6, 1.7 ars_GetListEntryWithFields.html, 1.3, 1.4
|
From: Michiel B. <mb...@us...> - 2009-04-14 12:29:31
|
Update of /cvsroot/arsperl/ARSperl/html/manual In directory 23jxhf1.ch3.sourceforge.com:/tmp/cvs-serv17155 Modified Files: ars_GetListEntry.html ars_GetListEntryWithFields.html Log Message: Updated documentation Index: ars_GetListEntry.html =================================================================== RCS file: /cvsroot/arsperl/ARSperl/html/manual/ars_GetListEntry.html,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -d -r1.6 -r1.7 *** ars_GetListEntry.html 16 Apr 2003 00:59:06 -0000 1.6 --- ars_GetListEntry.html 14 Apr 2009 12:29:28 -0000 1.7 *************** *** 1,93 **** ! <HTML> ! <HEAD> ! <TITLE>ARSperl Manual - ars_GetListEntry</TITLE> ! </HEAD> ! <BODY BGCOLOR="#FFFFFF"> ! ! <H2><CODE>ars_GetListEntry(ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0,...)</CODE></H2> ! ! This function is used to retrieve the list of <CODE>entry_id</CODE>s ! and description (query list) strings from the specified schema. The entries ! are returned as an array of <I>(entry_id, query-list)</I> pairs. ! If you wish to retrieve all entries in the schema (upto the maximum ! allowed by the server or specified by you as the <CODE>maxRetrieve</CODE> ! parameter) you should load a Qualifier with something like ! <CODE>(1 = 1)</CODE>. ! <P> ! <DL> ! <DT><B>ARS3.x</B> ! <DD> ! In 3.x, the "..." in the above function can be one of two things: ! <OL> ! <LI> A Hash Reference that specifies what you want the ! query list to look like, followed by (optionally) a list ! of field ids and sorting types to indicate how you want the ! query list sorted. ! <LI> An optional list of field ids and sorting types to indicate ! how you want the schema's default query list to be sorted. ! </OL> ! <p> ! <DT><B>ARS2.x</B> ! <DD> ! In 2.x, the "..." in the above function indicates ! an optional list of field ids and sorting type. ! </DL> ! ! The sorting type can be ! 1 for ascending, or 2 for descending. Also, note that if you want to ! retain the order of the entry ids returned, then you must assign the ! list to an array, and not a hash. <P> ! ! Setting <CODE>maxRetrieve = 0</CODE> will return as many matches as ! the server will allow. This is the default. ! <P> ! <code>firstRetrieve</code> (only available when compiled against the ! 5.x API) specifies which entry to start with. The default (zero) is to ! start with the first entry that matches the qualifier. ! <P> ! ! ! <DL> ! <DT><B>On success</B> ! <DD> ! Returns a list of <I>(entry_id, short-description)</I> pairs. ! <DT><B>On failure</B> ! <DD> ! Returns <CODE>undef</CODE>. ! </DL> ! <P> ! <i>Note: prior to ARSperl 1.50 <code>ars_GetListEntry</code> returned a ! <tt>-1</tt> on a call where the query matched more than the maxRetrieve ! number of items from the database. ! </i> ! ! <P>Example: ! ! <PRE> ! %entries = ars_GetListEntry($c, "User", $q, 100); foreach $entry_id (sort keys %entries) { ! print "EntryID: $entry_id Short-Descrip: $entries{$entry_id}\n"; } ! </PRE> ! ! <P> ! Example (2.x or 3.x) of how to set sorting options: ! ! <PRE> # returns entries for User schema sorted by login name ! $all = ars_LoadQualifier($c,"User","1=1"); $login_name = ars_GetFieldByName($c,"User","Login Name"); @Entries = ars_GetListEntry($c, "User", $all, 0, 0, $login_name, 1); ! for ( $i = 0; $i <= $#Entries; $i +=2 ) { ! $entry_num = $Entries[$i]; ! $description_fields = $Entries[$i+1]; ! } ! </PRE> ! ! <P>Example (3.x only) of how to specify your own query list and sorting options: ! ! <PRE> %f = ars_GetFieldTable($ctrl, "User"); # retrieve list of matching records. query list should only --- 1,107 ---- ! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> ! <html xmlns="http://www.w3.org/1999/xhtml"> ! <head> ! <title> ! ARSperl Manual - ars_GetListEntry ! </title> ! <style type="text/css"> ! /*<![CDATA[*/ ! body { ! background-color: #FFFFFF; ! } ! p.c2 {font-style: italic} ! dt.c1 {font-weight: bold} ! /*]]>*/ ! </style> ! </head> ! <body> ! <h2> ! <code>ars_GetListEntry(ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0,...)</code> ! </h2>This function is used to retrieve the list of <code>entry_id</code>s and results list ! strings from the specified schema. The entries are returned as an array of <i>(entry_id, ! resultslist)</i> pairs. If you wish to retrieve all entries in the schema (upto the maximum ! allowed by the server or specified by you as the <code>maxRetrieve</code> parameter) you should ! load a qualifier with something like <code>(1 = 1)</code>. ! <p> ! See also the <a href="ars_GetListEntryWithFields.html">ars_GetListEntryWithFields</a> which ! is similar to GetListEntry but returns selected fields as separate values and not as ! formatted strings. ! </p> ! <p> ! The "..." in the above function can be one of two things: ! </p> ! <ol> ! <li>A Hash Reference that specifies what you want the query list to look like, followed by ! (optionally) a list of field ids and sorting types to indicate how you want the query list ! sorted. ! </li> ! <li>An optional list of field ids and sorting types to indicate how you want the schemas ! default results list to be sorted. If you do not specify the fields you want to have ! returned, the function returns the fields defined as the results list for this schema, which ! can be changed on the server side. ! </li> ! </ol> ! <p></p> ! <p> ! The sorting type can be 1 for ascending, or 2 for descending. Also, note that if you want to ! retain the order of the entry ids returned, then you must assign the list to an array, and ! not a hash. ! </p> ! <p> ! Setting <code>maxRetrieve = 0</code> will return as many matches as the server will allow. ! This is the default. ! </p> ! <p> ! <code>firstRetrieve</code> specifies which entry to start with. The default (zero) is to ! start with the first entry that matches the qualifier. ! </p> ! <p></p> ! <dl> ! <dt class="c1"> ! On success ! </dt> ! <dd> ! Returns a list of <i>(entry_id, resultslist)</i> pairs. ! </dd> ! <dt class="c1"> ! On failure ! </dt> ! <dd> ! Returns <code>undef</code>. ! </dd> ! </dl> ! <h2> ! Examples: ! </h2> ! <h3> ! Simple usage: ! </h3> ! <pre> ! %entries = ars_GetListEntry($c, "User", $q, 100, 0); foreach $entry_id (sort keys %entries) { ! print "EntryID: $entry_id ResultsList: $entries{$entry_id}\n"; } ! </pre> ! <h3> ! Example of how to set sorting options: ! </h3> ! <pre> # returns entries for User schema sorted by login name ! $all = ars_LoadQualifier($c,"User","1=1"); $login_name = ars_GetFieldByName($c,"User","Login Name"); @Entries = ars_GetListEntry($c, "User", $all, 0, 0, $login_name, 1); ! ! for ( $i = 0; $i <= $#Entries; $i +=2 ) { $entry_num = $Entries[$i]; ! $resultslist_fields = $Entries[$i+1]; ! print "$entry_num\t$resultslist_fields\n"; } ! ! </pre> ! <h3> ! Example of how to specify your own query list and sorting options: ! </h3> ! <pre> %f = ars_GetFieldTable($ctrl, "User"); # retrieve list of matching records. query list should only *************** *** 97,118 **** # getListFields [ ! {columnWidth=>5, separator=>' ', fieldId=>$f{'Login name'} }, {columnWidth=>5, separator=>' ', fieldId=>$f{'Full Name'} } ], # sort Order ! $f{'Login name'}, 1); ! </PRE> ! <P> ! <hr width="30%"> ! <p> ! ! <A HREF="toc.html"><IMG ALT="<--" SRC="arrow.gif" ALIGN=CENTER> Table of Contents </A> ! ! <p> ! ! <address> ! Last changes to this page 15 Apr 2003 by jcmurphy<P> ! © J.C.Murphy, J.W.Murphy 1998 ar...@ar... ! </address> ! </BODY> ! </HTML> --- 111,131 ---- # getListFields [ ! {columnWidth=>5, separator=>' ', fieldId=>$f{'Login Name'} }, {columnWidth=>5, separator=>' ', fieldId=>$f{'Full Name'} } ], # sort Order ! $f{'Login Name'}, 1); ! ! </pre> ! <p> ! <a href="toc.html">Back to Table of Contents</a> ! </p> ! <p></p> ! <address> ! Last changes to this page 14 Apr 2009 by mic...@gm... ! <p> ! © J.C.Murphy, J.W.Murphy 1998 ar...@ar... ! </p> ! </address> ! </body> ! </html> Index: ars_GetListEntryWithFields.html =================================================================== RCS file: /cvsroot/arsperl/ARSperl/html/manual/ars_GetListEntryWithFields.html,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** ars_GetListEntryWithFields.html 16 Apr 2003 19:07:39 -0000 1.3 --- ars_GetListEntryWithFields.html 14 Apr 2009 12:29:28 -0000 1.4 *************** *** 1,97 **** ! <HTML> ! <HEAD> ! <TITLE>ARSperl Manual - ars_GetListEntryWithFields</TITLE> ! </HEAD> ! <BODY BGCOLOR="#FFFFFF"> ! ! <PRE> ! <H2><CODE>ars_GetListEntryWithFields( ! ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0, # standard ! [ fieldID_list ], # OPTIONAL ! sortID1,sortdir1,sortID2,sortdir2,...) # OPTIONAL</CODE></H2> ! </PRE> ! ! This function is used to query a specified schema and return actual ! field values - not formatted strings as per <CODE>ars_GetListEntry</CODE> - from ! all matching entries.<p> ! ! <CODE>[ fieldID_list ]</CODE> is an optional array reference; the list is ! a list of FieldIDs. Because only the actual fieldIDs need to be passed, ! this is a list of scalar values, not a list of hash references a la ! <CODE>ars_GetListEntry</CODE>. If not specified, the default result list ! fields for the schema are returned.<p> ! ! The other arguments are identical in function to <CODE><a href="ars_GetListEntry.html">ars_GetListEntry</a></CODE>. ! <p> ! ! The format of the returned list/hash is <I>(entry_id, {field_value_hash})</I> ! pairs. The returned list can be stored in an array or hash. Using an array ! preserves the sort order, if one was specified. Each referenced ! field_value_hash looks like the return of a single <CODE>ars_GetEntry</CODE> ! call: the hash keys are the fieldIDs and the hash values are the field values. ! <P> ! ! <DL> ! <DT><B>On success</B> ! <DD> ! Returns a list of <I>(entry_id, {field_value_hash})</I> pairs. ! <DT><B>On failure</B> ! <DD> ! Returns <CODE>undef</CODE>. ! </DL> ! <P> ! ! <P>Example: ! ! <PRE> ! # ! # Read Status and History of all open entries ! # return most recent entries first ! # ! ! $qs = qq/'Status' = "Open"/; ! ( $lq = ars_LoadQualifier( $ctrl, $schema, $qs ) ) ! || die( "LoadQualifier Failed: $ars_errstr" ); ! ! ( @Entries = ars_GetListEntryWithFields( ! $ctrl, $schema, $lq, 0, ! [ FieldID("Status"), FieldID("History") ], ! FieldID("EntryID"), 2 ! ) ) ! || die( "GLEWF Failed: $ars_errstr" ); ! </PRE> ! Returned list, sorted in descending order by EntryID: ! ! <PRE> ! @Entries = ( "0000000139", { 7 => 1, ! 10 => { decoded_history_hash } }, ! "0000000047", { 7 => 1, ! 10 => { another_diary } } ! ) ! </PRE> ! ! <P> ! <b>Notes:</b> This is a high-performance command that returns a lot of data with one ! API call. Care should be taken to delete the returned data structure ! (e.g., with "<CODE>undef %Entries</CODE>") when it is no longer needed, ! to avoid memory problems.<p> ! ! <CODE>ars_GetListEntryWithFields</CODE> can only be used with API version 4.0 ! or later.<p> ! ! See Also: <a HREF="ars_GetListEntry.html">ars_GetListEntry</a>, <a HREF="ars_GetMultipleEntries.html">ars_GetMultipleEntries</a> ! ! ! <hr width="30%"> ! <p> ! ! <A HREF="toc.html"><IMG ALT="<--" SRC="arrow.gif" ALIGN=CENTER> Table of Contents </A> ! ! <p> ! <address> ! Last changes to this page 3 October 2002 by G. David Frye<P> ! © J.C.Murphy, J.W.Murphy 1998 ar...@ar... ! </address> ! </BODY> ! </HTML> --- 1,109 ---- ! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> ! <html xmlns="http://www.w3.org/1999/xhtml"> ! <head> ! <title> ! ARSperl Manual - ars_GetListEntryWithFields ! </title> ! <style type="text/css"> ! /*<![CDATA[*/ ! body { ! background-color: #FFFFFF; ! } ! dt.c1 {font-weight: bold} ! /*]]>*/ ! </style> ! </head> ! <body> ! <h2> ! <code>ars_GetListEntryWithFields( ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0, # ! standard [ fieldID_list ], # OPTIONAL sortID1,sortdir1,sortID2,sortdir2,...) # ! OPTIONAL</code> ! </h2> ! <pre> ! </pre>This function is used to query a specified schema and return actual field values - not ! formatted strings as per <code>ars_GetListEntry</code> - from all matching entries. ! <p> ! <code>[ fieldID_list ]</code> is an optional array reference; the list is a list of FieldIDs. ! Because only the actual fieldIDs need to be passed, this is a list of scalar values, not a ! list of hash references a la <code>ars_GetListEntry</code>. If not specified, the default ! result list fields for the schema are returned. ! </p> ! <p> ! The other arguments are identical in function to <code><a href= ! "ars_GetListEntry.html">ars_GetListEntry</a></code>. ! </p> ! <p> ! The format of the returned list/hash is <i>(entry_id, {field_value_hash})</i> pairs. The ! returned list can be stored in an array or hash. Using an array preserves the sort order, if ! one was specified. Each referenced field_value_hash looks like the return of a single ! <code>ars_GetEntry</code> call: the hash keys are the fieldIDs and the hash values are the ! field values. ! </p> ! <p></p> ! <dl> ! <dt class="c1"> ! On success ! </dt> ! <dd> ! Returns a list of <i>(entry_id, {field_value_hash})</i> pairs. ! </dd> ! <dt class="c1"> ! On failure ! </dt> ! <dd> ! Returns <code>undef</code>. ! </dd> ! </dl> ! <p></p> ! <p> ! Example: ! </p> ! <pre> ! # Read all Completed entries from Sample:Enrollments ! # fetch Class Title, Location and Enrollee Login ! ! my $schema = "Sample:Enrollments"; ! my $querystring = qq/'7' = "Completed"/; ! ( my $lq = ars_LoadQualifier( $ctrl, $schema, $qs ) ) ! || die("LoadQualifier Failed: $ars_errstr"); ! ! my %fieldname_to_id = ars_GetFieldTable( $ctrl, $schema ); ! my $class_title = $fieldname_to_id{'Class Title'}; ! my $class_location = $fieldname_to_id{'Class Location'}; ! my $enrollee_login = $fieldname_to_id{'Enrollee Login'}; ! ! ( ! my %entries = ars_GetListEntryWithFields( ! $ctrl, $schema, $lq, 0, 0, ! [ $class_title, $class_location, $enrollee_login ], ! ) ! ) || die("GLEWF Failed: $ars_errstr"); ! ! foreach my $entry_id (keys %entries) { ! print ! "$entry_id\t $entries{$entry_id}{$class_title}\t $entries{$entry_id}{$class_location}\t $entries{$entry_id}{$enrollee_login}\n"; ! } ! </pre> ! <p> ! <b>Notes:</b> This is a high-performance command that returns a lot of data with one API ! call. Care should be taken to delete the returned data structure (e.g., with "<code>undef ! %entries</code>") when it is no longer needed, to avoid memory problems. ! </p> ! <p> ! See Also: <a href="ars_GetListEntry.html">ars_GetListEntry</a>, <a href= ! "ars_GetMultipleEntries.html">ars_GetMultipleEntries</a> ! </p> ! <p> ! <a href="toc.html">Back to Table of Contents</a> ! </p> ! <p></p> ! <address> ! Last changes to this page 14 April 2009 by mic...@gm... ! <p> ! © J.C.Murphy, J.W.Murphy 1998 ar...@ar... ! </p> ! </address> ! </body> ! </html> |
