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.