Name Standardization APIs ICR (3065)

Name

Value

NUMBER

3065

IA #

3065

DATE CREATED

2000/03/15

CUSTODIAL PACKAGE

KERNEL

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XLFNAME

NAME

Name Standardization APIs

GENERAL DESCRIPTION

Supported Name Standardization APIs.

STATUS

Active

XLFNAME

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

STDNAME(.NAME,FLAGS,.AUDIT)

Name Standardization Routine
============================
This procedure parses a name and converts it into the following standard
format:

Family_name,Given_name<space>Middle_name<space>Suffix

A name in standard format is entirely in upper-case, 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.

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

1. The name is converted to uppercase.

2. In the Family Name:

a. Semicolons (;) and colons (:) are converted to hyphens (-).
b. Spaces and all other punctuation except hyphens are removed.

3. In the other name parts (Given Name, Middle Name, and Suffix).
a. Semicolon, colons, commas (,), and periods (.) are converted to
spaces.
b. 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.

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

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 up-arrows (^) 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 and Roman
numerals I through X. 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 variable MYNAME 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="VAN DOE,JOHN A. B. 2ND (TEST)"
>D STDNAME^XLFNAME(.MYNAME,"CP",.MYAUD)

>ZW MYNAME
MYNAME=VANDOE,JOHN A B II
MYNAME("FAMILY")=VAN DOE
MYNAME("GIVEN")=JOHN A.
MYNAME("MIDDLE")=B.
MYNAME("SUFFIX")=2ND

>ZW MYAUD
MYAUD=VAN DOE,JOHN A. B. 2ND (TEST)
MYAUD("MIDDLE")=""
MYAUD("PERIOD")=""
MYAUD("SPACE")=""
MYAUD("STRIP")=""

STDNAME^XLFNAME returned the standard form of the name in MYNAME as
VANDOE,JOHN A B II. It interpreted JOHN 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.

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Both

(Required) NAME is 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.

Output:
------
NAME 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)

FLAGS

Input

Flags to control processing. Possible values are:.

C - Return name components in the NAME array.

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 - Don't 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

Both

If provided, this is an array that STDNAME^XLFNAME
returns if there are any ambiguities or possible problems in stardardizing the
name or parsing the name into component parts.

Output:
------
AUDIT is set to the original name that was passed in NAME.

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 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 isn't 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.7 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 doesn't contain any vowels or Y. It is interpreted as
a suffix.

- A Suffix is found between commas immediately after the Family Name.

$$CLEANC(COMP,FLAGS)

Name Component Standardization Routine
======================================
This extrinsic function takes a single name component and returns that name in
standard format.

Examples:
--------
1. Standardize family (last) name:

