Document revision date: 19 July 1999

You can add comments to Compaq-supplied messages documentation. Comments display with change bars immediately following the Compaq-supplied description. This feature is a handy way to publicize a site-specific solution for a common problem.

How to Perform This Task

1. Extract the message to which you want to add a comment. The following example extracts hypothetical message NOSNO:

   $ HELP/MESSAGE/EXTRACT=NOSNO.MSGHLP NOSNO

2. Edit the .MSGHLP file to add your comment. The .MSGHLP file format uses a unique numerical prefix to designate the message, facility, explanation, and user action sections of the message description. Add your comments at the end using a "5" prefix.

   1NOSNO, can't ski; no snow 2XCSKI, XCSKI Program 3Your attempt to ski failed because there is no snow. 4Wait until there is snow and attempt the operation again. 5If you don't want to wait, go to a location where there is 5snow and ski there. 5 5Or, try ice skating instead!

   
   Tips for modifying files:

   • Limit your comments to 60 characters per line so that they do not exceed the terminal display area.
   • Use a "5" prefix on blank lines too.
   • Do not edit Compaq-supplied data. Any such edits are ignored when the comment is added to the database. Section 5.6.5 describes how you can alter Compaq-supplied data.
3. Update the database by inserting the updated message:

   $ HELP/MESSAGE/INSERT=NOSNO.MSGHLP

   
   The comment is now displayed following the Compaq-supplied message description.

Example

$ HELP/MESSAGE/EXTRACT=ACCVIO.MSGHLP ACCVIO

[Edit ACCVIO.MSGHLP to add your comment.]

$ HELP/MESSAGE/INSERT=ACCVIO.MSGHLP

5.6.5 Changing Compaq-Supplied Data

You cannot use the procedure described in Section 5.6.4 to alter Compaq-supplied information. The recommended way to permanently change Compaq-supplied information is to send your comments to the OSSG Documentation Group (see the Preface for Internet and mail addresses) or contact a Compaq support representative.

The sequence described in this section allows you to modify Compaq-supplied data, with the following results:

• The Compaq-supplied message is deleted from the database and your version of the message is inserted.
• The message you modify subsequently displays with change bars to designate it as unsupported, user-supplied data.

  Note Currently, the Compaq-supplied message is reinserted into the database at the next upgrade and the user-supplied text is overwritten.

How to Perform This Task

1. Extract the message having the text or description you want to change:

   HELP/MESSAGE/EXTRACT=filename.MSGHLP search-string

2. Check the .MSGHLP file to ensure that your search did not pick up any messages that you do not want to change. Delete any such messages that you want to preserve out of the .MSGHLP file.
3. Delete the Compaq-supplied version of the message from the Help Message database by specifying the .MSGHLP file as input. The following command deletes all messages in the .MSGHLP file from the default .MSGHLP$DATA file:

   HELP/MESSAGE/DELETE=filename.MSGHLP

4. Edit the .MSGHLP file to make your changes.
5. Insert the revised message description into the Help Message database:

   HELP/MESSAGE/INSERT=filename.MSGHLP

   
   Your version of the message now appears in the database with change bars to indicate that it is not a Compaq-supplied message.

Example

$ HELP/MESSAGE/EXTRACT=NOFILES.MSGHLP NOFILES $ HELP/MESSAGE/DELETE=NOFILES.MSGHLP

[Edit NOFILES.MSGHLP to change the text.]

$ HELP/MESSAGE/INSERT=NOFILES.MSGHLP

5.6.6 Adding Messages to Compaq-Supplied Database Files

The OpenVMS System Messages: Companion Guide for Help Message Users describes how to create your own .MSGHLP$DATA files to add new messages to the Help Message database. Keeping your messages in a separate file can simplify your messages bookkeeping and ensure that your messages are preserved through future upgrades.

