Best practices for designing SMF records

Consider the following list of guidelines when designing SMF records:
  1. Never compromise compatibility with existing records or fields.
  2. Never change the meaning, format, or length of any existing field. If the meaning, format or length do change, add a new field.
  3. Add a new field to the end of a section rather than in front of an existing field within the section.
  4. Always use the standard SMF header fields.
  5. Use a standard SMF subtype field even if only the subtype is present.
  6. Use record types 0-127 and 1152-2047 for IBM® records; Use record types 128-1151 for applications and independent software vendor (ISV) products.
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. Consider adding a release indicator to allow programs to identify whether certain changes are present.
  13. 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.
  14. 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.
  15. 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.
  16. To generate a record that contains an Extended SMF record header, see the section Generating records with Extended headers. Do not change the format of the header for a record with an existing type and subtype. Such a change to an existing record would be incompatible for programs that read and consume that record.