$$CLEANC^XLFNAME("O'BRIEN-DE LA ROSA","F) --> OBRIEN-DELAROSA
$$CLEANC^XLFNAME("ST. JAMES","F") --> STJAMES

2. Standardize other (non-family) name components:

$$CLEANC^XLFNAME("E.C.) --> E C
$$CLEANC^XLFNAME("RENEE'") --> RENEE
$$CLEANC^XLFNAME("MARY ANN") --> MARY ANN
$$CLEANC^XLFNAME("JO-ANNE") --> JO-ANNE

VARIABLES

TYPE

VARIABLES DESCRIPTION

COMP

Input

(Required) The name component to be converted to
standard format.

FLAGS

Input

Flags to control processing. Possible values are:

F - If the name component to be converted is the FAMILY (LAST) NAME, pass
the "F" flag. With the "F" flag, colons (:), semicolons (;), and commas (,)
are converted to hyphens (-). Spaces and all punctuation except hyphens are
removed. Leading and trailing spaces and hyphens are removed.  Two or more
consecutive spaces or hyphens are replaced with a single space or hyphen.

Without the "F" flag, the component is converted to upper case.  Colons,
semicolons, commas, and periods (.) are converted to spaces. All punctuation
except for hyphens and spaces are removed. Leading and trailing spaces and
hyphens are removed.  Two or more consecutive spaces or hyphens are replaced
with a single space or hyphen. Birth position indicators 1ST through 10TH are
changed to their Roman numeral equivalents.

NAMECOMP(.NAME)

Component Parts from Standard Name
==================================
This procedure takes a name in standard format and returns in an array the
component parts of that name.

Example:
-------
In this example, the variable MYNAME is set to the standard name, and the
NAMECOMP^XLFNAME call is made to return in the MYNAME array the component
parts of that name:

>S MYNAME="MCDONALD-STJAMES,MARY ANN S MD"
>D NAMECOMP^XLFNAME(.MYNAME)

>ZW MYNAME
MYNAME=MCDONALD-STJAMES,MARY ANN S MD
MYNAME("FAMILY")=MCDONALD-STJAMES
MYNAME("GIVEN")=MARY ANN
MYNAME("MIDDLE")=S
MYNAME("SUFFIX")=MD

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Both

(Required) NAME is the name in standard format to be
parsed.  NAMECOMP^XLFNAME returns the component parts of the name in nodes
descendent from NAME.

Output:
------
The component parts of the name are returned in the NAME array passed in.

NAME("FAMILY) = Family (last) Name
NAME("GIVEN") = Given (first) Name
NAME("MIDDLE") = Middle Name
NAME("SUFFIX") = Suffix(es)

$$NAMEFMT(.NAME,FORMAT,FLAGS)

Formatted Name from Name Components
===================================
This extrinsic function returns a name converted to a form useful for display.

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:
--------
1. Suppose the MYNAME array contains the following elements:

MYNAME("PREFIX") = "MR."
MYNAME("GIVEN") = "JOHN"
MYNAME("MIDDLE") = "K."
MYNAME("FAMILY") = "O'BRIEN"
MYNAME("SUFFIX") = "JR"
MYNAME("DEGREE") = "PHD"

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

$$NAMEFMT^XLFNAME(.MYNAME,"F") --> O'BRIEN JOHN K. JR
$$NAMEFMT^XLFNAME(.MYNAME,"F","C") --> O'BRIEN,JOHN K. JR
$$NAMEFMT^XLFNAME(.MYNAME,"F","CS") --> OBRIEN,JOHN K JR
$$NAMEFMT^XLFNAME(.MYNAME,"F","CSD") --> OBRIEN,JOHN K JR PHD
$$NAMEFMT^XLFNAME(.MYNAME,"F","CDcXc") --> O'BRIEN,JOHN K., JR, PHD
$$NAMEFMT^XLFNAME(.MYNAME,"F","CSL12") --> OBRIEN,JOH K
$$NAMEFMT^XLFNAME(.MYNAME,"F","CMD") --> O'Brien,John K. Jr PhD
$$NAMEFMT^XLFNAME(.MYNAME,"G") --> JOHN K. O'BRIEN JR
$$NAMEFMT^XLFNAME(.MYNAME,"G","D") --> JOHN K. O'BRIEN JR PHD
$$NAMEFMT^XLFNAME(.MYNAME,"G","Dc") --> JOHN K. O'BRIEN JR, PHD
$$NAMEFMT^XLFNAME(.MYNAME,"G","P") --> MR. JOHN K. O'BRIEN JR
$$NAMEFMT^XLFNAME(.MYNAME,"G","Xc") --> JOHN K. O'BRIEN, JR
$$NAMEFMT^XLFNAME(.MYNAME,"G","PDcXc") --> MR. JOHN K. O'BRIEN, JR, PHD
$$NAMEFMT^XLFNAME(.MYNAME,"G","PDcXcM") --> Mr. John K. O'Brien, Jr, PhD
$$NAMEFMT^XLFNAME(.MYNAME,"G","S") --> JOHN K OBRIEN JR
$$NAMEFMT^XLFNAME(.MYNAME,"G","SL12") --> JOH K OBRIEN
$$NAMEFMT^XLFNAME(.MYNAME,"O") --> O'BRIEN
$$NAMEFMT^XLFNAME(.MYNAME,"O","S") --> OBRIEN
$$NAMEFMT^XLFNAME(.MYNAME,"O","M") --> O'Brien
$$NAMEFMT^XLFNAME(.MYNAME,"O","L3") --> O'B

2. If an entry in the NAME COMPONENTS 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 is:

FILE = 200 FIELD = .01
IENS = "32,"
PREFIX = "MR."
GIVEN NAME = "JOHN"
MIDDLE NAME = "K."
FAMILY NAME = "O'BRIEN"
SUFFIX = "JR"
DEGREE = "PHD"

you can set:

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

and call $$NAMEFMT^XLFNAME as in Example 1, listed previously, to return the
name in various formats.

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Input

(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 (#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
STDNAME^XLFNAME.

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

FORMAT

Input

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

Input

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.

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.

$$BLDNAME(.NAME,MAX)

Build Name from Component Parts
===============================
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)

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:
--------
1. Suppose the MYNAME array contains the following elements:

MYNAME("FAMILY") = "O'BRIEN"
MYNAME("GIVEN") = "JOHN"
MYNAME("MIDDLE") = "K."
MYNAME("SUFFIX") = "JR"

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

$$BLDNAME^XLFNAME(.MYNAME) --> OBRIEN,JOHN K JR
$$BLDNAME^XLFNAME(.MYNAME,12) --> OBRIEN,JOH K

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

FILE = 200
FIELD = .01
IENS = "32,"
GIVEN NAME = "JOHN"
MIDDLE NAME = "K."
FAMILY NAME = "O'BRIEN"
SUFFIX = "JR"

you can set:

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

and call $$BLDNAME^XLFNAME as in Example 1, listed previously:

$$BLDNAME^XLFNAME(.MYNAME) --> OBRIEN,JOHN K JR
$$BLDNAME^XLFNAME(.MYNAME,12) --> OBRIEN,JOH K

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Input

(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 file 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 the name components are obtained by making a call to
STDNAME^XLFNAME.

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

MAX

Input

The maximum length of the Name to be returned.
(Default = 256)

$$HLNAME([.]NAME,FLAGS,DELIM)

Convert Name to HL7 Formatted Name
==================================
This extrinsic function converts a name to HL7 format.

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. 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:
--------
1. Suppose the MYNAME array contains the following elements:

MYNAME("PREFIX") = "MR."
MYNAME("GIVEN") = "JOHN"
MYNAME("MIDDLE") = "K."
MYNAME("FAMILY") = "O'BRIEN"
MYNAME("SUFFIX") = "JR"
MYNAME("DEGREE") = "PHD"

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

$$HLNAME^XLFNAME(.MYNAME) --> O'BRIEN^JOHN^K.^JR^MR.^PHD
$$HLNAME^XLFNAME(.MYNAME,"","~") --> O'BRIEN~JOHN~K.~JR~MR.~PHD
$$HLNAME^XLFNAME(.MYNAME,"S","~") --> OBRIEN~JOHN~K~JR~MR~PHD
$$HLNAME^XLFNAME(.MYNAME,"L12S") --> OBRIEN^JOH^K

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

FILE = 200
FIELD = .01
IENS = "32,"
PREFIX = "MR."
GIVEN NAME = "JOHN"
MIDDLE NAME = "K."
FAMILY NAME = "O'BRIEN"
SUFFIX = "JR"
DEGREE = "PHD"

you can set:

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

and call $$HLNAME^XLFNAME as in Example 1, listed previously, to return the
name in various formats.

3. Convert a name passed by value to HL7 format:

$$HLNAME^XLFNAME("O'BRIEN,JOHN HOWARD II") --> O'BRIEN^JOHN^HOWARD^II
$$HLNAME^XLFNAME("O'BRIEN,JOHN HOWARD II","S") --> OBRIEN^JOHN^HOWARD^II
$$HLNAME^XLFNAME("O'BRIEN,JOHN HOWARD II","SL10","~") --> OBRIEN~J~H

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Input

(Required) The component parts of the name to be
converted:

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 file 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 STDNAME^XLFNAME.

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

Another alternative is to pass in the unsubscripted NAME parameter the name to
be converted. $$HLNAME^XLFNAME obtains the components parts of that name by
making a call to STDNAME^XLFNAME. This alternative is recommended only for
names that do not have associated entries on the NAME COMPONENTS file.

FLAGS

Input

Flags to controls processing. Possible values are:

L#  - Truncate the returned name to a maximum Length of # characters, where
# is an integer between 1 and 256.

S   - Return the name components in the HL7 formatted name in Standardized
form.

DELIM

Input

The delimiter to use in the HL7 string. (Default =
"^")

$$FMNAME(NAME,FLAGS,DELIM)

Convert HL7 Formatted Name to Name
==================================
This extrinsic function converts an HL7 formatted name to a name in VISTA
format.

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. 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:
--------
1. Convert an HL7 formatted name to a VISTA name:

$$FMNAME^XLFNAME("O'BRIEN^JOHN^K.^JR^MR.^PHD") --> O'BRIEN,JOHN K. JR
$$FMNAME^XLFNAME("O'BRIEN^JOHN^K.^JR^MR.^PHD","S") --> OBRIEN,JOHN K JR
$$FMNAME^XLFNAME("O'BRIEN^JOHN^K.^JR^MR.^PHD","M") --> O'Brien,John K. Jr
$$FMNAME^XLFNAME("O'BRIEN^JOHN^K.^JR^MR.^PHD","SL12") --> OBRIEN,JOH K

2. Convert an HL7 formatted name where "~" is the delimiter to a standard
name:

$$FMNAME^XLFNAME("O'BRIEN~JOHN~K.~JR~MR","S","~") --> OBRIEN,JOHN K JR

3. Convert an HL7 formatted name to a standard name, and return the
components of that name in the MYNAME array:

>S MYNAME="O'BRIEN^JOHN^K.^JR^MR.^PHD"

>W $$FMNAME^XLFNAME(.MYNAME,"CS")
OBRIEN,JOHN K JR

>ZW MYNAME
MYNAME=O'BRIEN^JOHN^K.^JR^MR.^PHD
MYNAME("FAMILY")=O'BRIEN
MYNAME("GIVEN")=JOHN
MYNAME("MIDDLE")=K.
MYNAME("SUFFIX")=JR

VARIABLES

TYPE

VARIABLES DESCRIPTION

NAME

Both

(Required) NAME is the HL7 name to be converted. If
the "C" flag is used, the name components are returned in nodes descendent
from NAME.

FLAGS

Input

Flags to controls processing. Possible values are:

C  - Return name components in the NAME array. (See "Output:" just after
this table.)

L# - Truncate the returned name to a maximum Length of # characters, where #
is an integer between 1 and 256.

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

S  - Return the name in Standardized form.

DELIM

Input

The delimiter used in the HL7 formatted name.
(Default = "^")