op_sar_buf_create()
Abstract
Creates a Sar buffer of the specified type, with the specified options.
Syntax
op_sar_buf_create (buf_type, options)
| Argument | Type | Description |
|---|---|---|
buf_type |
int |
type of the new buffer [This value is a numeric code that specifies the type of Sar buffer to be created. Symbolic constants for the three Sar buffer types are listed in Table 78 “Sar Buffer Type Symbolic Constants“ on page 24; these are OPC_SAR_BUF_TYPE_SEGMENT, OPC_SAR_BUF_TYPE_RESEGMENT, and `OPC_SAR_BUF_TYPE_REASSEMBLY).] |
options |
int |
buffer option flags [This value is the bitwise OR combination of symbolic constant flags that specify the Sar buffer options to be enabled (see the Details section and Table 77 “Sar Buffer Option Symbolic Constants“ on page 23).] |
Return Type
Sbhandle
Handle identifying the created Sar buffer.
Example
/* Get the handle for the event’s ICI. */
iciptr = op_intrpt_ici ();
/* Extract the request type. */
op_ici_attr_get (iciptr, "svc_request", &svc_req);
/* Request is for opening a connection */
if (svc_req == GP_REQ_CONN_OPEN)
{
/* Allocate a connection data structure. */
conn_ptr = (GpT_Connection *) op_prg_mem_alloc (sizeof (GpT_Connection));
/* Initialize connection variables. */
conn_ptr->seq_num = 0;
conn_ptr->active = 1;
/* Create a segmentation buffer for use by the connection. */
conn_ptr->sbh = op_sar_buf_create (OPC_SAR_BUF_TYPE_SEGMENT,
OPC_SAR_BUF_OPT_PK_BNDRY);
}
Details
The options argument specifies the operational options for the buffer being created. The options supported depend on the type of buffer being created, as shown in the following table.
Table 16: Sar Buffer Options for Creating Buffers
| Buffer Type | Supported Options | Option Flags |
|---|---|---|
| Any Type | default options (none) | OPC_SAR_BUF_OPT_DEFAULT |
| Segmentation & Resegmentation | packet boundary segment padding |
OPC_SAR_BUF_OPT_PK_BNDRYOPC_SAR_BUF_OPT_SEG_PAD |
| Reassembly | automatic flush | OPC_SAR_BUF_OPT_FLUSH_AUTO |
Invalid option flags passed to this KP are ignored, but recoverable errors are generated.
Note: The timed flush option (OPC_SAR_BUF_OPT_FLUSH_TIMED) cannot be set using this KP, but can be assigned to existing reassembly buffers via the KP op_sar_buf_options_set().
Once created, a Sar buffer’s type cannot be changed (e.g., a reassembly buffer is always a reassembly buffer).
Purpose
Provides a mechanism to create a Sar buffer for later use. Sar buffers must exist in order to perform any of the segmentation and reassembly services offered by Sar package KPs, because the buffers store the data used by the services (for example, segmentation buffers hold the data of source packets until it is removed in segments). Therefore, this KP is usually called from the initialization section of process models, or in the case of connection-oriented process models, from the initialization section of connections. This KP can create all three types of Sar buffer, so there are no KPs specialized for creating specific buffer types; in fact, there is no other way to create a Sar buffer.
Errors
- Program Abort: KP requires process context
- Program Abort: Buffer type value (
<buf_type>) is invalid. - Program Abort: Virtual memory limits exceeded. Too many allocated objects.
- Recoverable Error: Invalid option (
<option>) for specified buffer type. - Recoverable Error: Invalid option (
OPC_SAR_BUF_OPT_FLUSH_TIMED) for specified buffer type upon creation.
Reference
- Use the KP op_sar_buf_destroy() to deallocate a Sar buffer after it is no longer needed
- Use the KP op_sar_buf_options_set() to set options on a Sar buffer after it has been created
- Use the KP op_sar_buf_print() to print information about a Sar buffer to the standard output
- Use the KP op_sar_buf_size() to determine the number of bits stored in a Sar buffers