Consider the following list of guidelines when designing SMF records:
- Never compromise compatibility with existing records or fields.
- Never change the meaning, format, or length of any existing field.
If the meaning, format or length do change, add a new field.
- Add a new field to the end of a section rather than in front of
an existing field within the section.
- Always use the standard SMF header fields.
- Use a standard SMF subtype field even if only the subtype is present.
- Use record types 0-127 for IBM® records;
Use record types 128-255 for applications and independent software
vendor (ISV) products.
- Use the triplet convention, as seen in the SMF type 30 record,
for including variable sections (such as: offset to section, number
of sections, length of sections). Include the length of the section
containing the triplets or the number of triplets.
- If you report service units, be sure to include both the speed
constant and the service definition coefficients in the record. This
ensures they can be properly interpreted.
- Use the most precise time format available for date and time fields
and provide the GMT offset with leap seconds. Ensure you document
the format you use.
- Left justify and fill with blanks any EBCDIC and ASCII fields
and ensure you document the format. If EBCDIC or ASCII text is mixed
with binary data in a single field, ensure the format is documented.
- Use the system identifier (SID) or SYSNAME along with the SYSPLEX
name to identify a system. Ensure you document how you are identifying
the system.
- Consider adding a release indicator to allow programs to identify
whether certain changes are present.
- Avoid cumulative fields whenever possible. Instead, use interval
fields to allow the application to perform any necessary accumulation.
If you need cumulative fields, also provide interval fields.
- Ensure interval values do not become negative because of a change
to the operating environment during an interval. When the accumulated
counter wraps, document the maximum and consider including a bit to
indicate the wrap.
- If a field value is determined not valid for any reason (such
as a wrapped accumulator, or a value not obtained at the time the
record is being built), use an indicator bit to indicate that the
field is unreliable.