ARSperl Manual - ars_MergeEntry

## `ars_MergeEntry(ctrl, schema, mergeType, ...)`

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.

There are three conditions to detect after ars_MergeEntry(...).

1. A non-null value returned means that a new entry was created.
2. A null value returned, plus $ars_errstr empty, means that an existing entry was replaced.
3. A null value returned, plus $ars_errstr non-empty, means there was some error.

Here's some sample code that demonstrates how to evaluate the outcome of this function:

    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 -> new $ret\n";
            } else {
                    arsdie("MergeEntry $RPTID $ret") if $ars_errstr;
                    print "$RPTID replaced\n";
            }
    }

Note the value "3075" for mergeType. That translates to

               2048: skip field pattern checking
               1024: allow NULL in required fields
             +    3: delete existing entry and create new in its place
             -------
               3075

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

Example:

    	# 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";
    	}

    	# note that "2" means "create a new entry"
    	$a = ars_MergeEntry($ctrl, "HD:HelpDesk", 2,
    		            2 , "FOOBAR");
    	if(($a ne "") && ($ars_errstr eq "")) {
    		print "entry successfully created - $a\n";
    	}
    	else {
    		print "failed to merge - $ars_errstr\n";
    	}

Notes

Note: If you try to merge a diary field (to alter existing diary entries) you need to pass the encoded diary to this routine. See ars_EncodeDiary.

`mergeType` defines how the merge will happen if special field (ie. Entry-Id) already exists:

Code | Meaning
--- | ---
1 | Generate an error
2 | Create a new entry with a new entry id
3 | Delete the existing entry and create a new on in its place
4 | Update fields specified in the fieldlist in existing entry
5 | Generate a new entry id for all entries
1024+num above | Allow NULL in required fields (not applicable for Submitter, Status or Short-Description)
2048+num above | Skip field pattern checking
4096+num above | Ignore filter processing

Refer to the Remedy Programmers Manual for further details.

The Object Oriented ARSperl layer tries to be a little easier to use.

ars_MergeEntry was introduced in version 1.46 of ARSperl

Table of Contents