tmm_propagation_spec_calc_pathloss()
Note: Requires Terrain Modeling Module functionality
Abstract
Performs a path loss calculation using a specified propagation specification.
Syntax
tmm_propagation_spec_calc_pathloss (spec, tda_state_ptr, tx_position_ptr, rx_position_ptr, center_frequency, bandwidth, verbose, status_ptr, message_buffer_v, zone_used)
| Argument | Type | Description |
|---|---|---|
spec |
const TmmT_Propagation_Spec * |
Propagation specification to use when selecting a propagation model. |
tda_state_ptr |
void * |
Used by pipeline stages to pass arguments to the path loss calculation function. |
tx_position_ptr |
TmmT_Position * |
Path endpoint corresponding to position of the transmitter. |
rx_position_ptr |
TmmT_Position * |
Path endpoint corresponding to position of the receiver. |
center_frequency |
double |
Center frequency of the signal, in Hertz. |
bandwidth |
double |
Bandwidth of the signal, in Hertz. |
verbose |
int |
Desired verbosity mode for reporting path loss calculation messages to the simulation log, either OPC_TRUE or OPC_FALSE. Performs the same function as tmm_verbose_set(). |
status_ptr |
TmmT_Loss_Status * |
Area to be filled by the path loss calculation function to indicate the status of the calculation. Will be either TmmC_Loss_Valid, TmmC_Loss_No_Closure, or TmmC_Loss_Error. |
message_buffer_v |
char |
Buffer to hold messages generated by the path loss calculation (see Details). |
zone_used |
TmmT_Propagation_Zone * |
Area to be filled with the zone used for the calculation. Test with tmm_zone_valid(); a false result means no zone was selected, true means this zone was used for the path loss calculation. |
Return Value
double
Path loss in decibels. (Check status_ptr to see if this value is a valid path loss.)
Header
tmm.h
Example
Extract from dra_closure.ps.c:
TmmT_Propagation_Zone zone_used;
/** Call the propagation spec's path loss calculation method. **/
/** The function can report: **/
/** a signal loss value **/
/** a error condition (e.g. invalid elevation) **/
/** a lack of link closure - so no communication is **/
/** possible. **/
FIN_MT (tmm_spec_closure_calc (pkptr));
/* Get transmission frequency in Hz. */
tx_base_freq = op_td_get_dbl (pkptr, OPC_TDA_RA_TX_FREQ);
tx_bandwidth = op_td_get_dbl (pkptr, OPC_TDA_RA_TX_BW);
tx_center_freq = tx_base_freq + (tx_bandwidth / 2.0);
/* Get transmitter's location. */
tx_position.latitude = op_td_get_dbl (pkptr, OPC_TDA_RA_TX_LAT);
tx_position.longitude = op_td_get_dbl (pkptr, OPC_TDA_RA_TX_LONG);
tx_position.elevation = op_td_get_dbl (pkptr, OPC_TDA_RA_TX_ALT);
/* Get receiver's location. */
rx_position.latitude = op_td_get_dbl (pkptr, OPC_TDA_RA_RX_LAT);
rx_position.longitude = op_td_get_dbl (pkptr, OPC_TDA_RA_RX_LONG);
rx_position.elevation = op_td_get_dbl (pkptr, OPC_TDA_RA_RX_ALT);
/* Propagation models shipped by Riverbed don't use any extra state */
/* so just for clarity set the local state pointer to null. */
/* User created propagation models can pass any value they wish. */
pipeline_invocation_state_ptr = OPC_NIL;
/* Determine if TMM verbose is requested. */
/* This can be set using the tmm_verbose environment attribute */
trace_active = op_prg_odb_trace_active ()|| op_prg_odb_pktrace_active (pkptr);
verbose_active = tmm_verbose_get ();
/*** Call the propagation spec's path_loss_calc_method. ***/
for (str_index = 0; str_index < TMMC_LOSS_MESSAGE_BUF_NUM_STRS; str_index++)
tmm_spec_msg_buffer_v [str_index] [0] = '\0';
tmm_spec_path_loss_dB =
tmm_propagation_spec_calc_pathloss (
DraS_Closure_Prop_Spec_Ptr,
pipeline_invocation_state_ptr,
&tx_position,
&rx_position,
tx_center_freq,
tx_bandwidth,
verbose_active || trace_active,
&tmm_spec_loss_status,
tmm_spec_msg_buffer_v,
&zone_used);
Details
If the propagation specification contains several zones, TMM picks a zone with a compatible frequency range and containing the largest percentage of the signal path, then uses the propagation model specified by that zone. For more details, see "Creating a Propagation Specification" on page 14.
The message_buffer_v argument provides a location for the path loss calculation to report text messages about any problems or errors in calculating a loss value. This variable is a two-dimensional array comprising five arrays of 512-character buffers.
Purpose
This function calculates the path loss for a given path, frequency, and bandwidth, using a propagation model selected from a given propagation specification.
Errors
- None.
Reference
- None.