prt_api_insert

Name

prt_api_insert_item

Purpose

Insert item into tracking region queue.

Description

This routine provides a mechanism to insert an Item into the Tracking Region queue. If an Item is to be inserted into the queue at a particular location (other than at the head or tail of the queue), the region location of the item to be inserted ahead of is specified, i.e. specifying region_loc = 1, is equivalent to specifying region_loc = FIRST. Defined constants are provided as a way of indicating that the item is to be inserted either at the head or at the tail of the queue. The region location can be specified as FIRST (or also as EXIT) to insert the item as the first (head) item in the queue, i.e. this item will be the next item to transition out of the queue. LAST (and ENTRY) are provided to insert the item as the last item at the tail of the queue, BEHIND all other items.

Syntax

int prt_api_insert_item ( timestamp, ext_proc_flag, region_id,

region_loc, item_id, reference_id,

item_type_id, parent_item_id,

item_status, ext_hold_active,

group_id, int_hold_active,

int_hold_reason, num_atts_valid,

item_att_list, comment,

user_or_svc_id, retstat )

cor_time_t timestamp;

COR_BOOLEAN ext_proc_flag;

char region_id[PRT_REGION_ID_LEN + 1];

COR_I2 region_loc;

char item_id[PRT_ITEM_ID_LEN + 1];

char reference_id[PRT_ITEM_ID_LEN + 1];

char item_type_id[PRT_ITEM_TYPE_ID_LEN + 1];

char parent_item_id[PRT_ITEM_ID_LEN + 1];

COR_U4 item_status;

COR_BOOLEAN ext_hold_active;

char group_id[PRT_REGION_ID_LEN + 1];

COR_BOOLEAN int_hold_active;

char *int_hold_reason;

COR_I1 num_atts_valid;

PRT_ITEM_ATT *item_att_list;

char comment[SC_DESCRIPTION_LEN + 1];

char user_or_svc_id[SERVICE_ID_LEN + 1];

COR_STATUS *retstat;

Data Structures

See Static Information Requirements

Arguments

Argument	Description
Input
Serialized Items: Only
ext_proc_flag	External process flag; if TRUE, get all information from external process. (required)
item_id	Unique identifier of a Serialized Item (optional if reference_id is specified)
reference_id	Secondary identifier of a Serialized Item (optional if item_id is specified)
ext_hold_active	If TRUE, item held due to external hold. (required)
group_id	Group identifier providing reason for hold (required if ext_hold_active = TRUE).
num_atts_valid	Number of item attributes valid; this specifies the number of array elements in the item attribute list that contain valid data. If item_att_list is a NULL pointer, the function sends a zero to the Data Collector for this argument, regardless of what was actually passed. (required)
item_att_list	Item attribute list. This argument is the pointer to an array of PRT_NUM_ATTRIBUTES elements. If the pointer is NULL, this clearly indicates that no item attributes are being provide for the item being added. If the pointer is non-NULL, however, it must point to an array of exactly PRT_NUM_ATTRIBUTES elements. The num_atts_valid argument indicates how many of these elements contain valid data. (optional)
Non-Serialized Items Only
parent_item_id	Associated serialized item identifier (optional).
Both
Timestamp	The time the item was last moved or modified. The timestamp is used to ensure that, when attempting to insert an item, the item(s) currently at the location where the new item is to be inserted in front of have not moved or been modified between the time when information was last obtained for that item(s) and the attempt to insert the new item in front of it them). (One of the fields in the structure which returns data on an item is the last_mod_time field, which indicates the time at which the item was last moved or modified.) If the timestamp argument provided to this function is older than the timestamp associated with the item(s) at the location where the new item is to be inserted in front of, then the 'insert' function is not performed and a warning returned. If the timestamp argument passed to this function is zero, the operation is performed without any timestamp checking.
region_id	Region where the item is to be added to the queue (required).
rregion_loc	Specific location in the region where the Item is to be added (required argument). Specified as FIRST (EXIT), LAST (ENTRY), or a number from 1 to n, where n is the number of items in the queue. (required)
item_type_id	Item type identifier (required).
item_status	Item status (required).
int_hold_active	If TRUE, item held due to internal hold. (required)
int_hold_reason	Comment specifying reason for internal hold (required if int_hold_active = TRUE).
Comment	Comment to be recorded in PRT history log file. (optional)
user_or_svc_id	User or service identifier. This is used for logging purposes and is optional. If this pointer is NULL, the host process id is used. (optional)
Output
*retstat	Pointer to COR_STATUS structure

Return Value

Either COR_SUCCESS or COR_FAILURE.

If the function returns COR_FAILURE additional error information can be found in the COR_STATUS structure.

Error Codes

PRTC_NON_SER_ID	Non-serialized item has item or ref. id (Failure)
PRTC_SER_NO_ID	Serialized item missing both item & ref. id (Failure)
PRTC_UNKNOWN_REGION	Unknown REGION specified (Failure)
PRTC_BAD_REG_LOC_SPEC	Bad region location specified (Failure)
PRTC_INS_IN_OCC_NON_NORMAL	Attempt to Insert in occupied COMBINE/DISPERSE region (Failure)
PRTC_ITEM_STAMP_TOO_NEW	An affected item has changed since the last display (Failure)
PRTC_ADD_LOC_TOO_BIG	Cannot add item to unoccupied location- inserting (Warning)
PRTC_ADD_MULTIPLE_SERIAL	Cannot have two serialized items at one location (Warning)
PRTC_NO_DETAINMENT_CFG	No detainment region configured for (Warning)
PRTI_ITEM_TYPE_NULL	Item type identifier NULL (Warning)
PRTI_ITEM_TYPE_NDEF	Item type identifier not valid (Warning)
PRTI_NS_EXT_PROC_INVALID	ext_proc_flag set for non-serialized item (Warning)
PRTI_NON_SER_ID	Non-serialized item has item id or reference id (Warning)
PRTI_SER_NO_ID	Serialized item missing both item id and reference id (Warning)
PRTI_SER_PARENT	Parent ID specified for serialized item (Warning)
PRTI_GRP_ID_NULL	Group identifier NULL (Warning)
PRTI_GRP_ID_NDEF	Group identifier not valid (Warning)
PRTI_EXT_HOLD_NON_SER	External hold specified for non-serialized item (Warning)
PRTI_INT_HOLD_NO_REASON	Internal hold specified without reason (Warning)
PRTI_NON_SER_ATTS	Non-serialized item has attribute(s) (Warning)
PRTI_NUM_ATTS_INVALID	Invalid number of item attributes specified (Warning)
PRTI_REG_ID_NULL	Region identifier NULL (Warning)
PRTI_REG_ID_NDEF	Region identifier not valid (Warning)
PRTI_INVALID_REG_LOC	Invalid region location (Warning)
PRTI_MF_INIT_ERR	Error initializing segment (Failure)
PRTI_CRESEG_ERR	Error creating segment (Failure)

Plus all error codes returnable by prt_api_send_cmd.

More information

Application subroutines.