A box conceptually encloses part or
all of a model. The box gathers statistics
on the number of entities in the box
(i.e.,
the population) and the amount of time
entities spend in the box (i.e.,
the elapsed time). An entity might be
a customer, a message, or a resource.
Boxes are usually used to gather statistics
on queue lengths, response times, and
populations. Instrumenting a model involves
inserting function calls at the places
that entities enter and exit the box.
A table and a qtable are invisible but
integral parts of every box. Statistics
on the elapsed times are kept in the
table, statistics on the population
are kept in the qtable.
First-time users of boxes should focus
on the following three sections, which
explain how to set up boxes, instrument
a model, and produce reports. Subsequent
sections describe the more advanced
features of boxes.
A box is declared in a CSIM program
using the built-in type BOX.
Example:
BOX b;
Before a box can be used, it must be
initialized by calling the box
function.
Prototype:
BOX box(char*
name)
Example:
b = box("system");
The box name is used only to identify
the box in the output reports. Up to
80 characters in the name will be stored
by CSIM. A newly created box is always
empty. To create a non-empty box, call
the enter_box
function (described in the following
section) the appropriate number of times
immediately after creating the box.
A box can be initialized as a permanent
box using the permanent_box
function.
Prototype:
BOX permanent_box(char*
name)
Example:
b = permanent_box("system");
The information in a permanent box is
not cleared when the reset function
is called, and a permanent box is not
deleted when rerun is called. In all
other ways, a permanent box is exactly
like a box. As a general rule, do not
make a box permanent unless you have
a specific reason for doing so.
An entity enters a box by calling the
enter_box
function.
Prototype:
double enter_box(BOX
b)
Example:
timestamp = enter_box(b);
This function returns a timestamp that
must be saved by the entity that entered
the box. The entity exits the box by
calling the exit_box
function and passing to it the timestamp
that it received upon entry.
Prototype:
void exit_box(BOX
b, double entry_time)
Example:
exit_box(b, timestamp);
It is the responsibility of the programmer
to ensure that the integrity of the
timestamp is maintained while the entity
is in the box. Because boxes may be
nested or may overlap, it is advisable
to make the timestamp local to the CSIM
process and to use a separate timestamp
variable for each box. An invalid timestamp
(i.e.,
one that is less than zero or greater
than the current time) will cause an
error.
Reports for boxes are most often produced
by calling the report function, which
prints reports for all statistics gathering
objects. A report can be generated for
a specified box at any time by calling
the report_box
function.
Prototype:
void report_box(BOX
b)
Example:
report_box(b);
Reports can be produced for all existing
boxes by calling the report_boxes
function.
Prototype:
void report_boxes(void)
Example:
report_boxes();
The report for a box, as illustrated
below, will include the box name, statistics
on the elapsed times, and statistics
on the population of the box. If the
box is empty or no time has passed since
its creation or reset, messages to that
effect are printed instead of the statistics.
Note that statistics on the elapsed
times reflect only those entities that
have exited the box. Entities still
in the box when the report is produced
contribute to the population statistics
but not to the elapsed time statistics.
A summary report for all boxes can
be generated by calling the box_summary
function.
Prototype:
void box_summary(void)
Example:
box_summary();
The report that is produced contains
one line for each box and includes only
a subset of the statistics. If a box
is empty or no time has passed since
its creation or reset, some statistics
will not appear.
A histogram can be specified for the
elapsed times in a box and for the population
of a box using the following functions.
Prototype:
void box_time_histogram(BOX
b, long nbucket,
double min, double max)
Example:
box_time_histogram(b,
10, 0.0, 10.0);
Prototype:
void box_number_histogram(BOX
b, long
nbucket, long min, long max)
Example:
box_number_histogram(b,
10, 0, 10);
The histogram for the elapsed times
is the same as the histogram for a table.
See
section 11.4, "Histograms",
for details. The histogram for the population
of a box is the same as the histogram
for a qtable. See
section 12.4 , "Histograms",
for details.
Caution:
The min and max parameters of box_time_histogram
are of type double, whereas the corresponding
parameters of box_number_histogram
are of type long.
Confidence intervals can be requested
for the mean of the elapsed times in
a box and for the mean population of
a box using the following functions.
Prototype:
void box_time_confidence(BOX
b)
Example:
box_time_confidence(b);
Prototype:
void box_number_confidence(BOX
b)
Example:
box_number_confidence(b);
These two types of confidence intervals
are identical to the confidence intervals
for a table and qtable, respectively.
See
sections 11.5, "Confidence
Intervals", and 12.5,
"Confidence Intervals", for
details.
Moving windows can be specified for
the elapsed times in a box and for the
population of a box using the following
functions.
Prototype:
void box_time_moving_window(BOX
b, long n)
Example:
box_time_moving_window(b,
1000);
Prototype:
void box_number_moving_window(BOX b,
long n)
Example:
box_number_moving_window(b,
1000);
The window for the elapsed times specifies
the number of entities whose elapsed
times will be included in the statistics.
The window for the population specifies
the number of changes in the population
that will be included in the statistics.
Consequently, the simulation time covered
by these two windows may not be the
same.
All statistics maintained by a box can
be retrieved during the execution of
a model or upon its completion. The
name of a box can also be retrieved.
| Prototype: |
Functional
value: |
| char* box_name
(BOX b) |
pointer to name
of box |
| TABLE box_time_table
(BOX b) |
pointer to elapsed
time table |
| QTABLE box_number_qtable
(BOX b) |
pointer to population
qtable |
The pointer to a box's elapsed time
table can be passed to the inspector
functions for a table in order to obtain
statistics on the times that entities
have spent in the box.
Example:
max_time_in_box = table_max
(box_time_table(b));
If no entities have exited the box,
the table will be empty and zeros will
be returned for the undefined statistics.
The pointer to a box's population qtable
can be passed to the inspector functions
for a qtable in order to obtain statistics
on the population.
Example:
max_population
= qtable_max
(box_number_qtable(b));
If no time has passed, zero values will
be returned for the undefined statistics.
The name of a box can be changed at
any time using the set_name_box
function.
Prototype:
void set_name_box(BOX
b, char *new_name)
Example:
set_name_box(b,
"system");
Only the first 80 characters of the
box's name are stored.
Resetting a box causes all information
maintained by the box to be reinitialized,
except that the number currently present
in the box is saved for use in computing
future populations. All optional features
selected for the box (e.g.,
histogram, confidence intervals, moving
window) remain in effect and are also
reinitialized.
The reset
function is usually used to reset all
statistics gathering tools at once.
A specific box can be reset using the
reset_box
function.
Prototype:
void reset_box(BOX
b)
Example:
reset_box(b);
Although permanent boxes are not reset
by the reset
function, they can be reset explicitly
by calling reset_box.
When a box is no longer needed, its
storage can be reclaimed using the delete_box
function.
Prototype:
void delete_box(BOX
b)
Example:
delete_box(b);
Once a box has been deleted, it must
not be further referenced.
