prt_api_get_intproc_updates

Name

prt_api_get_intproc_updates

Purpose

Get interested process item/region tracking data updates.

Description

This routine provides a mechanism for an application to receive interested process updates from all data servers which have been specified based on the prt_system argument in the prt_api_init and prt_api_dyn_register_intproc calls. The information received by the interested process includes updates for Serialized and Non-serialized Items as well as region-related updates.

There are currently two types of updates that an interested process may receive from PRT:

• An item has been modified or moved - the manifest constant for this update type is PRT_INTPROC_ITEM_UPDATE. The event_code field in the PRT_ITEM_UPDATE_STRUCT indicates the exact nature of the update.
• The items in a region have been reordered - the manifest constant for this update type is PRT_INTPROC_REGION_UPDATE.

With both types of update structure, the action field contains the same value as the update_type argument returned to the calling program.

The caller allocates storage for both item update and region update structures. When the call returns, update_type will be set to PRT_INTPROC_ITEM_UPDATE if the item update structure has been filled in with item information. If the region update structure has been filled in, update_type will be set to PRT_INTPROC_REGION_UPDATE.

If a Data Server process which the interested process is configured to receive interested process updates from terminates (or some other error occurs) the interested process will be notified by receiving a message with update_type set to PRT_ERROR_RESP. In this case the service id of the associated Data Collector process will be placed in the user_or_svc_id field of the PRT_ITEM_UPDATE_STRUCT structure.

When prt_api_get_intproc_updates is called, it empties the datagram receive buffer of all messages that have arrived since the last call to prt_api_get_intproc_updates (or since the process registered as an interested process) via successive reads, until a read is posted and the event flag remains low. The messages which are read are placed into one of two lists, one containing errors messages, and the other containing valid interested process update messages. If there are any messages in the error message list, these are always returned before the real updates.

Syntax

int prt_api_get_intproc_updates( update_type, item_info,
                                 reg_info, retstat )
COR_U2                    *update_type;
PRT_ITEM_UPDATE_STRUCT    *item_info;
PRT_REGION_UPDATE_STRUCT  *reg_info;
COR_STATUS                *retstat;

Data Structures

typedef struct
{
  char att_name[PRT_ATTRIBUTE_LEN + 1] - item attribute name
  char att_value[PRT_ATTRIBUTE_LEN + 1] - item attribute value
} PRT_ITEM_ATT
typedef struct
{
  long         reg_entry_time;
  COR_I2       event_code;
  COR_U2       modify_bitmask;
  char         region_1_id[PRT_REGION_ID_LEN + 1];
  COR_I2       region_1_loc;
  char         region_2_id[PRT_REGION_ID_LEN + 1];
  COR_I2       region_2_loc;
  COR_I1       item_tracking_type;
  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  int_hold_active;
  char         int_hold_reason[SC_DESCRIPTION_LEN + 1];
  COR_BOOLEAN  ext_hold_active;
  char         group_id[PRT_REGION_ID_LEN + 1];
  COR_I1       num_atts_valid;
  PRT_ITEM_ATT item_att_list[PRT_NUM_ATTRIBUTES];
  char         comment[SC_DESCRIPTION_LEN + 1];
  char         user_or_svc_id[SERVICE_ID_LEN + 1];
  COR_I1       action;
} PRT_ITEM_UPDATE_STRUCT, *PRT_ITEM_UPDATE_STRUCT_PTR;
typedef struct
{
  COR_I1 event_code;
  char   region_id[PRT_REGION_ID_LEN + 1];
  COR_U4 region_status;
  char   comment[SC_DESCRIPTION_LEN + 1];
  char   user_or_svc_id[SERVICE_ID_LEN + 1];
  COR_I2 location;
  COR_I1 action;
} PRT_REGION_UPDATE_STRUCT, *PRT_REGION_UPDATE_STRUCT_PTR;

Notes: See the next chapter for the list of macros that can be used with the modify_bitmask parameter to determine which fields in the PRT_ITEM_UPDATE_STRUCT contain valid data.

The values supplied which identify region location are in the range FIRST (or EXIT), LAST (or ENTRY), and 0, 1, 2...n. '0' means that the region location is not appropriate. 1-n is the region location. FIRST and LAST are first and last to exit, respectively.

In the current implementation of production tracking, region_2_id and region_2_loc are not populated in the item update structure. These elements are reserved for GE Intelligent Platforms use.

Arguments

Return Value

Either COR_SUCCESS, COR_FAILURE or COR_WARNING.

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

If there are no requests pending, the function returns COR_WARNING with the COR_STATUS err_code set to PRTI_NOTHING_PENDING and update_type set to PRT_ERROR_RESP.

Error Codes