With write access to Compaq-supplied .MSGHLP$DATA files, you can alternatively insert your own messages into the Compaq-supplied MSGHLP$LIBRARY.MSGHLP$DATA file. However, messages inserted using this technique will currently be overwritten at the next upgrade. You can, however, save your input .MSGHLP files and repeat the insertion process at the next upgrade.

How to Perform This Task

1. Create a .MSGHLP file with your message descriptions in it. ( Section 5.6.4 includes an example of the .MSGHLP file format.)
2. Specify your .MSGHLP file as input to update the Compaq-supplied .MSGHLP$DATA file. Assuming that MSGHLP$LIBRARY.MSGHLP$DATA is the default, all you must enter is:

   HELP/MESSAGE/INSERT=filename.MSGHLP

Example

$ HELP/MESSAGE/INSERT=MYMESSAGES.MSGHLP

5.7 Customizing Mail

You can customize the operation of Mail on your system, including sending mail directly to a user's mail file if the node the user is on is currently in your OpenVMS Cluster system.

You customize Mail by defining the logical name MAIL$SYSTEM_FLAGS as a system and executive mode logical name. For example:

$ DEFINE/SYSTEM/EXECUTIVE_MODE MAIL$SYSTEM_FLAGS 1

The value of the logical name MAIL$SYSTEM_FLAGS is interpreted in the following ways:

Value	Meaning
1	Indicates that this node is part of a homogeneous OpenVMS Cluster system. In other words, all disks are accessible to the cluster, and a common SYSUAF file and a common mail file exist for the cluster. When this bit is set, the system checks the node to which you are sending mail to see if it is currently in the cluster. If the node is in the cluster, the system bypasses DECnet, and the message is written directly to the recipient's mail file. (Note that the node must be up to determine whether it is part of the cluster.)
2	Directs Mail to set the OpenVMS Cluster system breakthrough flag when issuing the $BRKTHRU service to notify the recipient of new mail. This flag is used only in OpenVMS Cluster systems and, typically, only in homogeneous OpenVMS Cluster systems (in other words, flag 1 is also set).
4	Directs Mail to include the time the message was delivered in the notification message displayed on the recipient's terminal.
+ 8	Directs Mail to use DECnet VAX address syntax when the system is running DECnet-Plus.
+16	Directs Mail to use DECnet-Plus address syntax.

For example, if MAIL$SYSTEM_FLAGS translates to 7, the system selects the first three flags. If the logical name does not translate, the default is 0, which indicates that no flags are set.

On VAX systems, if neither 8 nor 16 is in the value for MAIL$SYSTEM_FLAGS, the system checks to see whether DECnet for OpenVMS or DECnet-Plus is running on the system and requires the appropriate address syntax. Note that, ordinarily, you do not set either flag.

If the number of new (unread) mail messages displayed on the user's screen is inconsistent with the actual number of new messages, enter the READ/NEW command once (for each nonexistent message) when there is no new mail.

In mail messages sent through DECnet, users can specify node names and user names as logical names. Any access control information in the node name or logical name is ignored.

On VAX systems running DECnet-Plus, users can also specify node synonyms.

5.8 Setting Up the Multipurpose Internet Mail Extension (MIME) Utility

MIME is the standard used to attach nontext files to mail messages to send them over the Internet. The MIME utility allows users to read and compose MIME-encoded mail messages on OpenVMS systems.

Understanding the MIME Utility

With MIME, users can encode and send nontext files such as graphics or audio files encoded as plain text; however, those files are often unreadable. The MIME utility decodes MIME files sent over the Internet to their original form. MIME also allows users to create MIME-encoded files, which can be sent as mail messages using the OpenVMS Mail utility.

For more information on how users can use the MIME utility, refer to the OpenVMS User's Manual.

5.8.1 Defining a Foreign Command

Your only installation work is to define a foreign command to run the utility, for example:

MIME:== $SYS$SYSTEM:MIME.EXE

5.8.2 Initializing the MIME Utility

Users start the MIME utility from the OpenVMS DCL prompt by entering the following command:

$ MIME file-name

