Kernel 8.0 APIs Banner [skip navigation]
Office of Information & Technology (OIT) Banner

$$BLDNAME^XLFNAME(): Build Name from Component Parts

Reference Type: Supported, Category: Name Standardization, Integration Agreement: 3065

Description

This extrinsic function takes the component parts of a name and returns the name, truncated if necessary, in the following format:

Family_name,Given_name<space>Middle_name<space>Suffix(es)

Format

  $$BLDNAME^XLFNAME(.name[,max])

Input Parameters

.name:

(required) The component parts of the name:

NAME("FAMILY") = Family (Last) Name
NAME("GIVEN") = Given (First) Name(s)
NAME("MIDDLE") = Middle Name(s)
NAME("SUFFIX") = Suffix(es)

Alternatively, this array can contain the file number, IENS, and field number of the field that contains the name. If the name has a corresponding entry in the NAME COMPONENTS file (#20), then the name components are obtained from that entry. Otherwise, the name is obtained directly from the file, record, and field specified, and the name components are obtained by making a call to the STDNAME^XLFNAME API.

NAME("FILE") = Source file number (required)
NAME("IENS") = IENS of entry in the source file (required)
NAME("FIELD") = Source field number (required)
max:

(optional) The maximum length of the Name to be returned (default = 256). See the following section named "Details" for a description of the pruning algorithm.

Output

returns:

Returns the name, truncated if necessary, in the following format:

  Family_name,Given_name<space>Middle_name<space>
				Suffix(es)

Details

If the MAX input parameter is used, and the resulting name is longer than MAX, the following pruning algorithm is performed to shorten the name:

  1. Truncate Middle Name from the right-most position until only the initial character is left;

  2. Drop suffix;

  3. Truncate Given Name from the right-most position until only the initial character is left;

  4. Truncate Family Name from the right-most position;

  5. Truncate the name from the right.

Example 1

Suppose the MYNAME array contains the following elements:

MYNAME("FAMILY")="KRNUSER"
MYNAME("GIVEN")="SIXTY"
MYNAME("MIDDLE")="K."
MYNAME("SUFFIX")="JR"

Calls to $$BLDNAME^XLFNAME will return the name as follows:

>S X=$$BLDNAME^XLFNAME(.MYNAME)

>W X
KRNUSER,SIXTY K JR

"Pruning" the name to 12 characters total:

>S X =$$BLDNAME^XLFNAME(.MYNAME,12)

>W X
KRNUSER,SI K

Example 2

If an entry in the NAME COMPONENTS file (#20) stores the components of a name stored in the NAME field (#.01) of record number 32 in the NEW PERSON file (#200), and the data in the corresponding record in the NAME COMPONENT file (#20) is:

FILE=200
FIELD=.01
IENS="32,"
GIVEN NAME="SIXTY"
MIDDLE NAME="K."
FAMILY NAME="KRNUSER"
SUFFIX="JR"

you can set:

MYNAME("FILE")=200
MYNAME("FIELD")=.01
MYNAME("IENS")="32,"

and call $$BLDNAME^XLFNAME as in Example 1:

>S X=$$BLDNAME^XLFNAME(.MYNAME)

>W X
KRNUSER,SIXTY K JR

"Pruning" the name to 12 characters total:

>S X=$$BLDNAME^XLFNAME(.MYNAME,12)

>W X
KRNUSER,SI K

 


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: August 26, 2011

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.