op_sar_srcbuf_seg_access()
Abstract
Copies a segment of the specified length from the head of the specified source buffer (either a segmentation or resegmentation buffer). A pointer to the segment is returned.
Syntax
op_sar_srcbuf_seg_access (sb_hndl, bit_count)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the source buffer-of-interest [This value must identify a Sar source buffer (i.e., either a segmentation or a resegmentation buffer). A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
bit_count |
OpT_Sar_Size |
number of bits in accessed segment within buffer [This value is an integer, instead of a double as in the case of the bit_count arguments of some Sar KPs, because the maximum size of a Sar segment is below the maximum value of an integer.] |
Return Type
Packet*
Pointer to the segment packet accessed within the specified source buffer.
Example
/* Determine interrupt type. */
intrpt_type = op_intrpt_type ();
/* Process self interrupt. */
if (intrpt_type == OPC_INTRPT_SELF)
{
/* Process segment time-out event. */
if (op_intrpt_code () == SEG_TIME_OUT)
{
/* Generate another copy of last sent segment. */
seg_pkptr = op_sar_srcbuf_seg_access (seg_sbh, last_seg_size);
/* Retransmit the new segment copy, and set retransmit flag. */
op_pk_send (seg_pkptr, TX_OUTSTRM);
seg_rtx = 1;
}
}
Details
Accessing a packet from a Sar buffer does not remove the copied bits from the buffer; they are left in the buffer, available for further copies, or a final removal operation. The scenario of generating multiple redundant Sar segments and sending them through various paths of a network to a common destination generally does not require the user of the Sar package to perform elaborate accounting of the whereabouts of segments. The destination reassembly buffer will ignore redundant bit-ranges that are inserted, and the Sar package will keep track of all outstanding references to source packets.
The bit_count argument requests a segment of a certain length; however, there are several factors that affect whether the actual segment obtained by this KP has the requested length. If the number of bits in the buffer is less than the requested segment length, or if the packet boundary option has been set on the buffer and the bits at the head of the buffer are associated with a source packet that has less remaining bits than the requested segment length, then the segment will be limited to contain only the number of available data bits. However, if the segment padding option has been set on the buffer, then even if the number of data bits available for the accessed segment is less than the segment’s requested length, the segment will be padded to the requested length. The padding bits will not factor into the size of source packets reassembled from padded segments.
Purpose
Provides a mechanism for copying a Sar segment from a segmentation or resegmentation buffer. Accessing a Sar segment is an alternative to removing it from the source buffer that proves useful when the requirement arises to regenerate the segment (e.g., when retransmission of a segment is necessary). If a segment is accessed from a source buffer, and circumstances develop in which it does not need to be regenerated, the segment can be flushed from the head of the buffer via the KP op_sar_srcbuf_bits_flush().
Errors
- Standard Sar errors (see Table 15)
- Program Abort: Number of bits value (
<bit_count>) must be greater than 0. - Program Abort: Buffer type (reassembly) is invalid for this KP, should be (segmentation or resegmentation).
- Program Abort: Virtual memory limits exceeded. Too many allocated objects.
- Recoverable Error: Allocation of object block failed / Object type (
<ob_type>).
Reference
- Use the KP op_sar_srcbuf_seg_remove() to remove a Sar segment from the head of a (re)seg. buffer
- Use the KP op_sar_srcbuf_bits_flush() to flush a bit-range, identified by local bit index and length, from a (re)segmentation buffer
- Use the KP op_sar_segbuf_pk_insert() to insert a source packet at the tail of a segmentation buffer
- Use the KP op_sar_rsgbuf_seg_insert() to insert a Sar segment at the tail of a resegmentation buffer