Name
prt_api_delete_item
Purpose
Delete/scrap item from tracking region queue.
Description
This function provides a mechanism for deleting or scrapping a single Item from a specific Tracking Region queue. The calling routine receives back a status indicating the success or failure of the request.
Syntax
int prt_api_delete_item ( timestamp, prt_svc_id, group_id,
region_id, region_loc, item_id,
reference_id, item_type_id,
disposition, comment, user_or_svc_id,
retstat)
cor_time_t timestamp;
char prt_svc_id[SERVICE_ID_LEN + 1];
char group_id[PRT_REGION_ID_LEN + 1];
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];
COR_I1 disposition;
char comment[SC_DESCRIPTION_LEN + 1];
char user_or_svc_id[SERVICE_ID_LEN + 1];
COR_STATUS *retstat;
Data Structures
None
Arguments
|
Argument |
Description |
|
|
Input |
|
|
|
Serialized Items Only |
(See SYNTAX for proper order) |
|
|
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) |
|
|
Both |
|
|
|
Timestamp |
The time the item was last moved or modified. The timestamp is used to ensure that, when attempting to delete an item, the item has not changed (or moved) between the time when the time when information was last obtained for that item and the attempt to delete it. (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 item's current timestamp, then the deletion 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. |
|
|
prt_svc_id |
PRT service identifier (optional) |
|
|
group_id |
Identifier of the Tracking Group (optional) |
|
|
region_id |
Identifier of the Tracking Region where the Item is to be deleted from the queue (required for non-serialized items, optional for serialized items) |
|
|
|
Note: For serialized items, at least one of the above three arguments must be specified. |
|
|
region_loc |
Location in the region where the item resides (required). For non-serialized items, a specific region location must be specified. For serialized items, the constant ALL_LOCATIONS may be used. This indicates that the item may reside at any location in the region. |
|
|
item_type_id |
Item type identifier (required for non-serialized items, optional for serialized items) |
|
|
Disposition |
Disposition of item to be deleted. (required) Valid values are: |
|
|
|
SCRAP |
Causes the item to be scrapped. |
|
|
NO_LOCK_CHECK_SCRAP |
Causes the item to be scrapped, overriding region locking status. |
|
|
DELETE |
Causes the item to be deleted. |
|
|
NO_LOCK_CHECK_DELETE |
Causes the item to be deleted, overriding region locking status. |
|
|
Note: It may be necessary to force the delete of the item, regardless of the region's lock status, while using the PRT API functions to delete items in a region. To do this, use the "NO_LOCK_CHECK_" versions of SCRAP and DELETE above. |
|
|
Comment |
Comment to be recorded in PRT history log file (optional) |
|
|
user_or_svc_id |
User or service identifier (optional) |
|
|
Output |
|
|
|
*retstat |
Pointer to COR_STATUS structure |
|
Return Value
Either COR_SUCCESS, COR_WARNING, or COR_FAILURE.
If the function returns COR_WARNING or COR_FAILURE, additional error information can be found in the COR_STATUS structure.
Error Codes
|
PRTC_XREF_NOFIND |
Deleted, but not found in xref table (Warning) |
|
PRTC_ITEM_NOT_FOUND |
Item ID not found (Failure) |
|
PRTC_REF_NOT_FOUND |
Reference ID not found (Failure) |
|
PRTC_BAD_REG_SPEC |
Bad region specified (Failure) |
|
PRTC_BAD_REG_LOC_SPEC |
Bad region location specified (Failure) |
|
PRTC_NO_ITEM_AT_LOC |
Specified item not found specified location (Failure) |
|
PRTC_NO_REG_LOC_SPEC |
Must specify region location to delete non-serialized item (Failure) |
|
PRTC_ITEM_STAMP_TOO_NEW |
An affected item has changed since the last display (Failure) |
|
PRTI_ITEM_TYPE_NULL |
Item type identifier NULL (Warning) |
|
PRTI_ITEM_TYPE_NDEF |
Item type identifier not valid (Warning) |
|
PRTI_NON_SER_ID |
Non-serialized item has item id or reference id (Warning) |
|
PRTI_SVC_ID_NULL |
PRT service identifier NULL (Warning) |
|
PRTI_SVC_ID_NDEF |
PRT service identifier not valid (Warning) |
|
PRTI_GRP_ID_NULL |
Group identifier NULL (Warning) |
|
PRTI_GRP_ID_NDEF |
Group identifier not valid (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_INVALID_REG_LOC_MSG |
Invalid region location (Warning) |
|
PRTI_REG_NOT_IN_GRP |
Region not in group specified (Warning) |
|
PRTI_REG_NOT_IN_SVC |
Region not managed by service specified (Warning) |
|
PRTI_GRP_NOT_IN_SVC |
Group ID inconsistent with service specified (Warning) |
|
PRTI_NO_SVC_IMPLIED |
No service specified (via svc_id/group_id/region_id) (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. |
