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

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

Reference Type: Supported, Category: Name Standardization, ICR#: 3065

Description

The $$BLDNAME^XLFNAME 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 (#20) file, 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).

NOTE: For a description of the pruning algorithm, see the "Details" section that follows.

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.

Examples

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 returns 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 (#20) file stores the components of a name stored in the NAME (#.01) field of record number 32 in the NEW PERSON (#200) file, and the data in the corresponding record in the NAME COMPONENTS (#20) file 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,"

Then 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