Name
prt_api_add_item
Purpose
Add item to tracking region queue.
Description
This routine provides a mechanism to add an individual Item at the same location where another Item currently resides. Defined constants are provided as a way of indicating that the item is to be added either at the head or at the tail of the queue. The region location can be specified as FIRST (or also as EXIT) to add the item to the first (head) location in the queue, i.e. this item is being added to a location where one or more other items already currently reside (although no more than one serialized item may reside at a region location at any one time). These items will be the next items to transition out of the queue. LAST (and ENTRY) are provided to add the item to the last location in the region (the last location which currently has one or more items residing in it). These items will be the last items to transition out of the region (of all the items currently in the region).
Syntax
int prt_api_add_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 specified) |
|
reference_id |
Secondary identifier of a Serialized Item (optional if item_id 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 sets this argument to zero 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 provided along with 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 |
|
|
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 add an item, the item(s) currently at the location where the new item is being added have not moved or been modified between the time when information was last obtained for that item(s) and the attempt to add a new item at the same location. (One of the fields in the structure that 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 being added to, then the 'add' 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). |
|
region_loc |
Specific location in the region where the Item is to be added (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_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) |
|
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_ITEM_TYPE_NULL |
Item type identifier NULL (Warning) |
|
PRTI_INVALID_DEST |
Destination region is invalid for item of this type (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
|
|
Application subroutines. |
