@Name (Formula Language)

Allows you to manipulate hierarchical names. You can abbreviate the canonical format of a name, expand an abbreviated name to its canonical format, identify particular components within the name, and reverse the order of the components so that you can categorize a view by hierarchical names.

Enables you to convert a name between the Domino® and LDAP formats.

Note: LDAP conversion is new with Release 6.

Syntax

@Name( [ action ] ; name )

Parameters

[ action ]

Keyword. Indicates what you want done to the name -- whether you want to expand it, abbreviate it, convert it, and so on (see list of possible actions).

With @Name, you can perform the following actions:

[A]

Returns the ADMD component (administration management domain name) of a hierarchical name.

[ABBREVIATE]

Abbreviates a hierarchical name, removing the component labels. This saves space in the display, and looks friendlier.

[ADDRESS821]

Note: This keyword is new with R5.

Returns an Internet address in the format based on RFC 821 Address Format Syntax regardless of whether the original address was in RFC 821 or RFC 822 form. Case must be exact.

[C]

Returns the country/region component of a hierarchical name.

[CANONICALIZE]

Expands an abbreviated name, adding in whatever components are missing, as well as their labels. Missing components are taken from the current user ID, not from the Domino® Directory.

[CN]

  • Returns the common name component of a Domino® name.
  • Returns the local part of an Internet address in the format based on RFC 821 Address Format Syntax.
  • Returns the phrase part of an Internet address in the format based on RFC 822 Address Format Syntax.

[G]

Returns the given name component (the first name) of a hierarchical name.

[HIERARCHYONLY]

Note: This keyword is new with R5.

Strips the CN component of a hierarchical name and returns the remaining components.

[I]

Returns the initials component of a hierarchical name.

[LP]

Note: This keyword is new with R5.

Returns the LocalPart of a standard Internet address based on RFC 822 Address Format Syntax.

[O]

Returns the organization component of the hierarchical name.

[OU n ]

Returns the specified organizational unit component of a hierarchical name; n can be from 1 to 4, as in OU1. In the canonical form of the name, the OU components are not numbered; however, they are counted from first to last so that the first occurrence of the OU label is treated as OU1, the second occurrence is treated as OU2, and so on. Notes/Domino does not accept [OU] as a keyword.

[P]

Returns the PRMD component (private management domain name) of a hierarchical name.

[PHRASE]

Note: This keyword is new with R5.

Returns the Phrase part of a standard Internet address based on RFC 822 Address Format Syntax.

[Q]

Returns the generation component (such as "Jr") of a hierarchical name.

[S]

Returns the surname component (the last name) of a hierarchical name.

[TOAT]

Note: This keyword is new with Release 6.

Returns the LDAP AttributeType name when a Domino® field name is provided.

[TODATATYPE]

Note: This keyword is new with Release 6.

Returns the Domino® data type name when an LDAP Syntax name is provided.

[TOFIELD]

Note: This keyword is new with Release 6.

Returns the Domino® field name when an LDAP AttributeType name is provided.

[TOFORM]

Note: This keyword is new with Release 6.

Returns the Domino® form name when an LDAP ObjectClass name is provided.

[TOKEYWORD]

Reverses the order in which the naming components are displayed, and replaces slashes with backslashes: Country\Organization\Organization Unit... This is useful when you want to categorize a view by the components of a user's hierarchical name (backslashes represent subcategories in views). The [TOKEYWORD] option does not return the Common Name portion of the user name.

[TOOC]

Note: This keyword is new with Release 6.

Returns the LDAP ObjectClass name when a Domino® form or subform name is provided.

[TOSYNTAX]

Note: This keyword is new with Release 6.

Returns the LDAP Syntax name when a Domino® data type name is provided.

name

Text or names, or text or names list. A user or server name, entered in any form (Notes/Domino determines the full hierarchical name and then returns the requested components) or an LDAP AttributeType, ObjectClass, or Syntax name or a Domino® form, subform, field, or data type name to be converted from LDAP to Domino® format or vice-versa.

Return value

formattedname

Text or names, or text or names list. The second parameter formatted according to the first parameter.

Usage

@Name is particularly useful for abbreviating hierarchical names in a view.

If the second parameter is a list, the function operates on each element of the list, and the return value is a list with the same number of elements.

A hierarchical name is qualified with a series of components identifying the full name, organizational unit, organization, and country or region. Using hierarchical names guarantees that each user and server has a unique name.

