Name
prt_api_locate_item
Purpose
Locate serialized item.
Description
This API provides a mechanism for locating a Serialized Item within all configured PRT services, a specific PRT service, a specific Tracking Group or a specific Tracking Region. If the Item is located, the Item Tracking Data is returned to the calling routine with a return status of COR_SUCCESS. If the item was located in more than one tracking region, the first location is returned in the initial call. Successive calls to this routine return the item's additional locations. When the list of locations is complete, the routine returns COR_WARNING with the additional information in the COR_STATUS structure. If the Item was not located the calling routine receives back a status indicating the request failed.
Syntax
int prt_api_locate_item (prt_svc_id, group_id, region_id,
item_id, reference_id, item_data,
more_data, retstat)
char prt_svc_id[SERVICE_ID_LEN + 1];
char group_id[PRT_REGION_ID_LEN + 1];
char region_id[PRT_REGION_ID_LEN + 1];
char item_id[PRT_ITEM_ID_LEN + 1];
char reference_id[PRT_ITEM_ID_LEN + 1];
PRT_ITEM_STRUCT_PTR item_data;
COR_BOOLEAN *more_data;
COR_STATUS *retstat;
Data Structures
typedef struct {
cor_time_t - reg_entry_time
cor_time_t - last_mod_time
char region_id[PRT_REGION_ID_LEN + 1] - identifier of the region
COR_I2 region_loc - specific location in the region
char item_id[PRT_ITEM_ID_LEN + 1] - unique identifier of a
Serialized Item.
char reference_id[PRT_ITEM_ID_LEN + 1] - secondary identifier
of a Serialized Item.
char item_type_id[PRT_ITEM_TYPE_ID_LEN + 1] - item type
identifier.
char parent_item_id[PRT_ITEM_ID_LEN + 1] - pertains only to
Non-serialized Items.
COR_U4 item_status - item status.
COR_BOOLEAN int_hold_active - if TRUE, item held due to
internal hold.
char int_hold_reason[SC_DESCRIPTION_LEN + 1] - Comment specifying
reason for internal
hold.
COR_BOOLEAN ext_hold_active - if TRUE, item held due to
external hold.
char group_id[PRT_REGION_ID_LEN + 1] - identifier of the group
COR_I1 num_atts_valid - Number of attributes in the list
PRT_ITEM_ATT item_att_list[PRT_NUM_ATTRIBUTES] - Item Attributes
pertain to
Serialized
Items.
} PRT_ITEM_STRUCT, *PRT_ITEM_STRUCT_PTR
Arguments
|
Argument |
Description |
|
Input |
|
|
prt_svc_id |
PRT service identifier (optional) |
|
group_id |
Unique identifier of tracking group (optional) |
|
region_id |
Unique identifier of tracking region (optional) |
|
item_id |
Unique identifier of serialized item (optional if reference_id specified) |
|
reference_id |
Secondary identifier of serialized item (optional if item_id specified) |
|
more_data |
If this flag is set to true by the caller, the function attempts to return an item found by a previous call to this function. If this flag is set to FALSE, any items found by a previous call to this function are deleted and new request(s) are made to the specified service(s). |
|
Output |
|
|
PRT_ITEM_STRUCT_PTR item_data |
Serialized Item Tracking Data |
|
more_data |
If only a single item was found, this flag is set to FALSE. If more than one item was found, this flag is set to TRUE. |
|
*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
|
PRTS_NO_GLOBAL_XREF |
No XREF global section available (Warning) |
|
PRTS_REGION_NOT_DEFINED |
Region not configured (Warning) |
|
PRTS_NO_GLOBAL_REGION |
No global section available for Region (Warning) |
|
PRTI_BAD_POINTER |
Pointer to data structure is NULL (Warning) |
|
PRTI_NO_MORE_ITEMS |
No more items available (Warning) |
|
PRTI_SVC_ID_NULL |
PRT service identifier NULL (Warning) |
|
PRTI_SVC_ID_NDEF |
PRT service identifier not valid (Warning) |
|
PRTI_REG_ID_NULL |
Region identifier NULL (Warning) |
|
PRTI_REG_ID_NDEF |
Region identifier not valid (Warning) |
|
PRTI_GRP_ID_NULL |
Group identifier NULL (Warning) |
|
PRTI_GRP_ID_NDEF |
Group identifier not valid (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_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_UNEXPECTED_SEG |
Unexpected segment type (Warning) |
|
PRTI_ITEM_NOT_FOUND_INC_SRCH |
Item not found: some service(s) down (Warning) |
|
PRTI_ITEM_NOT_FOUND |
Item not found (Warning) |
|
PRTI_WRITE_PORT_ERR |
Error in ipc_write_port (Warn/Fail) |
|
PRTI_MF_INIT_ERR |
Error initializing segment (Failure) |
|
PRTI_CRESEG_ERR |
Error creating segment (Failure) |
|
PRTI_BAD_MSG |
Error in segment (Failure) |
|
PRTI_BAD_SERVER_RESPONSE |
PRT Data Server returned bad/error response (Failure) |
|
PRTI_UNKNOWN_RESPONDER |
Response received from unknown service (Failure) |
|
|
Application subroutines. |
