eval results from the CPAN

ARSperl
<HTML>
<HEAD>
<TITLE>ARSperl Manual - ars_MergeEntry</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">

   <H2><CODE>ars_MergeEntry(ctrl, schema, mergeType, ...)</CODE></H2>

	Merge an entry into the schema. This routine allows you to
	arbitrarily alter fields (diary, entry-id, etc) that would
	otherwise be difficult or impossible to alter. All it requires
	is permissions to write to the particular field that you wish
	to alter. The ellipses represent alternating fieldId/fieldValue
	pairs.


<P>
There are three conditions to detect after ars_MergeEntry(...).  

<ol>
<li> A non-null value returned means that a new entry was created.

<li> A null value returned, plus $ars_errstr empty, means that an existing
   entry was replaced.

<li> A null value returned, plus $ars_errstr non-empty, means there was some
   error.
</oL>

Here's some sample code that demonstrates how to evaluate the outcome of
	this function:
<PRE>
foreach $RPTID (sort keys %RPTEntryList) {
        undef @Report;
        ( @Report = ars_GetEntry($ctrl1, $ISS_RPT_SCHEMA, $RPTID) )
                || arsdie("GetEntry $RPTID");
        if ( $ret = ars_MergeEntry($ctrl2, $ISS_RPT_SCHEMA,
                                   3075, @Report) ) {
                print "$RPTID -&gt; new $ret\n";
        } else {
                arsdie("MergeEntry $RPTID $ret") if $ars_errstr;
                print "$RPTID replaced\n";
        }
}
</PRE>

Note the value "3075" for mergeType.  That translates to<P>
<PRE>
           2048: skip field pattern checking
           1024: allow NULL in required fields
         +    3: delete existing entry and create new in its place
         -------
           3075
</PRE>
<P>

      <DL>
         <DT><B>On success</B><DD>
		If a NEW entry was created: returns the entry-id of the merged entry.<BR>
		If an EXISTING entry was over-written: returns "" and <code>$ars_errstr</code> will be "" (or, more correctly, <code>%ARS::ars_errhash</code> will not contain any FATAL or ERROR messages - but might contains WARNINGs or NOTICEs). <BR>
		Note that this is how the C API behaves - this isn't something
		that is unique to ARSperl. <BR>
                <a href="#example">See examples below.</a>
         <DT><B>On failure</B><DD>
                Returns "" (an empty string) and sets <code>$ars_errstr</code>
      </DL>

      <P><a name="example">Example:</a><P>

      <PRE>
	# note that "4" means "overwrite existing"
	$a = ars_MergeEntry($ctrl, "HD:HelpDesk", 4, 
		   1 , "00000000012345",
		   2 , "FOOBAR");
	if(($a eq "") && ($ars_errstr eq "")) {
		print "entry successfully over-written\n";
	} 
	else {
		print "failed to merge - $ars_errstr\n";
	}
      </PRE>

	<hr width="10%">

      <PRE>

	# note that "2" means "create a new entry"
	$a = ars_MergeEntry($ctrl, "HD:HelpDesk", 2, 
		            2 , "FOOBAR");
	if(($a ne "") && ($ars_errstr eq "")) {
( run in 0.852 second using v1.01-cache-2.11-cpan-ceb78f64989 )