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

$$HLNAME^XLFNAME(): Convert Name to HL7 Formatted Name

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

Description

The $$HLNAME^XLFNAME extrinsic function converts an input name to an HL7 formatted name.

Format

  $$HLNAME^XLFNAME([.]name[,flags][,delim])

Input Parameters

[.]name:

(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 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(): 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)

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 the STDNAME^XLFNAME(): Name Standardization Routine API. This alternative is recommended only for names that do not have associated entries on the NAME COMPONENTS (#20) file.
flags:

(optional) 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:

(optional) The delimiter to use in the HL7 string (default is ^).

Output

returns:

Returns the converted name in 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

Example 1

Suppose the MYNAME array contains the following elements:

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

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

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

>W X
KRNUSER^SIXTY^K.^JR^MR.^PHD
>S X=$$HLNAME^XLFNAME(.MYNAME,"","~")

>W X
KRNUSER~SIXTY~K.~JR~MR.~PHD
>S X=$$HLNAME^XLFNAME(.MYNAME,"S","~")

>W X
KRNUSER~SIXTY~K~JR~MR~PHD
>S X=$$HLNAME^XLFNAME(.MYNAME,"L12S")

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

You can set:

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

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

Example 3

Convert a name passed by value to HL7 format:

>S X=$$HLNAME^XLFNAME("KRNUSER,SIXTY HOWARD II"

>W X
KRNUSER^SIXTY^HOWARD^II
>S X=$$HLNAME^XLFNAME("KRNUSER,SIXTY HOWARD II","S")

>W X
KRNUSER^SIXTY^HOWARD^II
>S X=$$HLNAME^XLFNAME("KRNUSER,SIXTY HOWARD II","SL10","~")

>W X
KRNUSER~S~H