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

$$NAMEFMT^XLFNAME(): Formatted Name from Name Components

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

Description

The $$NAMEFMT^XLFNAME extrinsic function returns a name converted to a form useful for display.

Format

  $$NAMEFMT^XLFNAME(.name[,format][,flags])

Input Parameters

.name:

(required) An array that contains the component parts of the name:

NAME("FAMILY) = Family (Last) Name (required)
NAME("GIVEN") = Given (First) Name(s) (optional)
NAME("MIDDLE") = Middle Name(s) (optional)
NAME("SUFFIX") = Suffix(es) (optional)
NAME("PREFIX") = Prefix (optional)
NAME("DEGREE") = Degree (optional)

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, then the name components are obtained from that entry. Otherwise, the name is obtained directly from the file, record, and field specified, and (#20)the name components are obtained by making a call to the STDNAME^XLFNAME(): Name Standardization Routine API.

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

(optional) Controls the general formatting of the output (Default = G). Possible values are:

  • F—Return Family (Last) Name first.

  • G—Return Given (First) Name first.

  • O—Return Only the Family (Last) Name.
flags:

(optional) Flags to controls processing. Possible values are:

  • C—If the F format is used, return a Comma between the Family (Last) and Given (First) Names. Otherwise, the Family (Last) Name and the Given (First) Name are separated by a space. (Ignored if the F format is not used.)

  • D—Return the Degree.

  • Dc—Return the Degree preceded by a comma and space.

  • L#—Truncate the returned name to a maximum Length of # characters, where # is an integer between 1 and 256. See "Details" as follows for a description of the pruning algorithm.

  • M—Return the name in Mixed case, with the first letter of each name component capitalized.

  • P—Return the Prefix.

  • S—Standardize the name components before building formatted name.

  • Xc—Precede the SuffiX with a comma and space.

Output

returns:

Returns the formatted name.

Details

If the L# flag is used, and the resulting name is longer than #, the following pruning algorithm is performed to shorten the name:

  1. Drop Degree.

  2. Drop Prefix.

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

  4. Drop suffix.

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

  6. Truncate Family Name from the right-most position.

  7. Truncate the name from the right.

Examples

Example 1

Suppose the MYNAME array contains the following elements:

MYNAME("PREFIX") = "MR."
MYNAME("GIVEN") = "SIXTY" 
MYNAME("MIDDLE") = "K." 
MYNAME("FAMILY") = "XUUSER" 
MYNAME("SUFFIX") = "JR"
MYNAME("DEGREE") = "PHD"

Then calls to the $$NAMEFMT^XLFNAME API returns the name as follows:

>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F")

>W X
XUUSER SIXTY K. JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","C")

>W X
XUUSER,SIXTY K. JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","CS")

>W X
XUUSER,SIXTY K JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","CSD")

>W X
XUUSER,SIXTY K JR PHD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","CDcXc")

>W X
XUUSER,SIXTY K., JR, PHD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","CSL12")

>W X
XUUSER,SI K
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"F","CMD")

>W X
Krnuser,Sixty K. Jr PhD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G")

>W X
SIXTY K. XUUSER JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","D")

>W X
SIXTY K. XUUSER JR PHD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","Dc")

>W X
SIXTY K. XUUSER JR, PHD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","P")

>W X
MR. SIXTY K. XUUSER JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","Xc")

>W X
SIXTY K. XUUSER, JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","PDcXc")

>W X
MR. SIXTY K. XUUSER, JR, PHD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","PDcXcM")

>W X
Mr. Sixty K. Krnuser, Jr, PhD
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","S")

>W X
SIXTY K XUUSER JR
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"G","SL12")

>W X
SI K XUUSER
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"O")

>W X
XUUSER
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"O","S")

>W X
XUUSER
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"O","M")

>W X
Xuuser
>S X=$$NAMEFMT^XLFNAME(.MYNAME,"O","L3")

>W X
XU

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,"
PREFIX = "MR."
GIVEN NAME = "SIXTY"
MIDDLE NAME = "K."
FAMILY NAME = "XUUSER"
SUFFIX = "JR"
DEGREE = "PHD"

You can set:

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

Then call the $$NAMEFMT^XLFNAME API, as in Example 1, to return the name in various formats.