As the database designer, you are responsible for controlling how user names are entered and displayed within Notes® applications. For simplicity, you should allow users to enter names in abbreviated form; then you can use @Name to expand the name to its canonical format. You should also display names in abbreviated form, using @Name to convert the stored canonical format of the name to its abbreviated form.

When you use a Names, Readers, or Authors field, Notes/Domino automatically converts hierarchical names to an appropriate format for display and storage. If the user enters an abbreviated name, Notes/Domino expands it to canonical format when storing it; the name is always displayed on a form in abbreviated format.

When you display the contents of a hierarchical name field in a view there is no automatic conversion; the entire canonical format of the name is displayed. You may want to convert the name to its abbreviated form with @Name.

If you are using @Name to parse an Internet address, the address must conform to the format based on the standard RFC 821 or RFC 822 Address Format Syntax.

Note: If you attempt to use the parameters A, G, I, P, Q, or S in Notes/Domino with existing user IDs, it may appear as though the parameters do not work. These parameters were added to take advantage of the addressing used for external mail and gateway products. When a mail message is received within Notes/Domino from an external mail source, the naming convention can include additional components. The @Name function can be used to manipulate the hierarchical name, including these additional components. Domino® IDs and names do not use these additional components, therefore, it is not possible to use these six parameters with a standard Domino® ID and name.

The following is an example of a full hierarchical name that takes advantage of every parameter.

G=Joe/I=JS/S=Smith/Q=Jr/CN=Joseph Smith/OU=Assembly/OU=Engineering/O=Acme/P=PrivAdmin/ A=PubAdmin/C=US

Examples

  1. This example returns Mary Tsen/Illustration/ Documentation/Development/R&D/WorkSavers/US if a user is looking at a document where the AUTHOR field contains the hierarchical form of Mary Tsen's name. .
    				@Name([ABBREVIATE];AUTHOR)
  2. This example returns Mary Tsen.
    @Name([CANONICALIZE];"Mary Tsen")

    Since there is no slash following the name, it is a nonhierarchical name and has no additional components.

  3. This example returns CN=MaryTsen/ OU=Illustration/OU=Documentation/OU=Development/OU=R&D/O=Acme/C=US if that is the current user ID. The hierarchy of the current user ID is appended to the name; no lookup occurs in the Domino® Directory.
    @Name([CANONICALIZE];"Mary Tsen/")
  4. This example returns Mary Tsen in an informational dialog box format, if the AUTHOR field in the document contains: CN=Mary Tsen/OU=Illustration/O=Acme.
    @Prompt([Ok]; "Common Name"; @Name([CN]; AUTHOR))
  5. This example returns Development.
    @Name([OU2];AUTHOR)
  6. This example returns US\Acme\R&D\Development\Documentation\Illustration. The slashes are now backslashes, which allow the naming components to be used as subcategories in a view. The common name component is not returned.
    @Name([TOKEYWORD];AUTHOR)
  7. This example returns SStreitfeld if the User_Name field contains this Internet address in RFC 822 format "Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com> .
    @Name([LP];User_Name)
  8. This example returns "Streitfeld, Sara (Miami)" if the User_Name field contains this Internet address in RFC 822 format "Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com> .
    @Name([Phrase];User_Name)
  9. This example returns SStreitfeld@gazette.com if the User_Name field contains this Internet address in RFC 822 format "Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com> .
    @Name([ADDRESS821];User_Name)
  10. This example returns Cam/IBM If the User_Name field contains John Doe/Cam/IBM.
    @Name([HIERARCHYONLY];User_Name)
  11. This example returns "secretary," the LDAP AttributeType name for the Domino® term, "assistant."
    @Name([TOAT];"assistant")
  12. This example returns "Internet Address," the Domino® term equivalent to the LDAP AttributeType name "mail."
    @Name([TOFIELD];"mail")
  13. This example returns "Number," the Domino® term equivalent to the LDAP data type, "Integer."
    @Name([TODATATYPE];"Integer")
  14. This example returns "Directory String," the syntax used in the LDAP directory for the Domino® data type "Text."
    @Name([TOSYNTAX];"Text")

  15. This example returns "Mary Tsen" and "Jacques Blanc" in a list.
    @Name([CN]; "Mary Tsen/Acme/US" : "Jacques Blanc/Acme/FR")