op_pk_create_fmt()
Abstract
Creates a new formatted packet with a predefined structure described by the specified packet format.
Syntax
op_pk_create_fmt (format_name)
| Argument | Type | Description |
|---|---|---|
format_name |
const char* |
name of the packet format that will be assigned to the packet [This value is the name of a packet format created using the Packet Format Editor. The packet format specified must be located in the model directories, or an error will occur. Packet format files have the suffix .pk.m appended to the format name.] |
Return Type
Packet*
Pointer to the new packet created by this KP, or OPC_NIL if a recoverable error has occurred.
Example
Excerpt from: example model (models/std/fddi); process model (fddi_mac); state (ENCAP); enter execs.
/* Compose a mac frame from all these elements */
mac_frame_ptr = op_pk_create_fmt ("fddi_mac_fr");
op_pk_nfd_set (mac_frame_ptr, "svc_class", svc_class);
op_pk_nfd_set (mac_frame_ptr, "dest_addr", dest_addr);
op_pk_nfd_set (mac_frame_ptr, "src_addr", my_address);
op_pk_nfd_set (mac_frame_ptr, "info", pdu_ptr);
if (svc_class == FDDI_SVC_ASYNC)
{
op_pk_nfd_set (mac_frame_ptr, "tk_class", req_tk_class);
op_pk_nfd_set (mac_frame_ptr, "pri", req_pri);
}
/* Assign the frame control field... */
op_pk_nfd_set (mac_frame_ptr, "fc", FDDI_FC_FRAME);
/* Enqueue the frame at the tail of the queue. */
op_subq_pk_insert (0, mac_frame_ptr, OPC_QPOS_TAIL);
Details
The new packet is allocated by the Simulation Kernel and enters circulation at the processor or queue running the process model which invoked this KP. The packet is internally formatted according to the specified packet format, so certain fields may be pre-assigned default values. The initial size of the created packet is the sum of the sizes of all set fields; the bulk data size of the packet is independent of the packet format and is set to zero by this KP (bulk data size may be modified using the KP op_pk_bulk_size_set()).
The new packet is issued a unique packet ID, which is simply the next available Packet ID when this KP is invoked. The packet’s creation and stamp times are set to the simulation time when this KP is invoked, and the creation and stamp modules are set to the module running the process which called this KP.
Purpose
Provides a mechanism to obtain a formatted packet with predetermined structure and default contents. Formatted packets are oriented towards communicating specific sets of data, since field data types can’t be changed and new fields can’t be added. The advantages of formatted packets (versus unformatted packets) are that fields can be identified by name, and less information must be specified for the field-setting operation. However, a performance penalty is incurred due to identifying fields by name, since specified field names must be string-compared to packet format field names until a match is found.
Typically, newly created packets are assigned specific contents and forwarded from the creating module using the op_pk_send…() or op_pk_deliver…() series of KPs. The pointer of a created packet may also be assigned to a process model state variable, and stored until a later time when transmission of the packet is required.
Errors
- Program Abort: Allocation of memory failed.
- Program Abort: Segmentation violation. (due to a malformed format_name argument)
- Recoverable Error: Packet format (
<format_name>) is unrecognized. - Recoverable Error: Invalid packet format (
<format_name>): field (<field_name>) is set. Fields of type structure cannot be set at creation. - Recoverable Error: Invalid packet format (
<format_name>): field (<field_name>) is set. Fields of type packet cannot be set at creation.
Reference
- Use the KP op_pk_nfd_set() to assign values to a formatted packet’s fields
- Use the
op_pk_send…()andop_pk_deliver…()KPs to send a packet to another module - Use the KP op_pk_destroy() to deallocate a packet which is no longer of use