Entering a file name is optional; without a file name, the MIME utility simply displays its prompt:

MIME>

When a user starts the MIME utility, the initialization process performs the following steps:

1. In the user's VMSmail profile, the MIME utility looks up the user's mail directory and default editor for use with the MIME utility.
2. The MIME utility refers to the following lists of internal defaults:
   • Content-types
     The MIME utility refers to this list before displaying incoming messages. The list contains content-types that the MIME utility recognizes and the information needed to decode each content-type received into its original format.
     An example of a MAILCAP entry, from RFC 1524, is as follows:

     application/postscript; ps-to-terminal %s;\ needsterminal application/postscript; ps-to-terminal %s; \compose=idraw %s

     
     The syntax of the entry is shown in Example 5-1. You can add content-types to the list MIME recognizes by creating a MAILCAP.DAT file. (Example 5-2 contains an example of a MAILCAP.DAT file.)

   • File-extensions
     The MIME utility refers to this list before sending outgoing messages. The list contains OpenVMS file extensions and the content-type associated with each extension. The MIME utility needs these extensions to include in a MIME-formatted message body it sends.
     Each line in the file-extension list is made up of the following items:

     extension, content-type/subtype, (optionally) Content-Transfer-Encoding string

     
     Examples of lines in a file-extension list follow:

     exe, application/vms-exe, base64 doc, application/ms-word, base64

     
     You can add file extensions and matching content-types to the list the MIME utility recognizes by creating a FILETYPES.DAT file, which is described in Table 5-4.

Table 5-4 lists and describes files you might want to create to customize the MIME utility on your system.

Table 5-4 MIME Utility Optional Files

File	Purpose
MIME$MAILCAP.DAT	For the display and parsing of incoming messages.
MIME$FILETYPES.DAT	For the assignment of content-types to outgoing attached files.
MIME$BCK.FDL	For backup save sets.
MIME$EXE.FDL	For OpenVMS executables.
MIME$OBJ.FDL	For OpenVMS .OBJ files.
MIME$OLB.FDL	For OpenVMS object libraries.
MIME$TXT.FDL	For text files.
MIME$PREAMBLE.TXT	For text that prefixes outgoing messages containing MIME-encoded attachments.
MIME$EPILOGUE.TXT	For text that suffixes outgoing messages containing MIME-encoded attachments.

Place these files in the SYS$MANAGER: directory.

5.8.3.1 MIME$MAILCAP.DAT File Processing

The format of the MAILCAP file originated in RFC 1524, A User Agent Configuration Mechanism for Multimedia Mail Format Information, by N. Borenstein, September, 1993. The MIME utility uses instructions in this file to interpret and display messages and attachments. By following these instructions, the MIME user agent calls external programs to display the content-types found in MIME messages.

Example 5-1, which is an excerpt from RFC 1524, describes the MAILCAP file format in modified Backus-Naur Format (BNF).

Example 5-1 MAILCAP File Format

