FairCom ISAM for C

SnapShot

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

System Snapshot Structure

File Snapshot Structure

User Snapshot Structure

SQL Snapshot Structure

Replication Snapshot Structure

Transaction Snapshot Structure

File List Snapshot Structure

CHECKLOCK List Snapshot Structure

Memory Snapshot

Snapshot Actions and Options

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:

Snapshot action	opcode	rqstdesc	snapbufr
On-demand system snapshot returned directly in the output buffer. No entry is made in SYSLOG.	ctPSSsystem	NULL	Address of output buffer large enough to hold at least a ctGSMS structure
On-demand system snapshot written to the SNAPSHOT.FCS text file.	ctPSStext	An optional text description, or NULL	NULL

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:

Snapshot action	opcode	rqstdesc	snapbufr
Activate the file with the specified file name. Use a pattern of ‘*’ to activate all files.	ctPSSaddFileName	File name (e.g., “cust.”)	NULL
Activate the file with the specified file number.	ctPSSaddFileNo	Small integer file number (e.g., "0")	NULL
On-demand file snapshot returned directly in the output buffer for the file with file number specified by rqstdesc. No entry is made in SYSLOG.	ctPSSfile	Small integer file number (e.g., "3")	Address of output buffer large enough to hold a ctGFMS structure
Undo all file activations.	ctPSSclearFiles	NULL	NULL
On-demand file snapshot returned directly. No entry is made in SYSLOG.	ctPSSfileSystemHandle	System file number	ctGFMS buffer
On-demand snapshot of all open files written to SNAPFILE.FCS, a comma-delimited text file.	ctPSScsvFile	NULL	NULL
On-demand snapshot of all open files written to SNAPFILE.FCS, a simple text file.	ctPSStextFile	NULL	NULL
Starts collection of disk I/O timing stats. It affects the contents of a file snapshot. Disk I/O timings can also be enabled from configuration file with the entry: DIAGNOSTICS SNAPSHOT_IOTIME	ctPSStimeFileIoOn	NULL	NULL
Turn off disk I/O timings. Disk I/O timings require a significant number of calls to the high resolution timer, and are more consistent with diagnostic or testing modes of operation.	ctPSStimeFileIoOff	NULL	NULL

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:

Snapshot action	opcode	rqstdesc	snapbufr
Activate the user with the specified User ID. Use a pattern of ‘*’ to activate all users.	ctPSSaddUserID	User ID (e.g., “admin”)	NULL
Activate the user with the specified thread handle.	ctPSSaddUserHandle	Small integer thread handle (e.g., “12”)	NULL
On-demand user snapshot returned directly in the output buffer. No entry is made in SYSLOG. The snapshot is for the user calling ctSNAPSHOT().	ctPSSuser	NULL	Address of output buffer large enough to hold at least a ctGUMS structure
On-demand user snapshot returned directly in the output buffer.	ctPSSuserHandle	Small integer thread handle (e.g., “12”)	Address of output buffer large enough to hold at least a ctGSMS structure
Undo all user activations.	ctPSSclearUsers	NULL	NULL

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.

Snapshot action	opcode	rqstdesc	snapbufr
Start automatic snapshots, or change time interval if automatic snapshots are already enabled.	ctPSSstartAuto	Interval in minutes (e.g., “60”)	NULL
Stop automatic snapshots.	ctPSSstopAuto	NULL	NULL
Resume automatic snapshots with the same interval last used.	ctPSSresumeAuto	NULL	NULL

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:

Snapshot action	opcode	rqstdesc	snapbufr
On-demand snapshot of system and activated users and files written to SYSLOG. All entries to SYSLOG share the instance ID, a 4-byte integer, returned in the output buffer.	ctPSSnow	An optional text description up to 128 bytes, or NULL	Address of a 4-byte integer to hold instance ID

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.

Snapshot action	opcode	rqstdesc	snapbufr
Start collecting function-timing statistics. This can be called whether or not automatic snapshots are currently active. It affects the contents of snapshots written to SYSLOG, not when or if they occur.	ctPSStimeWorkOn	NULL	NULL
Turn off function timings.	ctPSStimeWorkOff	NULL	NULL
Mark beginning time for one of 8 user specified timing baskets.	ctPSSbegMark	Small integer between 0 and 7 (e.g., "3")	NULL
Mark ending time for user specified timing basket.	ctPSSendMark	Small integer between 0 and 7 (e.g., "3")	NULL
Clear all function-timing statistics.	ctPSStimeWorkClear	NULL	NULL
On-demand snapshot of c-tree function timings written to SNAPFUNC.FCS, a simple text file.	ctPSStextFunc	NULL	NULL
On-demand snapshot of c-tree function timings written to SNAPFUNC.FCS, a comma-delimited text file.	ctPSScsvFunc	NULL	NULL

SQL Snapshot Support

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

Snapshot action	opcode	rqstdesc	snapbufr
SQL Statement cache counters	ctPSSsqlSystem	NULL	ctSQLS

File List Snapshot Support

Snapshot action	opcode	rqstdesc	snapbufr
On demand filelist snapshot returned directly. No entry is made in SYSLOG.	ctPSSfilelist	NULL	ctGFLS

CHECKLOCK List Snapshot Support

Snapshot action	opcode	rqstdesc	snapbufr
On demand CHECKLOCK_FILE snapshot returned directly. No entry is made in SYSLOG.	ctPSSchecklockfile	NULL	ctGCMS

Memory Snapshot Support

Snapshot action	opcode	rqstdesc	snapbufr
On demand memory allocation snapshot returned directly. No entry is made in SYSLOG.	ctPSSmemAlloc	NULL	ctGMMS

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:

Snapshot action	opcode	rqstdesc	snapbufr
Retrieve information about FairCom Server replication state. On-demand replication reader snapshot is returned directly. No entry is made in SYSLOG.	ctPSSreplread

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 action	opcode	rqstdesc	snapbufr
Retrieve FairCom Server's transaction statistics.	ctPSStransaction

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.

CTDBRET_OK

Successful operation.

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);

...