prt_api_req_regionlist

Name

prt_api_req_regionlist

Purpose

Request list of tracking region data.

Description

This routine provides a mechanism to request Tracking Region Data for one or more Tracking Regions in a Tracking Region Group residing within all configured PRT services, a specific PRT service, a specific Tracking Group or a specific Tracking Region. If the request is a success the calling routine will receive back a count of the number of Tracking Regions returned to the region list. If the request fails, the calling routine will receive back status information on the reason for the failure.

Syntax

prt_api_req_regionlist (prt_svc_id, group_id, region_id,

                        item_count, 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];

COR_I4      *item_count;

COR_STATUS  *retstat;

Data Structures

None

Arguments

Argument

Description

Input

 

prt_svc_id

PRT service identifier (optional, but required if no other arguments specified)

group_id

Tracking group identifier (optional, but required if no other arguments specified)

region_id

Tracking region identifier (optional, but required if no other arguments specified)

Note: At least one of the above three arguments must be specified. If not, all services will be queried. It is possible that a list of 'items' will be collected, but not all services will have responded (because one or more of them were down). Thus the user has a list of valid responses, but may not have all the 'items' that should have been returned. In this case, the function will return COR_WARNING with an err_code of PRTI_NOT_ALL_SVCS_RESPONDED. The function returns, through an argument passed, the number of 'items' actually received. This argument will show how many valid 'items' were received.

Output

 

*item_count

Count of regions returned to schema

*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_REGION_NOT_DEFINED

Region not configured (Warning)

PRTS_GROUP_NOT_DEFINED

Group not configured (Warning)

PRTS_NO_REGIONS_MAPPED

No regions attempted were mapped (Warning)

PRTS_NO_INFO

No information available due to unknown reason (Warning)

PRTS_NO_GLOBAL_REGION

No global section available for Region (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_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_TYPE

Unexpected segment type from PRT_DS (Warning)

PRTI_PARTNER_DEAD

Partner dead (Warning)

PRTI_EXTRA_SEGS

Ignored extra segments after STATUS_SEG or END_SEG (Warning)

PRTI_NOT_ALL_SVCS_RESPONDED

Not all services responded (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_READ_PORT_ERR

Error in ipc_read_port (Failure)

More information

Application subroutines.