prt_api_modify_item_all

Name

prt_api_modify_item_all

Purpose

Modify item tracking data (all).

Description

This routine provides a mechanism to modify all information fields associated with an item, both those modifiable by the prt_api_modify_item function and (for a serialized item) the item's attributes, also. For non-serialized items, this function does nothing more than the prt_api_modify_item function. The calling routine receives back a status indicating the success or failure of the request.

Syntax

int prt_api_modify_item_all( timestamp, modify_bitmask,

                             status_bitmask, region_id,

                             region_loc, item_id, reference_id,

                             item_type_id, parent_item_id,

                             item_status, ext_hold_active,

                             group_id, int_hold_active,

                             int_hold_reason, num_atts_valid,

                             item_att_list, comment,

                             user_or_svc_id, retstat)

cor_time_t        timestamp;

COR_U2        modify_bitmask;

COR_U4        status_bitmask;

char          region_id[PRT_REGION_ID_LEN + 1];

COR_I2        region_loc;

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   ext_hold_active;

char          group_id[PRT_REGION_ID_LEN + 1];

COR_BOOLEAN   int_hold_active;

char          int_hold_reason[SC_DESCRIPTION_LEN + 1];

COR_I1        num_atts_valid;

PRT_ITEM_ATT  *item_att_list;

char          comment[SC_DESCRIPTION_LEN + 1];

char          user_or_svc_id[SERVICE_ID_LEN + 1];

COR_STATUS    *retstat;

Data Structures

None

Input (See SYNTAX for proper order)

Arguments

Argument

Description

Serialized Items Only

 

item_id

Unique identifier of a Serialized Item (optional if reference id specified)

reference_id

Secondary identifier of a Serialized Item (optional if item id specified).

ext_hold_active

If TRUE, item held due to external hold (optional)

group_id

Group identifier providing reason for hold (required if ext_hold_active = TRUE)

num_atts_valid

Number of item attributes valid; this specifies the number of array elements in the item attribute list that contain valid data.

item_att_list

Item Attributes pertain to Serialized Items.

Non-Serialized Items Only

 

parent_item_id

Item ID of associated serialized Item (optional) 

Both

 

timestamp

The time the item was last moved or modified. The timestamp is used to ensure that, when attempting to modify an item, the item has not changed (or moved) between the time when information was last obtained for that item and the attempt to modify it. (One of the fields in the structure which 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 timestamp associated with the item at the time of the attempted modification, then the modification 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.

modify_bitmask

Indicates fields that have been modified (required). If a bit in the bitmask is set, the corresponding argument provided to this function is required. If a bit is clear, the corresponding argument is not accessed in any way. The following fields are potentially modifiable and have a corresponding bit in the modify_bitmask.

 

Field Name

Bit Name

 

item_status

ITEM_STATUS_BIT

 

status_bitmask

ITEM_STATUS_BIT

 

item_id

ITEM_ID_MOD_BIT

 

reference_id

REFERENCE_ID_MOD_BIT

 

item_type_id

ITEM_TYPE_ID_BIT

 

parent_item_id

PARENT_ITEM_ID_BIT

 

ext_hold_active

EXT_HOLD_BIT

 

group_id

EXT_HOLD_BIT

 

int_hold_active

INT_HOLD_BIT

 

int_hold_reason

INT_HOLD_BIT

 

num_atts_valid

ATTS_VALID_BIT

 

item_att_list

ATTS_VALID_BIT

 

Macros can be used to set the various bits in modify_bitmask to indicate which fields are being modified.

Note that the item_id and reference_id, if both are specified, are used to find the item unless either the ITEM_ID_MOD_BIT or REFERENCE_ID_MOD_BIT is set (both cannot be set). If neither is set, the item you are looking to modify will only be found if both the item_id and the reference_id you supply match that of an item already in the production tracking system. The item_ids need not match, however, if the ITEM_ID_MOD_BIT is set, and similarly, the reference_ids need not match if the REFERENCE_ID_MOD_BIT is set.

status_bitmask

Indicates fields in item status that have been modified (optional)

region_id

Region where item last resided (required)

region_loc

Location in the region where the item resides (required) For non-serialized items, a specific region location must be specified. For serialized items, the constant ALL_LOCATIONS may be used. This indicates that the item may reside at any location in the region.

item_type_id

Item type identifier (required for non-serialized item, optional for serialized items)

item_status

Item status (optional)

comment

Comment to be recorded in PRT history log file. (optional)

user_or_svc_id

User or service identifier (optional)

int_hold_active

If TRUE, item held due to internal hold (optional)

int_hold_reason

Comment specifying reason for internal hold. (required for activate, does not apply to deactivate).

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_INVALID_ITEM_TYPE

Invalid item type specified (Warning)

PRTC_CANT_MATCH_BOTH

Item/XREF entry mismatch (Warning)

PRTC_ITEM_NOT_FOUND

Item ID not found (Warning)

PRTC_REF_NOT_FOUND

Reference ID not found (Warning)

PRTC_BAD_REG_SPEC

Bad region specified (Warning)

PRTC_BAD_REG_LOC_SPEC

Bad region location specified (Warning)

PRTC_ITEM_STAMP_TOO_NEW

An affected item has changed since the last display (Warning)

PRTC_NO_ITEM_AT_LOC

Specified item not found specified location (Warning)

PRTI_CANT_MOD_ITEM_REF_IDS

Can't modify both item & ref. ids (Warning)

PRTI_CANT_MOD_ITEM_WOUT_REF

Must specify ref. id to modify item id (Warning)

PRTI_ITEM_TYPE_NULL

Item type identifier NULL (Warning)

PRTI_ITEM_TYPE_NDEF

Item type 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_GRP_ID_NULL

Group identifier NULL (Warning)

PRTI_GRP_ID_NDEF

Group identifier not valid (Warning)

PRTI_EXT_HOLD_NON_SER

External hold specified for non-serialized item (Warning)

PRTI_INT_HOLD_NO_REASON

Internal hold specified without reason (Warning)

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_ITEM_TYPE_NULL

Item type identifier NULL (Warning)

PRTI_ITEM_TYPE_NDEF

Item type identifier not valid (Warning)

PRTI_SER_PARENT

Parent ID specified for serialized item (Warning)

PRTI_NUM_ATTS_INVALID

Invalid number of item attributes specified (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.