op_stat_annotate()
Abstract
Adds an annotation to a statistic name in the output vector file.
Syntax
op_stat_annotate (stat_handle, stat_annotation)
| Argument | Type | Description |
|---|---|---|
stat_handle |
Stathandle |
Statistic handle identifying the global or local statistic to receive the value [A statistic handle can be obtained via the KP op_stat_reg().] |
stat_annotation |
const string |
Text to be used for the statistic annotation |
Return Type
void
No return value.
Example
/* Obtain a local statistic handle for the ete delay and variance statistics. */
if (conn_id < FRMSC_PVC_CONN_STAT_COUNT)
{
frms_ete_del_lhandle = op_stat_reg ("Frame Relay PVC. Delay (sec)", conn_id,
OPC_STAT_LOCAL);
sprintf (stat_annot_str, "%s --> %s", source_FRAD_name, dest_FRAD_name);
op_stat_annotate (frms_ete_del_lhandle, stat_annot_str);
frms_ete_del_var_lhandle = op_stat_reg ("Frame Relay PVC.Delay Variance",
conn_id, OPC_STAT_LOCAL);
sprintf (stat_annot_str, "%s --> %s", source_FRAD_name, dest_FRAD_name);
op_stat_rename (frms_ete_del_var_lhandle, "Delay Variation");
op_stat_annotate (frms_ete_del_var_lhandle, stat_annot_str);
}
Details
This KP takes a stathandle and a string. The string is put inside angle brackets and appended to the statistic name in the output vector file. If the statistic is dimensional, the annotation replaces the dimension number that normally appears at the end of the statistic.
For example, if the full hierarchical name of a statistic in the output vector file is:
subnet.node.group.statistic [2]
after a call to op_stat_annotate (hndl, "location"), the full hierarchical name is:
subnet.node.group.statistic <location>
If a statistic is renamed with op_stat_rename() and annotated, the statistic name in the output vector file includes both the new name and the annotation, regardless of which operation is done first.
Purpose
Provides a mechanism for writing statistics in the output vector file and including a descriptive annotation.
Errors
- Program Abort: Segmentation violation. (due to an invalid statistic handle)
- Recoverable Error: Attempting use of unregistered statistic handle.
Reference
- Use the KPs op_stat_tag_add_dbl(), op_stat_tag_add_int32(), op_stat_tag_add_int64(), and op_stat_tag_add_str() to add tags to a statistic.
- Use the KP op_stat_reg() to obtain a statistic handle
- Use the KP op_stat_rename() to rename a statistic
- Use the KP op_stat_scalar_write() to write a value to a scalar statistic
- Use the KP op_stat_write() to write a value to an output statistic, tagged with the current simulation time
- Use the KP op_stat_write_t() to write a value to an output statistic, tagged with a specified simulation time