prt_api_delete_items_at_loc

Name

prt_api_delete_items_at_loc

Purpose

Delete/scrap items from tracking region queue location.

Description

This function lets users delete or scrap all Items at a location in 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_items_at_loc (timestamp, region_id,

                                 region_loc, disposition,

                                 comment, user_or_svc_id,

                                 retstat)

cor_time_t      timestamp;

char        region_id[PRT_REGION_ID_LEN + 1];

COR_I2      region_loc;

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

(See SYNTAX for proper order)

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 that 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.

region_id

Identifier of the Tracking Region where the Items are to be deleted from the queue

 

Note: For serialized items, at least one of the above three arguments must be specified.

region_loc

Location in the region where the items reside (required)

Disposition

Disposition of item to be deleted. Valid (required) 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 deletion 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_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_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_NO_SVC_IMPLIED

No service specified (via 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.

More information

Application subroutines.