Mailcap-Entry = typefield ; view-command [";" 1#field] typefield = propertype / implicit-wild propertype = type "/" wildsubtype implicitwild = type wildsubtype = subtype / "*" view-command = mtext mtext = *mchar mchar = schar / qchar schar = * <any CHAR except ";","\", and CTLS> qchar = "\" CHAR ; may quote any char field = flag / namedfield namedfield = fieldname "=" mtext flag = "needsterminal" ; All these literals are to / "copiousoutput" ; be interpreted as / x-token ; case-insensitive fieldname = / "compose" ;Also, all of these / "composetyped" ;are case-insensitive. / "print" / "edit" / "test" / "x11-bitmap" / "textualnewlines" / "description" / x-token

Notes:

• The terms type, subtype, and x-token are defined in MIME.
• Although the definition of schar includes the percent sign (%), this character has a special meaning in the UNIX (and possibly other) semantics. It therefore needs to be quoted as a qchar to be used literally.

You can customize the MAILCAP.DAT file to specify a File Descriptor Language (FDL) for a specific content-type to extract message parts on your system. Example 5-2 contains an example of a MAILCAP.DAT file.

Example 5-2 MAILCAP.DAT File

! ! MIME$MAILCAP.DAT ! ! Local customizations of content types and processing options ! ! Use xv.exe to display images image/*; xv %s ! ! Use Netscape for html attachments text/html; netscape %s ! ! Convert BACKUP save sets into proper format with a custom fdl application/vms-backup; ;x-fdl=sys$manager:mime$bck.fdl

5.8.3.2 MIME$FILETYPES.DAT File Processing

The optional MIME$FILE_TYPES.DAT file contains lists of OpenVMS file extensions and the MIME content-type associated with each one. ADD command processing uses the FILETYPE structure to designate the content-type of an OpenVMS file to be attached to a composed message.

The syntax of the file format is similar to that of the MIME$MAILCAP.DAT file, with the "#" character indicating comments. Each line in the file contains a single file extension (without the leading '.'), followed by the content-type and subtype to be associated with files that use that extension.

Optionally, the line can include the Content-Transfer-Encoding string (7bit, 8bit, Base64 or Quoted-printable), which is used to encode the contents of the file for transmission in the message. 7bit, 8bit, Base64 or Quoted-printable are the standard MIME encodings and the only ones accepted. If no encoding is specified, the MIME utility uses 7bit.

5.8.4 Adding Preamble and Epilogue Text

Users who receive MIME messages and who do not have the MIME utility installed will see only unreadable text. This text will give them no clues to the contents of the message they have received. The MIME utility allows you to include plain text at the beginning and end of such messages to describe the information in the message. These messages are displayed only if no MIME-compliant user agent is on the user's system.

You can create these optional text files for the MIME utility to use before and after MIME messages:

SYS$MANAGER:MIME$PREAMBLE.TXT SYS$MANAGER:MIME$EPILOGUE.TXT

5.9 Setting Correct Time Zone Information on Your System

Beginning with OpenVMS Version 7.0, the DEC C RTL implements its default date/time support for programs compiled with DEC C Version 5.2 using a model based on Coordinated Universal Time (UTC), an international standard for measuring time of day.

Using UTC allows the DEC C RTL to implement ANSI C/POSIX functionality. In addition, the UTC model makes the DEC C RTL compatible with the Compaq UNIX and POSIX RTL time functions. With a UTC-based system, users can perform the following actions:

• Compute the time in any time zone
• Correctly compute past and future times, taking daylight saving time into account
• Use the ANSI C gmtime routine and make use of the tm-isdst field of the tm structure

The following sections explain these concepts and tasks:

Concept or Task	Section
Understanding time-setting concepts: Coordinated Universal Time (UTC) Time differential factor (TDF) Daylight saving time and standard time Time zones	Section 5.9.1
Determining your system's TDF	Section 5.9.2
Using UTC$TIME_SETUP.COM: Setting the time zone on your system Setting the TDF on your system	Section 5.9.3
Adjusting for daylight saving time and standard time	Section 5.9.4
Setting time in an OpenVMS Cluster environment	Section 5.9.5

5.9.1 Understanding Time-Setting Concepts

Understanding some time concepts will help you see the importance of setting the correct time zone and TDF on your system.

5.9.1.1 Coordinated Universal Time

Coordinated Universal Time (UTC) is similar in most respects to Greenwich Mean Time (GMT). Under the UTC time standard, zero hours occurs when the Greenwich Meridian is at midnight. Unlike local time, which can go backward and forward depending on daylight saving time, UTC always increases.

Local times can be up to 12 hours behind Greenwich Mean Time or 13 hours ahead of it.

Because UTC is independent of time zones, you can use UTC around the world; for example, it is 2:00 UTC at the same moment in Paris as well as in Tokyo. You can examine data that is time-stamped with UTC values in Paris and Tokyo without complicated conversions to deal with local time zones.

	privacy and legal statement
6017PRO_016.HTML