Historical Statistics Facility (HSF)


When the Historical Statistics Facility (HSF) is enabled for an Enterprise Server for .NET CICS or JES region, event records are created in the region database at run time for transactions and jobs respectively. These records can be subsequently processed to provide detailed information of their execution. This information can include:
  • Number of times a transaction has been executed
  • Number of times a job has been executed
  • Time spent by a transaction within CICS APIs
  • Time spent by a transaction or job step within SQL APIs
  • Time spent by a transaction processing files
  • Time spent by a transaction processing TD and TS queues
  • Time spent processing a job and its steps
  • I/O counts for datasets used by job steps
  • Number of transactions executed per second

Region Configuration

The Region Startup File Editor is used to configure HSF for CICS and JES regions. You can specify whether HSF is to be enabled for the region, the lifetime of the HSF data, and whether HSF data is to be persisted across region cold-starts. HSF data will always be persisted across warm-starts. By default, HSF is not enabled for a region.

If a lifetime is configured for HSF data, a running Enterprise Server for .NET system will periodically delete any data that has expired the specified lifetime. HSF data can also be manually deleted using the Enterprise Server for .NET Administration UI or seehsf command-line tool.

Note: To ensure accuracy for transaction and job submission latency (i.e. the time between when a task is queued and when it goes into execution), the system clocks of any machines running SEPs and the machine hosting the region database should be synchronized. This does not mean that the system clocks of all of these machines have to be set in the same time zone; it is the underlying UTC time of the machines that is important to be synchronized.
Note: If a region was created with HSF enabled using a version of Enterprise Server for .NET earlier than 2.3 hot-fix 2, HSF will be implicitly disabled during region start-up if HSF data persistence has been enabled in the region start-up file. This can be resolved by doing one of the following:
  • Disable HSF data persistence and cold start the region
  • Drop the region database and cold start the region

Administering HSF

HSF can be administered by either the Enterprise Server for .NET Administration UI, or the seehsf command-line tool.

The Enterprise Server for .NET Administration UI's Historical Statistics Facility view for the currently selected region can be used to:
  • Configure the range of HSF data to be used to display statistics for (e.g. maximum number of transactions, maximum number of jobs, and start/end date/time)
  • Display the average latency and execution time, and the number of times executed of each transaction id or job name
  • Display the latency and execution time of each individual transaction or job executed
  • Delete HSF data from the region database
The seehsf command-line tool can be used to:
  • Create a .csv file containing data for each individual transaction instance. By default this data includes the latency time, execution time and time spent within CICS APIs. It can optionally additionally include the time spent processing files, TD queues and/or TS queues
  • Create a .csv file containing data aggregated for each transaction id. This data includes the number of times each transaction id has been executed, together with the average latency time, execution time and time spent within CICS APIs
  • Create a .csv file containing data grouped by time (e.g. showing the number of transactions executed per 1 minute interval)
  • Restrict the amount of data written to the .csv file by allowing the specification of the maximum number of records, maximum number of transactions, and start/end date/time
  • Delete HSF data from the region database
  • Display information about the HSF configuration for the region
Note: seehsf outputs times to the .csv file in the format hh:mm:ss.mmm (e.g. 10:35:58.734). Unfortunately Microsoft's excel spreadsheet program does not recognise this as a valid time format, resulting in the data being incorrectly displayed. To view the time data correctly, apply the following custom time format to the Time column: