op_pk_nfd_set()
DEPRECATED—Use explicitly typed op_pk_nfd_set_<type>()
Abstract
Assigns the value of an integer, double, or packet field in the specified packet; the field-of-interest is specified by name.
Note: This format is used for integer, double, and packet fields only. For other field types, use an alternate format (see the Purpose section for details).
Syntax
op_pk_nfd_set (pkptr, fd_name, value)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest [A pointer to a packet can be obtained from many KPs, including op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
fd_name |
char* |
name of the field-of-interest [This name must be a defined field within the packet's format, or an error will occur.] |
value |
void* |
value to be assigned to the field [This value can be an integer, a double, or a packet pointer.] |
Return Type
Compcode
Completion code indicating if the specified field was successfully assigned a new value. The OPC_COMPCODE_FAILURE constant will be returned if a recoverable error occurs.
Example
/* create a formatted packet */
f_pkptr = op_pk_create_fmt ("example_pkt");
/* assign integer fields in the packet */
op_pk_nfd_set (f_pkptr, "fd_int_1", 2511);
int_value = 5 * 200;
op_pk_nfd_set (f_pkptr, "fd_int_2", int_value);
/* assign double fields in the packet */
op_pk_nfd_set (f_pkptr, "fd_double_1", 3.1415);
db_value = 33.5 / 27.1;
op_pk_nfd_set (f_pkptr, "fd_double_2", db_value);
/* encapsulate a higher-level packet in the packet */
enc_pkptr = op_pk_create (24);
op_pk_nfd_set (f_pkptr, "fd_packet", enc_pkptr);
/* send the defined packet out of the processor */
op_pk_send (f_pkptr, OUTSTRM);
Details
The value argument can accept either an integer, a double, or a packet pointer value. The logic within this KP determines the type of the passed argument based on the packet's internal format, and alters its field assignment technique accordingly. If the specified field has not been set before, the size of the new field is also determined from the packet's format, and it is added to the total size of the packet.
For the integer, double, and packet field types, the value of the field needs to be specified. Packets which are assigned to fields are "encapsulated" within the packet being operated on by this KP, and the invoking process loses ownership of the encapsulated packet. These encapsulated packets are not accessible until they are decapsulated by op_pk_fd_get() (or optionally op_pk_nfd_get(), if the packet is formatted).
Fields that are of type packet use a special technique for dynamic size determination. When these types of fields are defined in a packet format using the Packet Format Editor, field size is specified in one of the data table columns. If the specified size of the field is set to "inherited", the size of the field will track the size of the encapsulated packet, thus accurately modeling the aggregate packet size. If the size of such a field is specified in the table as zero or positive, it overrides the size of any encapsulated packet, thus supporting the modeling of data compression.
Purpose
Provides a mechanism to set the value of a field within a packet. Because the packet is formatted, only the value of the field needs to be specified; the type and size of the field (which would need to be specified to the unformatted version of this KP, op_pk_fd_set()), are automatically obtained from the format.
Note: This KP should be applied only to formatted packets; otherwise an error will occur.
This format of op_pk_nfd_set() supports integer, double, and packet field types. Alternate formats of this KP support information field types (op_pk_nfd_set()) and structure field types (op_pk_nfd_set()).
Data-type-specific versions of this KP exist. These alternate KPs are more efficient than this variable argument version. In addition, they allow the compiler to catch argument errors that are missed with this KP. For details, refer to op_pk_nfd_set_int32(), op_pk_nfd_set_int64(), op_pk_nfd_set_dbl(), op_pk_nfd_set_objid(), op_pk_nfd_set_pkid(), and op_pk_nfd_set_pkt().
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or fd_name argument)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Recoverable Error: No field named (
<fd_name>) in packet (<pk_id>).
Reference
- Use the alternate formats of this KP to assign values to information or structure fields of a packet
- Use one of the variants of the KP op_pk_fd_set() to assign the value of a field in a packet, specifying the field by numeric index
- Use one of the variants of the KP op_pk_nfd_get() to obtain the value of a field in a packet
- Use the KP op_pk_nfd_strip() to unset a field within a packet, subtracting out its contribution to total packet size