op_pk_fd_set()
Abstract
Assigns the type and size of an information field in the specified packet; the field-of-interest is specified by a numeric index.
Note: This KP format is used for information fields only. For other field types, use an alternate format (see the Purpose section for details).
Syntax
op_pk_fd_set (pkptr, fd_index, type, size)
| 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(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
fd_index |
int |
numeric index of the field-of-interest [This value must be non-negative, or an error will occur.] |
type |
int |
type to be assigned to the field [This is an numeric code which specifies the field type (see Table 55 “Field Type Symbolic Constants“ on page 14); the only acceptable value for this KP format is OPC_FIELD_TYPE_INFO.] |
size |
int, double, or OpT_Int64 |
modeled size (in bits) of the field contents, or OPC_FIELD_SIZE_UNCHANGED [If this argument is of type double or OpT_Int64, you must augment the type argument. See the Details section for more information.] |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the field could be set; OPC_COMPCODE_FAILURE otherwise.
Example
/* create an unformatted packet */
uf_pkptr = op_pk_create (0);
/* assign an integer code to the packet */
op_pk_fd_set (uf_pkptr, FD_TYPE, OPC_FIELD_TYPE_INTEGER, DATA_XFER, 16);
/* assign an information field to the packet */
op_pk_fd_set (uf_pkptr, FD_DATA, OPC_FIELD_TYPE_INFO, 1500);
/* send the defined packet out of the processor */
op_pk_send (uf_pkptr, OUTSTRM);
Details
For the information field type, only the size of the field needs to be specified, because the actual values of the data modeled by the field are irrelevant to the simulation. Getting the value of an information field via the KP op_pk_fd_get() does not have a valid purpose, but instead of causing an error, the string “unspecified” is copied into the passed value pointer. If the specified size of the field is different from its previous size, the total size of the packet will change proportionally.
If size is of type double, you must augment the type argument by adding an OR operator (|) and the flag OPC_FIELD_SIZE_IS_DOUBLE; otherwise the underlying code will interpret the size argument as an integer value. If the size argument is of type OpT_Int64, you must augment the type argument by adding an OR operator (|) and the OPC_FIELD_SIZE_IS_INT64 flag. For example,
op_pk_fd_set (pkptr, 0, OPC_FIELD_TYPE_INFO, 16) |
uses a size argument of type integer (the value 16 as an integer (four-byte) argument) |
op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_INFO|OPC_FIELD_SIZE_IS_DOUBLE, 16.0) |
uses a size argument of type double (the value 16.0 as a double (eight-byte) argument) |
OpT_Int64 the_size = 16;op_pk_fd_set (pkptr, 0,OPC_FIELD_TYPE_INFO|OPC_FIELD_SIZE_IS_INT64,the_size) |
uses a size argument of type 64-bit integer (the value 16 as a 64-bit integer (eight-byte) argument) |
If size is different from the previous size of the field, the total size of the packet will change accordingly. If size is OPC_FIELD_SIZE_UNCHANGED, the size of the field will remain as defined in the packet.
Note: OPC_FIELD_SIZE_UNCHANGED is a 64-bit value. When it is used, the type argument must be augmented for an OpT_Int64 argument, as follows:
op_pk_fd_set (pkptr, field_index,
OPC_FIELD_TYPE_INFO|OPC_FIELD_SIZE_IS_INT64,
OPC_FIELD_SIZE_UNCHANGED)
Purpose
Provides a mechanism to set the value of an information field within a packet. This KP is usually applied to unformatted packets, but it can be applied to formatted packets as well (formatted packet field names can be converted into numeric indices using the KPs op_pk_name_to_index() and op_pk_nfd_name_to_index()).
This format of op_pk_fd_set() supports only information field types, because no field value is specified. Alternate formats of this KP support integer, double, or packet field types (op_pk_fd_set()) and structure field types (op_pk_fd_set()).
A data-type-specific version of this KP exists. The alternate KP is more efficient than this variable argument version. In addition, it allows the compiler to catch argument errors that are missed with this KP. For details, refer to op_pk_fd_set_info().
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Program Abort: Allocation of memory failed.
- Recoverable Error: Field type (
<type>) is unrecognized. - Recoverable Error: Field size (
<size>) is out-of-range. - Recoverable Error: Field index (
<fd_index>) is out-of-range for packet (<pk_id>).
Reference
- Use the alternate formats of this KP to assign values to integer, double, packet, or structure fields of a packet
- Use one of the variants of the KP op_pk_nfd_set() to assign a field’s value in a formatted packet, specifying the field by name.
- Use one of the variants of the KP op_pk_fd_strip() to unset a field within a packet, subtracting out its contribution to total packet size