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

STDNAME^XLFNAME(): Name Standardization Routine

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

Description

The STDNAME^XLFNAME API parses a name and converts it into the following standard format:

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

A name in standard format is entirely in uppercase, and contains no Arabic numerals. The Family_name (last name) portion of a standard name appears to the left of the comma and contains no spaces and no punctuation except hyphens (-). The other parts of a standard name (the portion to the right of the comma) contain no punctuation except for hyphens and spaces. NMI and NMN are not used for the Middle_name.

STDNAME^XLFNAME optionally returns in an array the component parts of the name. It also optionally returns information in an array about possible problems encountered during the conversion of the name to standard form and the parsing of the name into its component parts.

Format

  STDNAME^XLFNAME(.name,flags,.audit)

Input Parameters

.name:

(required) The name to be converted to standard format. It is assumed that the name is in the general format:

Family_name,Given_name(s) Middle_name Suffix(es)

If the F flag is not used, and the name contains no comma, it is assumed the name is in the general format:

Given_name(s) Middle_name Family_name Suffix(es)

The standard form of the name is returned in the NAME variable. If the C flag is passed in, the components of the name are returned in nodes descendent from NAME. (See " Output".)
flags:

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

  • C—Return name components in the NAME array. (See " Output".)

  • F—If the name passed in the name input parameter does not contain a comma, assume it is the Family Name only. For example, if the name input is "ST JAMES", return the name as "STJAMES" instead of "JAMES,ST".

  • G—Do not return AUDIT("GIVEN") even if the Given Name is missing.

  • P—Remove text in parentheses ( ), brackets [], or braces { } from the name. If such text is actually removed, return AUDIT("STRIP").
.audit:

(optional) If provided, this is an array that STDNAME^XLFNAME returns if there are any ambiguities or possible problems in standardizing the name or parsing the name into component parts. (See " Output".)

Output Parameters

name:

This parameter is set to the name that was input converted to standard format.

If the flags input parameter contains a C, the component parts of the name are returned in the NAME array:

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

If this parameter is set to the original name that was passed in the name parameter. In addition, if there were any problems in the interpretation of the name being standardized, descendents of audit are set:

AUDIT("SUBSCRIPT") = ""

where "SUBSCRIPT" can be any one of the following:

  • AUDIT("FAMILY")—The Family Name starts with ST. (The period and space are removed from the Family Name. For example, the name "ST. JOHN" is converted to "STJOHN".)

  • AUDIT("GIVEN")—Returned if there is no Given Name and the G flag is not passed in.

  • AUDIT("MIDDLE")—Returned if there are three or more names between the first comma and the Suffix(es). (All name parts except the last are assumed to be part of the Given Name. Only the last part is assumed to be the Middle Name.)

  • AUDIT("NM")—Returned if NMI or NMN appears to be used as the Middle Name. (NMI and NMN are removed from the standard name, and the Middle Name component is returned as NULL.)

  • AUDIT("NOTE")—Returned if the name appears to contain a note or flag that may not actually be part of the name. For example, the name starts with C- or EEE, or has FEE at the end.

  • AUDIT("NUMBER")—Returned if a name part (other than a valid numeric Suffix) contains a number.

  • AUDIT("PERIOD")—Returned if periods were removed.

  • AUDIT("PUNC")—Returned if punctuation was removed.

  • AUDIT("SPACE")—Returned if spaces were removed from the Family Name.

  • AUDIT("STRIP")—Returned if text in parentheses ( ), brackets [ ], or braces { } were removed from the Name. (This is done only if the P flag is passed.)

  • AUDIT("SUFFIX")—Returned if:

    • Suffix(es) are found immediately to the left of the 1st comma.

    • I, V, or X, and nothing else except valid suffixes, appear immediately after the Given Name. (It is interpreted as the Middle Name.)

    • The name immediately after the Given Name appears to be a non-numeric suffix (except I, V, and X), and everything after that also appear to be suffixes. (It is assumed there are a Given Name and Suffix(es), but no Middle Name.)

    • M.D. or M D is found at the end of the name, or before any valid suffixes at the end of the name. (It is assumed that M and D are initials in the Given or Middle Name rather than a Suffix.)

    • The name part before any recognizable suffixes is more than one character in length and does not contain any vowels or Y. It is interpreted as a suffix.

    • Suffix is found between commas immediately after the Family Name.

Details

Standard Name

