Declaration

NINT SnapShot(NINT opcode, pTEXT rqstdesc, pVOID snapbufr, VRLEN buflen);

Parameters:

• opcode specifies the action to be taken by the snapshot function.
• rqstdesc points to an ASCII string containing the input information.
• snapbufr points to an output buffer of length buflen.

Different opcodes require different combinations of input and output parameters ranging from using neither of them to both of them.

Description

FairCom DB tracks and reports a wealth of performance-oriented statistics. FairCom DB's Snapshot capability enables the capture of performance monitoring data using a combination of configuration file options and the SnapShot API function. The performance data can be captured automatically at specified intervals or on demand in the following ways:

• The ctstat utility provides a command-line interface to the SNAPSHOT API function, supporting output of FairCom DB statistics at the core database engine, user, file, and function levels.
• Configuration file options support automatic performance snapshots by specifying the interval between automatic snapshots and the contents of the snapshots. The performance data captured by automatic snapshots are written to the FairCom DB system event log (SYSLOG) files.
• Use DIAGNOSTICS options to capture the automatic system snapshot data to the human-readable SNAPSHOT.FCS file.
• The SnapShot() API function can control automatic snapshots, overriding configuration options (if any), and can capture on-demand performance data:
  • to either the SYSLOG files or to the human-readable SNAPSHOT.FCS file, or
  • as a return to the calling program.

For tips about monitoring system performance using this function, see Performance Monitoring Using the SnapShot API.

Snapshot Contents

Each snapshot is composed of a structure (ctGSMS for system info, ctGUMS for user info, and ctGFMS for file info) followed optionally by a variable region. Each of the three snapshot structures contains information about the size of the structure and the amount of variable information, if any, following the structure. Further, if the output buffer is too small to hold all the variable information, the contents member of the main structure will have the ctSNAPSHOTtruncated bit turned on if information had to be truncated.

Note These structure definitions may vary depending on the version of the FairCom DB and FairCom DB client versions you are using. Please consult the c-tree headers for the actual structure definition that is in use. Differences in definitions between a given ctstat client and FairCom DB may make ctstat incompatible with that server, in which case the ctstat utility displays an error message indicating structure incompatibility.

The only variable information consists of an array of function timing results for the overall system or for a user. The array is composed of ctWRKSTT structures. Function timings are described below, but these timings are only for direct calls from c-tree clients.

^ High-Resolution Timers - Most of the elapsed times accumulated in the snapshots are based on high-resolution timers that report in numbers of ticks and are stored in eight-byte integers. The description following each structure member contains a ‘^’ to indicate results based on high-resolution timers. To convert such times to seconds, divide by the ticks per second, a system dependent value stored in the scthrbastim member of each snapshot structure.

Snapshot Structures

See Snapshot Contents. 

System Snapshot Support

The SnapShot API function supports logging FairCom DB system statistics. For a listing of the system statistics FairCom DB collects, refer to the ctGSMS structure in the Snapshot Contents section below. The supported operations include:

File Snapshot Support

The SnapShot API function supports logging FairCom DB file statistics. For a listing of the file statistics the FairCom DB collects, refer to the ctGFMS structure in the Snapshot Contents section. The supported operations include:

User Snapshot Support

The SnapShot API function supports logging FairCom DB user statistics. For a listing of the user statistics FairCom DB collects, refer to the ctGUMS structure in the Snapshot Contents section below. The supported operations include:

Automatic Snapshot Support

The SnapShot API function supports starting, stopping, and resuming automatic snapshots. The following table shows the parameters to pass to SnapShot to perform these operations.

Combined Snapshot Support

The SnapShot API function supports logging combined snapshots containing FairCom Server system statistics and user and file statistics for the specified activated users and files. This ability is supported by the following operation:

Function Timing Snapshot Support

The SnapShot API function supports profiling of FairCom DB API function calls (function timing) and timing of user-defined operations. The supported operations include:

• Starting and stopping the collection of FairCom DB API function timing statistics.
• Resetting the function timing statistics.
• Accumulating timings in user-defined timing baskets. Users may define up to 8 different timing baskets. A begin mark call establishes a high resolution starting time for the specified basket. An end mark call causes the specified basket counter to be incremented, and the elapsed time is added to the timing basket. The baskets are numbered from 0 to 7.

Note Function timings require a significant number of calls to the high-resolution timer, and are more consistent with diagnostic or testing modes of operation.

The following table shows the parameters to pass to SnapShot() to perform these operations.

SQL Snapshot Support

The SnapShot API function has a mode for retrieving FairCom DB SQL specific statistics.

File List Snapshot Support

CHECKLOCK List Snapshot Support

Memory Snapshot Support

Replication Snapshot Support

The SnapShot API function supports logging information about the FairCom Server replication state. For a listing of the transaction statistics the FairCom Server collects, refer to the ctPSSreplread structure in the Snapshot Contents section below. The supported operations include:

Transaction Snapshot Support

The SnapShot API function supports logging FairCom Server transaction statistics. For a listing of the transaction statistics the FairCom Server collects, refer to the ctPSStransaction structure in the Snapshot Contents section. The supported operations include:

Snapshot support for FairCom Server compiled without transaction control

In V11 and later, support has been added for using the SnapShot feature when FairCom DB Server is compiled without transaction control (UNIFRMAT server, for example). (ctSNAPSHOT API and utilities such as ctstat and FairCom DB Monitor use this feature.)

Prior to this modification, FairCom DB Monitor had limited functionality on a server that did not support transaction processing: the Files Stats, System Snapshot, User Snapshot, Snapshot Favorites, and Function Timing tabs could not be used (typical error = 454, not supported).

Note Although the snapshot API is now supported by a server, some functions (such as replication and transaction information) are not supported.

Return Values

SnapShot returns NO_ERROR (0) on success, or an error code on failure.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

   ...

   ctGSMS* my_sysSnap;
   NINT rc = 0;

   my_sysSnap = (ctGSMS*) malloc(sizeof(ctGSMS));
   memset(my_sysSnap, 0, sizeof(ctGSMS));

   rc = InitISAMXtd(10, 10, 8192/128, 10, 0, "ADMIN", "ADMIN", "FAIRCOMS");
   if (rc) {
      printf("InitISAMXtd Error: %d\n", rc);
      return (rc);
   }
 
   /* Take a System SnapShot */
   rc = SnapShot(ctPSSsystem, NULL, my_sysSnap, sizeof(ctGSMS));
   if (rc) {
      printf("SnapShot Error: %d\n", rc);
      return (rc);
   }

   rc = CloseISAM();
   if (rc)
      printf("CloseISAM Error: %d\n", rc);

   /* Print Memory statistics */
   printf("High Mem: %d\n", my_sysSnap->sctmemhgh);
   printf("Current Mem: %d\n", my_sysSnap->sctmemsum);
    

   /* Print Disk I/O statistics */
   printf("Read ops: %d\n", my_sysSnap->sct_rdops);
   printf("Read bytes: %d\n", my_sysSnap->sct_rdbyt);
   printf("Write ops: %d\n", my_sysSnap->sct_wrops);
   printf("Write bytes: %d\n", my_sysSnap->sct_wrbyt);

   /* Print Platform Specific Server information */
   printf("Server flavor: %d\n", my_sysSnap->sflvr);
   printf("Alignment: %d\n", my_sysSnap->salgn);
   printf("Pointer size: %d\n", my_sysSnap->spntr);

   free(my_sysSnap);

   ...

See also

• Performance Monitoring Using the SnapShot API