op_pk_fd_print_proc_set()
Abstract
Associates a custom print procedure with the specified field of the specified unformatted packet; the field-of-interest is specified by a numeric index.
Syntax
op_pk_fd_print_proc_set (pkptr, field_index, print_proc)
| 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().] |
field_index |
int |
numeric index of the field-of-interest. Can identify any field type except information. [This value should be non-negative; however, no error will occur if it is not. Instead, OPC_COMPCODE_FAILURE will be returned, indicating the specified field is not set.] |
print_proc |
Procedure |
print procedure; see the Details section for more information |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the print procedure was installed successfully; OPC_COMPCODE_FAILURE if an error occurred.
Example
/* Install a print procedure for the 5th field of a particular */
/* unformatted packet. The 5th field is the "address" field. */
/* address_print_proc is defined in the function block as follows: */
/* */
/* void address_print_proc (void *structure_ptr, PrgT_List *dest_lptr) */
/* { */
/* char *char_line; */
/* ReqT_Address *addr_ptr; */
/* addr_ptr = (ReqT_Address *) structure_ptr; */
/* char_line = op_prg_mem_alloc (sizeof (char) * 60); */
/* sprintf (char_line, "subnet: %d", addr_ptr->subnet); */
/* op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); */
/* char_line = op_prg_mem_alloc (sizeof (char) * 60); */
/* sprintf (char_line, "node : %s", addr_ptr->node_name); */
/* op_prg_list_insert (dest_lptr, char_line, OPC_LISTPOS_TAIL); */
/* } */
op_pk_fd_print_proc_set (pkptr, 5, address_print_proc);
Details
When the packet is printed (using the pkprint command in ODB or the op_pk_print() KP), the specified print_proc will be called by the Simulation Kernel to obtain custom text for the specified packet field.
The print_proc must have the following prototype:
void
Pk_Fd_Print_Proc (void *field_value_ptr, PrgT_List *dest_lptr);
The print_proc must add new entries to the PrgT_List *dest_lptr. Use prg_mem_alloc() to allocate strings for addition to the list. The Simulation Kernel deallocates all memory.
The contents of the field are passed in *field_value_ptr. This argument varies by data type:
| Field Data Type | *field_value_ptr Argument |
|---|---|
int32, int64, double, pktid, objid |
address of the value (cast to appropriate type) |
packet |
address of the packet |
structure |
address of the structure |
Purpose
Use this KP to specify a function to be called when a specified field of the specified packet is printed by the ODB pkprint command or by the op_pk_print() KP. The field can be of any type except information. The print proc allows additional custom information about a field to be printed, in addition to the index, name, size, type, and value.
The print proc function can be useful if the field value is coded in some way. For example, if an int32 field contains information represented as a bitmap, the print proc can print a decoded version that makes debugging easier. The print proc also can be used for creating a textual representation of a data structure stored inside a structure type packet field. Such data structures can be complex, so a representation is useful in debugging.
Errors
- Recoverable Error: Contents of packet (
<id>) is a value vector. Packet doesn't allow field operations. - Recoverable Error: Field index
<index>is out-of-range for packet<id>. - Recoverable Error: No field with index (
<index>) in packet (<id>). - 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>).
Reference
- Use the KP op_pk_create() to create a new unformatted packet with the specified bulk data size; the packet does not have any of its fields set.
- Use the KP op_pk_print() to print information (including the contents of packet fields and the values of field properties) about the specified packet to the standard output device.