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.
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:

CodeMeaning
1Generate an error
2Create a new entry with the new entry id
3Delete the existing entry and create a new on in its place
4Update fields specified in the fieldlist in existing entry
1024+num aboveAllow NULL in required fields (not applicable for Submitter, Status or Short-Description)
2048+num aboveSkip field pattern checking

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

Last changes to this page 24-Oct-2001 by jcmurphy@smurfland.cit.buffalo.edu
© J.C.Murphy, J.W.Murphy 1997 arsperl@smurfland.cit.buffalo.edu