Kernel APIs: UPDCOMP^XLFNAME2

UPDCOMP^XLFNAME2(): Update Name Components Entry

Reference Type: Controlled Subscription, Category: Name Standardization, ICR#: 3066

Description

The UPDCOMP^XLFNAME2 API updates an entry in the NAME COMPONENTS (#20) file. Optionally, the pointer in the source file that points to the name components entry is also updated.

This API is designed to be used in the SET logic of a MUMPS cross-reference on the NAME field in a source file, to keep the NAME field and the associated name components in sync. For an example of its use, see the ANAME index in the INDEX (#.11) file. The ANAME index is a MUMPS cross-reference on the NAME (#.01) field of the NEW PERSON (#200) file. If an entry's NAME field is edited, the ANAME cross-reference updates the associated entry in the NAME COMPONENTS (#20) file.

NOTE: Existing MUMPS cross-references on the NAME COMPONENTS (#20) file already exist to update the associated NAME field on the source file if the components are edited.

Format

  UPDCOMP^XLFNAME2(file,[.]record,field,[.]name[,ptrfield][,ptrval])

Input Parameters

file:	(required) The number of the file or Multiple (the "source file") that contains the name.
[.]record:	(required) The IENS or the Internal Entry Number array (that looks like the DA array) of the record in the source file that contains the name.
field:	(required) The number of the field in the source file that contains the name.
[.]name:	(required) An array that contains the component parts of the name to store in the NAME COMPONENTS (#20) file entry: NAME("FAMILY) = Family Name (required) NAME("GIVEN") = Given Name(s)(optional) NAME("MIDDLE") = Middle Name(s)(optional) NAME("SUFFIX") = Suffix(es) (optional) NAME("PREFIX") = Prefix (optional) NAME("NOTES") = optional free text string Alternatively, a name in standard format can be passed in the name input parameter. If the name input parameter has no descendents [i.e., $D(NAME)=1], UPDCOMP^XLFNAME2 makes a call to the NAMECOMP^XLFNAME(): Component Parts from Standard Name API to build the NAME array for you.
ptrfield:	(optional) The number of the POINTER field in the source file that points to the NAME COMPONENTS (#20) file. Only if this parameter is passed is the value of this POINTER field be updated with the entry number of the record in the NAME COMPONENTS (#20) file that was added or edited.
ptrval:	(optional) The current value of the POINTER field specified by the ptrfield input parameter. This parameter can be used to save processing time. If both ptrfield and ptrval are passed, the POINTER field is updated only if this value is different from the entry number of the record in the NAME COMPONENTS (#20) file that was added or edited.

Output

returns:

Updated entry in the NAME COMPONENTS (#20) file.

Example

Suppose the .01 field of File #1000 contains a person's name, and the component parts of the name in entry 132 should be updated as follows:

Family (last) name: KRNUSER
Given (first) name: FIFTY HENRY
Middle name: A.
Suffix: JR.

Field #1.1 is defined as a pointer to the NAME COMPONENTS (#20) file and has a value of 42, the IEN of a record in the NAME COMPONENTS (#20) file. To update the NAME COMPONENTS (#20) file with this name, you can do the following:

>S MYNAME("FAMILY")="KRNUSER"
>S MYNAME("GIVEN")="FIFTY HENRY"
>S MYNAME("MIDDLE")="A."
>S MYNAME("SUFFIX")="JR."

>D UPDCOMP^XLFNAME2(1000,132,.01,.MYNAME,1.1,42)

If there is an entry in the NAME COMPONENTS (#20) file that corresponds to File #1000, Field #.01, IEN #132, that entry is updated with the name components passed in the MYNAME array. Otherwise, a new entry is added to the name components with this information.

If the entry in the name components that was updated or added is record #42, no change is made to the value of the POINTER field #1.1, since 42 was passed in the 6th parameter.

MUMPS cross-references on the NAME COMPONENTS (#20) file updates the name in the Field #.01 of File #1000 to "KRNUSER,FIFTY HENRY A JR" if it does not already contain that name.