In forming the standard name, the following changes are made:

  1. The name is converted to uppercase.

  2. In the Family Name:

    1. Semicolons (;) and colons (:) are converted to hyphens (-).

      Spaces and all other punctuation except hyphens are removed.

    2. Spaces and all other punctuation except hyphens are removed.

  3. In the other name parts (Given Name, Middle Name, and Suffix).

    1. Semicolon, colons, commas (,), and periods (.) are converted to spaces.

      Spaces and all other punctuation except hyphens are removed.

    2. All punctuation except hyphens and spaces are removed.

  4. Hyphens and spaces at the beginning and end of the name are removed.

  5. Two or more consecutive hyphens/spaces are replaced with a single hyphen/space.

  6. Any suffixes immediate preceding the comma are moved to the end.

  7. The suffixes indicating birth positions 1st, 2nd, 3rd, ..., 10th are converted to their Roman numeral equivalents I, II, III, … X.

  8. DR immediately after the comma (or if there is no comma, at the beginning of the name), is assumed to be a suffix and moved to the end of the name.

  9. Any suffixes between two commas immediate after the Family Name are moved to the end of the name.

  10. NMI or NMN used as a Middle Name is deleted.
Component Parts Name

In forming the component parts of the name, only the following changes are made:

  1. The name component is converted to uppercase.

  2. In the Family Name, semicolons (;) and colons (:) are converted to hyphens (-).

  3. In the other name parts (Given Name, Middle Name, and Suffix), semicolons, colons, and commas (,) are converted to spaces.

  4. Hyphens and spaces at the beginning and end of the name are removed.

  5. Two or more consecutive hyphens/spaces are replaced with a single hyphen/space.

  6. A Middle Name of NMI or NMN is changed to NULL.

  7. Spaces after periods are removed.

  8. Accent graves (`) and carets (^) are removed.

In parsing the name into its component parts, if the name contains a comma or the F flag is passed, STDNAME^XLFNAME looks for suffixes immediately to the left of the first comma, and at the very end of the name. The suffixes it recognizes are 1ST through 10TH, JR, SR, DR, MD, ESQ, DDS, RN, ARNP, DO, PA, and Roman numerals I through X.

NOTE: The ARNP, DO, and PA suffixes were added with Kernel Patch XU*8.0*535.

If a name part before any recognizable suffixes is more than one character in length, and contains no vowel or Y, it is also assumed to be a suffix. The Name Standardization looks for the DR suffix immediately after the first comma, and for any suffix between two commas immediately after the Family Name. The portion of the name to the left of the comma, less any suffixes, is assumed to be the Family Name.

After STDNAME^XLFNAME accounts for all Suffixes, it looks at the portion of the name after the comma. It assumes that the first space-delimited piece is the Given Name. If any other pieces are left, the last one (rightmost) is assumed to be the Middle Name, and anything else is appended to the end of the Given Name.

If the name contains no comma, and the F flag is not passed, STDNAME^XLFNAME looks for suffixes at the very end of the name. The last space-delimited piece before any suffixes is assumed to be the Family Name. The first space-delimited piece is assumed to be the Given Name. If any other pieces are left, the last one (rightmost) is assumed to be the Middle Name, and anything else is appended to the end of the Given Name.

Example

In this example, the MYNAME variable is set to the name to be standardized. The C flag indicates that the name components should be returned in the MYNAME array, and the P flag indicates that parenthetical text should be removed from the name. STDNAME^XLFNAME sets MYAUD to original name passed in and sets nodes in the MYAUD array to flag changes and possible problems.

>S MYNAME="KRNUSER,FIFTY A. B. 2ND (TEST)"
>D STDNAME^XLFNAME(.MYNAME,"CP",.MYAUD)

>ZW MYNAME
MYNAME=KRNUSER,FIFTY A B II
MYNAME("FAMILY")=KRNUSER
MYNAME("GIVEN")=FIFTY A.
MYNAME("MIDDLE")=B.
MYNAME("SUFFIX")=2ND

>ZW MYAUD
MYAUD=KRNUSER,FIFTY A. B. 2ND (TEST)
MYAUD("MIDDLE")=""
MYAUD("PERIOD")=""
MYAUD("SPACE")=""
MYAUD("STRIP")=""

STDNAME^XLFNAME returned the standard form of the name in MYNAME as KRNUSER,FIFTY A B II. It interpreted FIFTY A. as the given (first) name and B. as the middle name. Since this may not be correct, MYAUD("MIDDLE") is set. Periods were removed and spaces were removed to form the standard name, therefore MYAUD("PERIOD") and MYAUD("SPACE") were set. Finally, since the parenthetical text (TEST) was removed, MYAUD("STRIP") was set.