MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
-------------------------------------------------------------------------------
mh-format
PURPOSE
Defines message formats for the Message Handling (MH) Package.
DESCRIPTION
Several MH commands use either a format string (similar to a printf string) or
a format file to format their output. For example, the scan command uses a
format string to format the scan listing for each message, while the repl
command uses a format file to format a message reply.
A MH format string is similar to a printf string, but uses multi-letter escape
sequences beginning with the "%" character. In addition, the usual C language
backslash characters (\b, \f, \n, \r, and \t) are recognized. To continue a
format line to the next line, precede the new-line character with a \
(backslash).
The interpretation model is based on a simple machine with two registers, num
and str. The former contains an integer value; the latter a string value.
When an escape is processed, if the escape requires an argument, the system
reads the current value of either num or str, and if the escape returns a
value, the system writes either num or str.
Note: The MHL command will look for inbox in $CWD/Mail instead of $HOME/Mail.
Escapes
Escapes are of three types: component, function, or control. A component
escape, specified as "%{"name"}", is created for each header found in the
message being processed. For example, "%{date}" refers to the Date: field of
the appropriate message. A component escape is always string valued.
A control escape is one of:
%<escape
%|
%>
which corresponds to an if-then-else construct. If escape has a nonzero value
(for integer-valued escapes) or is not empty (for string-valued escapes), then
everything up to "%|" or "%>" (whichever comes first) is interpreted;
otherwise, processing skips to "%|" or "%>" (whichever comes first) and starts
interpreting again.
A function escape is specified as "%("name")" and is statically defined. Here
is the list:
Processed November 7, 1990 MH-FORMAT(5,F) 1
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
+-----------+----------------------+------------------------------------------+
|Escape | Argument | Returns Interpretation |
+-----------+----------------------+------------------------------------------+
|nonzero | integer integer | num has a nonzero value |
+-----------+----------------------+------------------------------------------+
|zero | integer integer | num is zero |
+-----------+----------------------+------------------------------------------+
|eq | integer integer | num == width |
+-----------+----------------------+------------------------------------------+
|ne | integer integer | num != width |
+-----------+----------------------+------------------------------------------+
|gt | integer integer | width > num |
+-----------+----------------------+------------------------------------------+
|null | string integer | str is empty |
+-----------+----------------------+------------------------------------------+
|nonnull | string integer | str is not empty |
+-----------+----------------------+------------------------------------------+
|putstr | string | Display str |
+-----------+----------------------+------------------------------------------+
|putstrf | string | Display str in the specified width, for |
| | | example: |
| | | |
| | | %20(putstrf{subject}) |
| | | |
+-----------+----------------------+------------------------------------------+
|putnum | integer | Display num |
+-----------+----------------------+------------------------------------------+
|putnumf | integer | Display num in the specified width, for |
| | | example: |
| | | |
| | | %4(putnum(msg)) |
| | | |
+-----------+----------------------+------------------------------------------+
|msg | integer | Message number |
+-----------+----------------------+------------------------------------------+
|cur | integer | Message is current |
+-----------+----------------------+------------------------------------------+
|size | integer | Size of message |
+-----------+----------------------+------------------------------------------+
|strlen | string integer | Length of str |
+-----------+----------------------+------------------------------------------+
|me | string | The user's mailbox |
+-----------+----------------------+------------------------------------------+
|plus | integer | Add width to num |
+-----------+----------------------+------------------------------------------+
|minus | integer | Subtract num from width |
+-----------+----------------------+------------------------------------------+
|charleft | integer | Space left in output buffer |
+-----------+----------------------+------------------------------------------+
|timenow | integer | Seconds from 00:00:00 GMT |
| | | January 1, 1970 |
+-----------+----------------------+------------------------------------------+
Processed November 7, 1990 MH-FORMAT(5,F) 2
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
When str is a date, these escapes are useful:
+-----------+----------------------+------------------------------------------+
|Escape | Argument | Returns Interpretation |
+-----------+----------------------+------------------------------------------+
|sec | string integer | Seconds of the minute |
+-----------+----------------------+------------------------------------------+
|min | string integer | Minutes of the day |
+-----------+----------------------+------------------------------------------+
|hour | string integer | Hours of the day (24-hour clock) |
+-----------+----------------------+------------------------------------------+
|mday | string integer | Day of the month |
+-----------+----------------------+------------------------------------------+
|mon | string integer | Month of the year |
+-----------+----------------------+------------------------------------------+
|wday | string integer | Day of the week (Sunday=0) |
+-----------+----------------------+------------------------------------------+
|year | string integer | Year of the century |
+-----------+----------------------+------------------------------------------+
|yday | string integer | Day of the year |
+-----------+----------------------+------------------------------------------+
|dst | string integer | Daylight savings in effect |
+-----------+----------------------+------------------------------------------+
|zone | string integer | Time zone |
+-----------+----------------------+------------------------------------------+
|sday | string integer | Day of the week known. Values are: |
| | | |
| | | 1 Explicit day |
| | | 0 Implicit (the MH package figured it |
| | | out) |
| | | -1 Unknown (the MH package could not |
| | | figure it out) |
| | | |
+-----------+----------------------+------------------------------------------+
|clock | string integer | Seconds from 00:00:00 GMT January 1, |
| | | 1970 |
+-----------+----------------------+------------------------------------------+
|rclock | string integer | Seconds prior to current time |
+-----------+----------------------+------------------------------------------+
|month | string string | Month of the year |
+-----------+----------------------+------------------------------------------+
|lmonth | string string | Month of the year (long form) |
+-----------+----------------------+------------------------------------------+
|tzone | string string | Time zone |
+-----------+----------------------+------------------------------------------+
|day | string string | Day of the week |
+-----------+----------------------+------------------------------------------+
|weekday | string string | Day of the week (long) |
+-----------+----------------------+------------------------------------------+
|tws | string string | RFC 822 rendering of the date |
+-----------+----------------------+------------------------------------------+
Processed November 7, 1990 MH-FORMAT(5,F) 3
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
+-----------+----------------------+------------------------------------------+
|Escape | Argument | Returns Interpretation |
+-----------+----------------------+------------------------------------------+
|pretty | string string | A more user-friendly rendering |
+-----------+----------------------+------------------------------------------+
|nodate | string | Date was not parseable |
+-----------+----------------------+------------------------------------------+
When str is an address, these escapes are useful:
+-----------+----------------------+------------------------------------------+
|Escape | Argument | Returns Interpretation |
+-----------+----------------------+------------------------------------------+
|pers | string string | The personal name of the address |
+-----------+----------------------+------------------------------------------+
|mbox | string string | The local part of the address |
+-----------+----------------------+------------------------------------------+
|host | string string | The domain part of the address |
+-----------+----------------------+------------------------------------------+
|path | string string | The route part of the address |
+-----------+----------------------+------------------------------------------+
|type | string integer | The type of host. Values are: |
| | | |
| | | -1 uucp |
| | | 0 Local |
| | | 1 Network |
| | | 2 Unknown |
| | | |
+-----------+----------------------+------------------------------------------+
|nohost | string integer | No host was present in the address |
+-----------+----------------------+------------------------------------------+
|ingrp | string integer | The address appeared inside a group |
+-----------+----------------------+------------------------------------------+
|gname | string string | The name of the group (present for first |
| | | address only) |
+-----------+----------------------+------------------------------------------+
|note | string string | Commentary text |
+-----------+----------------------+------------------------------------------+
|proper | string string | RFC 822 rendering of the address |
+-----------+----------------------+------------------------------------------+
|friendly | string string | A more user-friendly rendering |
+-----------+----------------------+------------------------------------------+
|mymbox | string | The address refers to the user's mailbox |
+-----------+----------------------+------------------------------------------+
|formataddr | string | Display str in an address list |
+-----------+----------------------+------------------------------------------+
mhl.format
The mhl.format file is similar to other MH format files, but controls the
format of output when mhl is the message listing program. Each line of the
mhl.format file must have one of the following forms:
Processed November 7, 1990 MH-FORMAT(5,F) 4
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
;comment
:cleartext
variable"[",variable"...]"
component:"["variable"...]"
A line beginning with the ; character contains comments that are ignored. A
line beginning with the : character contains text for output. A line that
contains the : character only produces a blank output line. A line beginning
with component defines the format of the specified component. If a variable
follows a component, the variable applies only to that component. Lines
having other formats define the global environment.
Variables that have integer or string values as arguments must be followed by
an "=" (equal) character and the integer or string value (for example,
"overflowoffset=5"). String values must also be enclosed in double quotation
characters (for example, "overflow"***""). An argument specified with the
suffix /G has global scope. An argument specified with the suffix /L has local
scope.
The entire mhl.format file is parsed before output processing begins. Thus, if
a variable's global setting is defined in multiple places, the last global
definition for that variable describes the real global setting.
The following table lists the mhl.format variables and their arguments:
+------------------+--------------+-------------------------------------------+
|Variable | Argument | Description |
+------------------+--------------+-------------------------------------------+
|width | integer | Set the screen width or component width |
+------------------+--------------+-------------------------------------------+
|length | integer | Set the screen length or component length |
+------------------+--------------+-------------------------------------------+
|offset | integer | Indent component the specified number of |
| | | columns |
+------------------+--------------+-------------------------------------------+
|overflowtext | string | Output string at the beginning of each |
| | | overflow line |
+------------------+--------------+-------------------------------------------+
|overflowoffset | integer | Indent overflow lines the specified |
| | | number of columns |
+------------------+--------------+-------------------------------------------+
|compwidth | integer | Indent component text the specified |
| | | number of columns after the first line of |
| | | output |
+------------------+--------------+-------------------------------------------+
|uppercase | flag | Output text of component in all upper |
| | | case characters |
+------------------+--------------+-------------------------------------------+
|nouppercase | flag | Output text of component in the case |
| | | entered |
+------------------+--------------+-------------------------------------------+
Processed November 7, 1990 MH-FORMAT(5,F) 5
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
+------------------+--------------+-------------------------------------------+
|Variable | Argument | Description |
+------------------+--------------+-------------------------------------------+
|clearscreen | flag/G | Clear the screen before each page |
+------------------+--------------+-------------------------------------------+
|noclearscreen | flag/G | Do not clear the screen before each page |
+------------------+--------------+-------------------------------------------+
|bell | flag/G | Produce an audible indicator at the end |
| | | of each page |
+------------------+--------------+-------------------------------------------+
|nobell | flag/G | Do not produce an audible indicator at |
| | | the end of each page |
+------------------+--------------+-------------------------------------------+
|component | string/L | Use string as the name for the specified |
| | | component instead of the string component |
+------------------+--------------+-------------------------------------------+
|nocomponent | flag | Do not output the string component for |
| | | the specified component |
+------------------+--------------+-------------------------------------------+
|center | flag | Center component on line. This variable |
| | | works for one-line components only. |
+------------------+--------------+-------------------------------------------+
|nocenter | flag | Do not center component |
+------------------+--------------+-------------------------------------------+
|leftadjust | flag | Strip off the leading whitespace |
| | | characters from each line of text |
+------------------+--------------+-------------------------------------------+
|noleftadjust | flag | Do not strip off the leading whitespace |
| | | characters from each line of text |
+------------------+--------------+-------------------------------------------+
|compress | flag | Change new-line characters in text to |
| | | space characters |
+------------------+--------------+-------------------------------------------+
|nocompress | flag | Do not change new-line characters in text |
| | | to space characters |
+------------------+--------------+-------------------------------------------+
|formatfield | string | Use string as the format string for the |
| | | specified component |
+------------------+--------------+-------------------------------------------+
|addrfield | flag | The specified component contains |
| | | addresses |
+------------------+--------------+-------------------------------------------+
|datefield | flag | The specified component contains dates. |
+------------------+--------------+-------------------------------------------+
|ignore | unquoted | Do not output component specified by |
| | string | string |
+------------------+--------------+-------------------------------------------+
EXAMPLE
The following format string is the default for the scan command. It has been
divided into several pieces for readability. The first part is:
Processed November 7, 1990 MH-FORMAT(5,F) 6
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
%4(putnum(msg))%<(cur)+%| %>%<{replied}-%| %>
This says that the message number should be displayed in four digits. If the
message is the current message, a + character is displayed next; otherwise, a
space character is displayed. If a "replied:" field is present, then a -
(minus) is displayed; otherwise, a space is displayed. Next:
%02(putnumf(mon{date}))%02(putnumf(mday{date}))
The month and day are displayed in two digits (zero filled). Next:
%<{date} %|*>
If no "date:" field is present, then an "*" (asterisk) character is displayed;
otherwise, a space character is displayed. Next:
%<(mymbox{from})To:%14(putstr(friendly{to}))
If the message is from me, display "to:" followed by a friendly rendering of
the first address in the "To:" field. Continuing:
%|%17(putstrf(friendly{from}))%
If the message is not from me, display "from:" followed by the "from:" address.
And finally:
%{subject}<<%{body}>>
Display the subject and initial body of the message.
This method of formatting messages allows you to extract individual fields and
display them in the format you desire.
If you use the -form file argument when you run scan, it treats each line in
file as a format string and acts accordingly. The following files contain scan
listing formats that you can look at: /usr/lib/mh/scan.time,
/usr/lib/mh/scan.size, and /usr/lib/mh/scan.timely.
The following line is an example of a line that could appear in the mhl.format
file:
width=80,length=40,clearscreen,overflow"***",overflowoffset=5
This format line defines the screen size to be "80" columns by "40" rows and
specifies that the screen should be cleared before each page, that the overflow
text should be flagged with the string "***", and that the overflow indentation
should be "5" columns.
RELATED INFORMATION
The ap, dp, mhl, and scan commands in AIX Operating System Commands Reference.
Processed November 7, 1990 MH-FORMAT(5,F) 7
MH-FORMAT(5,F) AIX Technical Reference MH-FORMAT(5,F)
The "Overview of the Message Handling Package" in Managing the AIX Operating
System.
Processed November 7, 1990 MH-FORMAT(5,F) 8