prt_api_locate_item
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) |