Main Page | Modules | Files | Functions | Code Elements | Data Structures | Deprecated

Product Structure

Detailed Description

The Product Structure (PS) ITK module manages the creation, manipulation, and storage of product structure data within Teamcenter.

Product structure in Teamcenter is represented by assembly Items containing links to component Items which make up the assembly. The structure of Items is represented in BOMView objects. The links to component Items are known as occurrences.

The PS ITK module covers the creation of BOMViews and BOMView Revisions for Items and Item Revisions, the creation and modification of occurrences to reference the component parts of an assembly and the attachment of structure related attributes to occurrences.

Common Return Values

Return Value Description
CFM_invalid_tag Tag is not a valid config_rule.
POM_attr_null_forbidden type_name is NULL or zero length.
POM_inst_referenced BOMView or one of its Revisions is already referenced.
POM_inst_violates_unique view_type or note_type of the same name already exists in the database.
POM_invalid_string String is NULL, zero length or too long.
PS_no_seq_no No sequence number has been set for this occurrence.
PS_bvr_is_precise For a precise parent BOMView Revision, child_item must be the tag of a specific Item Revision, not an Item.
PS_cant_delete_preferred child_item is the preferred substitute.
PS_cant_unattach_bvr Revising an unshared BOMView Revision is not allowed, as it would be left unattached.
PS_cyclic_structure You cannot create an occurrence of the same Item whose revision contains the parent BOMView Revision. This would produce a structure which references itself.
PS_duplicate The combination of view_type and parent_item must be unique.
PS_insufficient_privilege User must have Teamcenter Engineering system administrator privileges.
PS_invalid_attribute No attribute of this name is registered with the occurrence class.
PS_invalid_bom_view Tag is not a valid BOMView.
PS_invalid_bvr Tag is not a valid BOMView Revision.
PS_invalid_child_item Tag is not an Item or Item Revision.
PS_invalid_class Not a valid PS class identifier.
PS_invalid_item Tag is not a valid Item.
PS_invalid_note_type Tag is not a valid note_type.
PS_invalid_occurrence No such occurrence in this parent BOMView Revision.
PS_invalid_occurrence_flag Not a valid occurrence flag token.
PS_invalid_ref_class The client data is not an instance of the POM class specified in the definition of this attribute.
PS_invalid_value The new index is less than zero or greater than the number of occurrences of the parent BOMView Revision minus one.
PS_invalid_view_type Tag is not a valid view_type.
PS_no_default_view_type View type was NULLTAG but no default view_type defined.
PS_no_note_of_this_type This occurrence does not have a note of this type.
PS_no_such_substitute child_item is not a substitute of this occurrence.
PS_no_transform This occurrence has no transform set.
PS_not_found No such view_type.
PS_has_old_transform_only Occurrence only has old format transform.
PS_could_not_convert_transform Could not convert old format transform to PLMXML format.
PS_no_legacy_transform_factor There is no legacy transform factor on the BVR.
PS_not_a_plmxml_transform There is no PLMXML transform on this occurrence.
PS_two_transforms This occurrence has a PLMXML transform and an old transform; this is an invalid situation.
PS_allow_plmxml_pref_invalid The preference PS_allow_plmxml_transforms_with_no_legacy_factor is invalid or does not exist " "(should take values Yes or No).
PS_transform_format_pref_invalidThe preference PS_assume_old_transform_format must only take values In_Legacy_Format, " ", Written_By_UG or Unknown (case sensitive).
PS_transform_units_pref_invalid The preference PS_assume_legacy_transform_units must only take values Inches, Millimeters, " " or Unknown

Modules

PS View Type Functions

PS Occurrence Types

Common Return Values:

PS_duplicate - An occurrence type by the same name already exists in the database.
PS_invalid_occ_type - Invalid occurrence type tag specified.

PS BOM View Functions

BOM View Revision Functions

PS Occurrence Sequencing

PS Occurrence Functions

PS Substitutes Functions

PS Variants

The variant data is a pointer to a variant_expression block (see bom.h for routines to manipulate it) An occurrence may have either variant data or substitutes, but not both. It is an error to attempt to set the one if the occurrence currently has the other defined

PS Object Functions

PS Note Type Functions

PS Where Used Functions

PS Unified Occurrence Effecivity Functions

Functions

Function Documentation

PS_API int PS_add_optional_item ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
tag_t  opt_item,
tag_t  opt_rev,
tag_t  opt_view,
tag_t *  optlist 
)

Parameters:
parent  (I)
occurrence  (I)
child_item  (I)
opt_item  (I)
opt_rev  (I)
opt_view  (I)
optlist  (O)

PS_API int PS_add_predecessor ( tag_t  bvr,
tag_t  occ,
tag_t  predecessor 
)

This function is used to add a predecessor directly to the occurrence.

Restrictions:

Both occ and predecessor share the same parent bvr.

Return Values:

PS_self_predecessor Cannot define self as predecessor.
PS_pred_rel_exists This predecessor relationship is already defined.
PS_cyclic_pred_structureCircular precedence relationship defined.

Parameters:
bvr  (I) Tag of the parent bvr
occ  (I) Tag of the successor occurrence thread
predecessor  (I) Tag of the predecessor occurrence thread

PS_API int PS_add_related_substitutes ( int  n_items,
tag_t *  occurrences,
tag_t *  sub_items,
tag_t *  substitute_set 
)

Parameters:
n_items  (I) number of substitute items
occurrences  (I) Array of occurrence
sub_items  (I) Array of substitute items
substitute_set  (O) Array of related substitutes

PS_API int PS_add_substitute ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
tag_t  child_bom_view 
)

Adds the specified Item or Item Revision / BOMView pair as a substitute child for the specified occurrence. If the occurrence has no substitutes already, the existing child becomes the preferred substitute.

In future, the BOMView will be used to distinguish between multiple views of the same Item, but currently NULLTAG can be used.

Parameters:
parent  (I) Tag of the parent BOMView Revision
occurrence  (I) Tag of the occurrence
child_item  (I) Tag of the child Item or Item Revision
child_bom_view  (I) Tag of the child BOMView

PS_API int PS_ask_bom_view_of_bvr ( tag_t  bvr,
tag_t *  bom_view 
)

Returns the tag of the BOMView to which this is a revision.

Parameters:
bvr  (I) Tag of the BOMView Revision
bom_view  (O) Returns tag of the BOMView of which bvr is revision

PS_API int PS_ask_bom_view_type ( tag_t  bom_view,
tag_t *  view_type 
)

Returns the view type of a BOMView.

Parameters:
bom_view  (I) Tag of the BOMView
view_type  (O) Tag of the view type of BOMView

PS_API int PS_ask_client_data ( tag_t  instance,
const char *  attr_name,
tag_t *  client_data 
)

Returns the client data attributed to the instance for the specified attribute name. The client data will be a tag of a POM object.

Note:
This function is used to inquire about client data of all PS classes (except occurrence). Occurrences are referenced using a parent BOMView Revision, thus occurrence pairing a separate interface function PS_ask_occurrence_client_data is provided to inquire about client data of an occurrence.
Parameters:
instance  (I) Tag of an instance of a PS class
attr_name  (I) Name of the attribute to be retrieved
client_data  (O) Returns the tag of a POM object. If no client data is attached to this attribute of the occurrence, NULLTAG is returned.

PS_API int PS_ask_default_view_type ( tag_t *  view_type  ) 

Looks at site/group/role/user/local preferences as appropriate to find the default view type defined for the current user. Returns NULLTAG if a default view type is not defined.

Parameters:
view_type  (O) User's default view type

PS_API int PS_ask_has_substitutes ( tag_t  parent,
tag_t  occurrence,
logical *  has_substitutes 
)

Returns true if the specified occurrence has two or more substitute children.

Parameters:
parent  (I) Tag of the parent BOMView Revision
occurrence  (I) Tag of the occurrence
has_substitutes  (O) Whether the occurrence has substitutes

PS_API int PS_ask_has_variant_data ( tag_t  parent,
tag_t  occurrence,
logical *  has_variant_data 
)

Returns a logical value to say whether this occurrence holds variant data (i.e., is subject to a variant condition).

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
has_variant_data  (O) Returns true if the occurrence holds variant data, false otherwise.

PS_API int PS_ask_is_bvr_precise ( tag_t  bvr,
logical *  is_precise 
)

If "precise" a BOMView Revision can only contain precise occurrences of child Item Revisions. Otherwise it is "imprecise" and can only contain imprecise occurrences of child Items.

Parameters:
bvr  (I) Tag of the BOMView Revision
is_precise  (O) True if the BOMView Revision is precise, false if it is imprecise.

PS_API int PS_ask_is_bvr_shared ( tag_t  bvr,
logical *  is_shared 
)

Answers true if this BOMView Revision is referenced by more than one Item Revision.

Note:
If this BOMView Revision is referenced by more than one Item Revision, then you will not be allowed to modify its structure. You must first revise the BOMView Revision in the Item Revision whose structure you want to change.

From V3.4, BOMView Revisions are automatically revised when ItemRevisions are copied. This means that new BOMView Revisions will only ever be referenced by a single Item Revision, and only pre-V3.4 legacy data will contain shared BOMView Revisions.

Parameters:
bvr  (I) Tag of the BOMView Revision
is_shared  (O) True if this BOMView Revision is referenced by more than one Item Revision

PS_API int PS_ask_item_of_bom_view ( tag_t  bom_view,
tag_t *  item 
)

Returns the tag of the item of which the BOMView is an attribute.

Parameters:
bom_view  (I) Tag of the BOMView
item  (O) Returns the tag of the item to which the BOMView is an attribute

PS_API int PS_ask_latest_option_rev ( tag_t  variant,
tag_t *  variantRev 
)

PS_API int PS_ask_legacy_transform_factor ( tag_t  bvr,
double *  legacy_factor 
)

An ITK routine for asking and setting the unit conversion factor.

Returns the legacy transform factor for the specified BOMViewRevision. If no legacy transform actor is available, PS_no_legacy_transform_factor is returned.

Parameters:
bvr  (I) Tag of the BVR
legacy_factor  (O) Returns the legacy transform factor from the BVR

PS_API int PS_ask_note_type_default_value ( tag_t  note_type,
char **  default_value 
)

Returns the default value of the note type

Parameters:
note_type  (I) Tag of the note type
default_value  (OF) Returns the default value of the note type

PS_API int PS_ask_note_type_description ( tag_t  note_type,
char **  description 
)

Returns the description of a note type.

Parameters:
note_type  (I) Tag of the note type
description  (OF) Returns the description of the note type

PS_API int PS_ask_note_type_name ( tag_t  note_type,
char **  name 
)

Returns the name of a note type.

Parameters:
note_type  (I) Tag of the note type
name  (OF) Returns the name of the note type

PS_API int PS_ask_occ_clone_stable_uid ( tag_t  parent,
tag_t  occurrence,
char **  clone_stable_uid 
)

When a bvr is copied to a different view (by PS_copy_bvr) or to a different item (by item save as) then occurrence tags are _not_ carried over, however this value will be preserved between equivalent occurrences in the source and new bvr.

Parameters:
parent  (I)
occurrence  (I)
clone_stable_uid  (OF)

PS_API int PS_ask_occurrence_child ( tag_t  parent,
tag_t  occurrence,
tag_t *  child_item,
tag_t *  child_bom_view 
)

Inquires the child Item or Item Revision and BOMView of an occurrence. If the occurrence has two or more substitutes, the preferred child is returned.

If the parent BOMViewRevision is "precise," child_item will be the tag of an Item Revision. If the parent BOMViewRevision is "imprecise", child_item will be the tag of an Item.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
child_item  (O) Returns the tag of the child Item or Item Revision referenced by the occurrence
child_bom_view  (O) Returns the tag of the child BOMView referenced by the occurrence

PS_API int PS_ask_occurrence_client_data ( tag_t  parent,
tag_t  occurrence,
const char *  attr_name,
tag_t *  client_data 
)

Returns the client data attributed to the occurrence for the specified attribute name. The client data is a tag of a POM object.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
attr_name  (I) Name of the attribute to be retrieved
client_data  (O)

PS_API int PS_ask_occurrence_flag ( tag_t  parent,
tag_t  occurrence,
int  flag,
logical *  is_set 
)

Inquires the state (true or false) of a flag attribute of an occurrence. Currently, only one flag attribute, PS_qty_as_required, is implemented. If set, this occurrence indicates the child Item it references is to be used as required. This interface is intended to support the addition of new flag attributes in the future.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
flag  (I) Integer value defined in ps_tokens.h that identifies the flag. Currently, PS_qty_as_required is the only flag supported.
is_set  (O) Returns true if the flag is set, otherwise false

PS_API int PS_ask_occurrence_name ( tag_t  parent,
tag_t  occurrence,
char **  occurrence_name 
)

Parameters:
parent  (I)
occurrence  (I)
occurrence_name  (OF)

PS_API int PS_ask_occurrence_note_text ( tag_t  parent,
tag_t  occurrence,
tag_t  note_type,
char **  text 
)

An occurrence can have textual notes attached to it. Each note has a note type, which identifies the purpose of that note (e.g., "usage", "color"). An occurrence can have any number of notes, as long as each note is of a different note type. Note types are defined for a Teamcenter installation by the Teamcenter system administrator.

This function returns the text of a note of the specified note type attached to the specified occurrence.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
note_type  (I) Tag of the note type
text  (OF) Returns the text of the specified note

PS_API int PS_ask_occurrence_qty ( tag_t  parent,
tag_t  occurrence,
double *  qty 
)

Inquires the attribute quantity of an occurrence.

A negative quantity means "quantity undefined." This is the initial state for newly created occurrences.

Note that a quantity of "as required" can be recorded on an occurrence by setting the PS_qty_as_required occurrence flag. See also PS_ask_occurrence_flag and PS_set_occurrence_flag.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
qty  (O) Returns the quantity attribute of the occurrence

PS_API int PS_ask_occurrence_ref_designator ( tag_t  parentBVR,
tag_t  occThread,
char **  refDesignator 
)

Inquires the attribute RefDesignator of an occurrence.

Parameters:
parentBVR  (I) Tag of the occurrence's parent BOMView Revision
occThread  (I) Tag of the occurrence
refDesignator  (OF) Returns the RefDesignator attribute of the occurrence

PS_API int PS_ask_occurrence_type ( tag_t  parent,
tag_t  occurrence,
char **  occTypeString 
)

This function is used to ask the occurrence type of an existing occurrence.

Parameters:
parent  (I) Parent bvr of the occurrence
occurrence  (I) Tag of the occurrence thread to ask the type for in the parent bvr
occTypeString  (OF) The tag of the occurrence type

PS_API int PS_ask_occurrence_type_name ( tag_t  occ_type,
char **  type_name 
)

This function is used to enquire the name of an existing occurrence type.

Parameters:
occ_type  (I) Tag of the occurrence type to enquire name for
type_name  (OF) The name of the occurrence type

PS_API int PS_ask_plmxml_transform ( tag_t  parent,
tag_t  occurrence,
double **  transform 
)

An ITK routine for asking and setting the PLM XML format transform.

Returns the PLM XML transform of the specified occurrence. If no transform is set PS_no_transform is returned. If both an PLM XML transform and a legacy transform are found, PS_two_transforms is returned. If the occurrence only has a legacy transform, PS_has_old_transform_only is returned.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
transform  (OF) 16 Returns a pointer to an MEM_alloc()ed array holding 16 doubles, which represent a PLM XML format 4X4 transform matrix. The transform matrix looks like [ R R R T ] * 'R' is the rotation part; [ R R R T ] * 'T' is the transform vector; [ R R R T ] * 'P' is the perspective part; [ P P P S ] * 'S' is the inverse scale; The components of the transform are specified as the following ( column order): R R R P R R R P R R R P T T T S. With regards to mixed units, Transforms are always in the units of the parent, not the child to which they're applied. In PLM XML, when the attribute type=scale specified on Transform element, it takes priority over the entry 'S' above. More information about PLM XML Transform definition can be found on http://www.plm.automation.siemens.com/en_us/products/open/plmxml/schemas.shtml

PS_API int PS_ask_seq_no ( tag_t  parent,
tag_t  occurrence,
char **  seq_no 
)

Inquires the sequence number attribute of an occurrence.

Note:
Sequence numbers are alphanumeric and are therefore stored as text strings.
Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
seq_no  (OF) Returns the sequence number as a string

PS_API int PS_ask_struct_modified_date ( tag_t  bvr,
date_t *  struct_dlm 
)

This function will return the time/date at which the structure was changed by the change conditions and saved

Parameters:
bvr  (I)
struct_dlm  (O)

PS_API int PS_ask_transform ( tag_t  parent,
tag_t  occurrence,
double **  transform 
)

Returns the legacy transform of the specified occurrence if one is available. If no transform is set, a null pointer is set and PS_no_transform is returned. If a PLM XML transform is set and the legacy factor is present, the PLM XML transform is converted to the legacy format and returned. If a PLM XML transform is set, but no legacy factor is available, then PS_no_legacy_transform_factor is returned. If both PLM XML and legacy transforms are present, PS_two_transforms is returned.

Return Values:

PS_no_legacy_transform_factor - This occurrence has the PLM XML transform set without a legacy factor.

Deprecated:
This function is not supported after Version 10.0. Please use PS_ask_plmxml_transform instead.
Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
transform  (OF) 16 Returns a pointer to an MEM_alloc()ed array holding a 4x4 transformation matrix

PS_API int PS_ask_variant_data ( tag_t  parent,
tag_t  occurrence,
tag_t *  variant_expression_block 
)

Returns the tag of a variant expression block which describes the variant condition that applies to this occurrence. If the occurrence has no variant data defined, then NULLTAG is returned.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
variant_expression_block  (O) POM object holding the variant condition. Go to bom.h for routines to manipulate a variant expression block.

PS_API int PS_ask_view_type_name ( tag_t  view_type,
char **  type_name 
)

Returns the name of a view type.

Parameters:
view_type  (I) Tag of the view type
type_name  (OF) Name of the view type

PS_API int PS_bvr_ask_default_next_seq_no ( tag_t  bvr,
tag_t  child_item,
char **  seq_no 
)

Generates next sequence number for the PS BOMView Revision.

Note:
This function is called by the the user exit USER_ask_new_seqno/USER_ask_for_new_sequence_no. the child item parameter need to be passed if user has preference PS_new_seqno_mode = existing otherwise just pass the NULLTAG to generate a new sequence number.- default behaviour.
Parameters:
bvr  (I) BOM View Revision tag
seq_no  < (I) child item tag (OF) Returns the sequence number as a string

PS_API int PS_bvr_translate_mvl ( tag_t  bvr,
int  n_modules,
char **  from_modules,
char **  to_modules 
)

Parameters:
bvr  (I)
n_modules  (I)
from_modules  (I) n_modules
to_modules  (I) n_modules

PS_API int PS_change_to_replace ( tag_t  oldBvr,
tag_t  oldOccTag,
tag_t  newBvr,
tag_t  newOccTag 
)

Parameters:
oldBvr  (I) bomview revision tag of left window
oldOccTag  (I) occurrence thread tag of left window
newBvr  (I) bomview revision tag of right window
newOccTag  (I) occurrence thread tag of right window

PS_API int PS_clear_occurrence_flag ( tag_t  parent,
tag_t  occurrence,
int  flag 
)

Clears a flag attribute of an occurrence. Currently, only one flag attribute is implemented, PS_qty_as_required. If set, this occurrence indicates the child Item it references is to be used as required. This interface is intended to support the addition of new flag attributes in the future.

Note:
To set the flag, use PS_set_occurrence_flag.
If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.
Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
flag  (I) Integer value defined in ps_tokens.h that identifies the flag. Currently, PS_qty_as_required is the only flag supported.

PS_API int PS_convert_legacy_transform ( tag_t  parent,
tag_t  occurrence,
double **  ext_transform 
)

An ITK routine for converting transforms from legacy to PLM XML format.

This function generates the PLM XML transform for the specified occurrence and parent BOMView Revision. This function attempts to convert an existing old style transform, which must be in the correct "Legacy" format, to the corresponding PLM XML format transform. If necessary, the value of the PS_assume_legacy_transform_units preference is taken as the units of the parent. The value PS_transform_units_pref_invalid is returned if this preference is invalid. If the occurrence already has a PLM XML format transform associated with it, PS_already_plmxml_transform is returned, or if no conversion is possible, PS_could_not_convert_transform is returned.

Return Values:

PS_already_plmxml_transform The occurrence already has an PLM XML transform on it.
PS_no_transform No legacy transform is found.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
ext_transform  (OF) 16 A pointer to an SM array of 16 doubles representing a PLM XML format 4x4 transform matrix or a null pointer if the conversion can't be done. The transform matrix looks like [ R R R T ] * 'R' is the rotation part; [ R R R T ] * 'T' is the transform vector; [ R R R T ] * 'P' is the perspective part; [ P P P S ] * 'S' is the inverse scale; The components of the transform are specified as the following ( column order): R R R P R R R P R R R P T T T S. With regards to mixed units, Transforms are always in the units of the parent, not the child to which they're applied. In PLM XML, when the attribute type=scale specified on Transform element, it takes priority over the entry 'S' above. More information about PLM XML Transform definition can be found on http://www.plm.automation.siemens.com/en_us/products/open/plmxml/schemas.shtml

PS_API int PS_copy_bvr ( tag_t  source_bvr,
tag_t  bom_view,
const char *  revision_name,
const char *  revision_desc,
tag_t  parent_ir,
tag_t *  new_bvr 
)

Produces a new working BOMViewRevision based on the source BOMViewRevision of a different BOMView. The new BOMView Revision is made an attribute of the specified parent Item Revision. This Item Revision must be a revision of the Item that is the parent of the target BOMView.

Note:
The new BOMView Revision is not saved. It can be saved to the database using AOM_save. Note that the parent Item Revision is modified and must also be saved.

If the target parent Item Revision already references a revision of the specified BOMView, the reference to the new BOMView Revision replaces the reference to the old one.

Parameters:
source_bvr  (I) Tag of the BOMViewRevision to base the new revision on
bom_view  (I) Create a new revision of this BOMView
revision_name  (I) Revision name. If NULL or empty string "" is specified, the default name is used. See also PS_default_bvr_name.
revision_desc  (I) A description of the revision (can be NULL)
parent_ir  (I) Tag of the parent Item Revision of the new BOMView Revision
new_bvr  (O) Returns the tag of the newly created BOMView Revision

PS_API int PS_create_bom_view ( tag_t  view_type,
const char *  view_name,
const char *  view_desc,
tag_t  parent_item,
tag_t *  bom_view 
)

Creates a new BOMView. No BOMView Revisions exist yet. The BOMView is made a view of the specified item. If view_type is NULLTAG, the default view type will be used (as given by PS_ask_default_view_type).

Note:
The new BOMView is not saved. It can be saved to the database using AOM_save. Note that the parent_item is modified and must also be saved. The new BOMView must be saved before the parent_item is saved. Failure to do so results in the BOMView not being added to the parent.
Parameters:
view_type  (I) Site-specific identifier for the type of view (e.g., DESIGN, Assembly)
view_name  (I) Name of the view. If NULL or empty string is specified, the default name is used. See also PS_default_bom_view_name.
view_desc  (I) Optional description text (NULL if not required)
parent_item  (I) Makes the new BOMView a view of this Item
bom_view  (O) Returns the tag of the new BOMView

PS_API int PS_create_bvr ( tag_t  bom_view,
const char *  revision_name,
const char *  revision_desc,
logical  precise,
tag_t  parent_ir,
tag_t *  bvr 
)

Creates an initial working revision of a BOMView, with no occurrences. The BOMView Revision created is made an attribute of the specified parent Item Revision. This Item Revision must be a revision of the Item that is the parent of the BOMView.

Note:
The new BOMView Revision is not saved, it can be saved to the database using AOM_save. Note that the parent Item Revision is modified and must also be saved. The new BOMView Revision must be saved before the parent Item Revision is saved. Failure to do so results in the BOMView Revision not being added to the parent.
Parameters:
bom_view  (I) Tag of the BOMView for which the first revision is to be created
revision_name  (I) Revision name. If NULL or empty string "" is specified, the default name is used. See also PS_default_bvr_name.
revision_desc  (I) A description of the revision (can be NULL)
precise  (I) If true the BOMView Revision can have precise occurrences of child Item Revisions. If false it can have imprecise occurrence of child Items.
parent_ir  (I) The tag of the parent Item Revision of the BOMView Revision
bvr  (O) Returns the tag of the newly created BOMView Revision

PS_API int PS_create_occurrences ( tag_t  parent,
tag_t  child_item,
tag_t  child_bom_view,
int  n_occurrences,
tag_t **  occurrences 
)

Creates a number of occurrences linking the specified parent BOMView Revision and the child Item / BOMView pairing.

If the parent BOMView Revision is "precise," child_item must be the tag of a specific Item Revision.

If the parent BOMView Revision is "imprecise," child_item can be the tag of an Item or an Item Revision. If the tag of an Item Revision is given, the occurrence will store a reference to the Item of which it is a revision.

The BOMView specified must belong to the child Item. When multiple views functionality is provided in a future release this will allow differentiation between the views of an item.

If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function creates occurrences in the loaded representation of the BOMView Revision only. The new occurrences will be stored in the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the parent BOMView Revision
child_item  (I) Tag of the child Item or Item Revision
child_bom_view  (I) Tag of the child BOMView
n_occurrences  (I) The number of occurrences to be created
occurrences  (OF) n_occurrences Returns an array of the tags of the occurrences created

PS_API int PS_create_occurrences_tag_validation ( tag_t  parent,
tag_t  child_item,
int  n_occurrences 
)

Valites parent, child and occurrnces for PS_create_occurrences and PS_create_occurrences_with_occ_type

Parameters:
parent  (I) Tag of the parent BOMView Revision
child_item  (I) Tag of the child Item or Item Revision
n_occurrences  (I) The number of occurrences to be created

PS_API int PS_create_occurrences_with_occ_type ( tag_t  parent,
tag_t  child_item,
tag_t  child_bom_view,
int  n_occurrences,
tag_t  occType,
tag_t **  occurrences 
)

Creates a number of occurrences linking the specified parent BOMView Revision and the child Item / BOMView pairing with a specific Occurrence Type.

Parameters:
parent  (I) Tag of the parent BOMView Revision
child_item  (I) Tag of the child Item or Item Revision
child_bom_view  (I) Tag of the child BOMView
n_occurrences  (I) The number of occurrences to be created
occType  (I) Tag of the occurrence type
occurrences  (OF) n_occurrences Returns an array of the tags of the occurrences created

PS_API int PS_default_bom_view_name ( tag_t  item,
tag_t  view_type,
char **  name 
)

Returns a default name for a BOMView. The default implementation creates a name of the form "<Item ID>-<view type name>" (e.g., 100-Design).

Note:
To allow user customization of the default name format, this function calls out via the USER_ps_default_bom_view_name user exit. The default implementation of this user exit uses the PS_system_default_bom_view_name function to generate the default name format as described above.

It is not necessary to call this function to pass a name to PS_create_bom_view, as that function will automatically use the default name when passed a NULL or empty string ("") (e.g., to pre-populate a dialog box field with a default name for a BOMView to be created).

If the view_type argument is NULLTAG, the user's default view type is used.

Parameters:
item  (I) Tag of the Item of the BOMView
view_type  (I) Tag of the view type of the BOMView
name  (OF)

PS_API int PS_default_bvr_name ( tag_t  item_revision,
tag_t  view_type,
char **  name 
)

Returns a default name for a BOMView Revision. The default implementation creates a name of the form "<Item Revision ID>-<view type name>" (e.g., "100/A-Design").

Note:
To allow user customization of the default name format, this function calls out via the USER_ps_default_bvr_name user exit. The default implementation of this user exit uses the PS_system_default_bvr_name function to generate the default name format as described above.

It is not necessary to call this function to pass a name to PS_create_bvr, PS_revise_bvr or PS_copy_bvr as any of those functions will automatically use the default name when passed a NULL or empty string (""). This function is intended for example to pre-populate a dialog box field with a default name for a BOMView Revision to be created.

If the view type argument is NULLTAG, the user's default view type is used.

Parameters:
item_revision  (I) Tag of the Item Revision the new BOMView Revision is to be created for
view_type  (I) Tag of the intended type of the BOMView Revision to be created (if the BOMView already exists then this should be the type of that BOMView).
name  (OF)

PS_API int PS_define_client_data ( int  ps_class,
const char *  attr_name,
tag_t  ref_class,
int  property 
)

Adds an extra attribute to a PS class. This extra attribute must be a reference to a POM object. The type of the reference is the specified class.

Note:
This function can only be called by a user with Teamcenter system administrator privilege.
Parameters:
ps_class  (I) Token identifying the class of PS object to which this attribute is to be attached
attr_name  (I) Name of the attribute
ref_class  (I) Tag of the POM class which this attribute is to reference
property  (I) The attribute can have its property set to PS_copyable, in which case this attribute is copied from one revision of the object to another.

Client data attributes can be added to the classes PS_bom_view, PS_bom_view_revision, PS_occurrence and PS_view_type. Property PS_copyable is only applicable to PS_bom_view_revision and PS_occurrence.

PS_API int PS_delete_bom_view ( tag_t  bom_view  ) 

Deletes a BOMView and all of its BOMViewRevisions, provided none of them is referenced.

Parameters:
bom_view  (I) Tag of the view to be deleted

PS_API int PS_delete_bvr ( tag_t  bvr  ) 

Deletes the specified BOMViewRevision, provided it is not referenced.

Parameters:
bvr  (I) Tag of the BOMView Revision to be deleted

PS_API int PS_delete_client_data_defn ( int  ps_class,
const char *  attr_name 
)

Remove definition of client data attribute. Only possible if attribute has not been populated.

Parameters:
ps_class  (I)
attr_name  (I)

PS_API int PS_delete_occurrence ( tag_t  parent,
tag_t  occurrence 
)

Deletes the occurrence from its parent BOMView Revision.

If necessary, this function will load the parent BOMView Revision and lock it for modify.

Note:
This function only removes the occurrence from the loaded representation of the BOMView Revision. It is not removed from the database until the parent BOMView Revision is saved using function AOM_save.

Equivalent occurrences referenced by the same tag from other revisions of the same parent BOMView are not effected by this deletion.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence

PS_API int PS_delete_occurrence_note ( tag_t  parent,
tag_t  occurrence,
tag_t  note_type 
)

An occurrence can have textual notes attached to it. Each note has a note type, which identifies the purpose of that note (e.g., "usage," "color"). An occurrence can have any number of notes, as long as each note is of a different note type. Note types are defined for a Teamcenter installation by the Teamcenter system administrator.

This function deletes a note of the specified note type attached to the specified occurrence.

If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
note_type  (I) Tag of the note type

PS_API int PS_delete_substitute ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item 
)

Removes the specified non-preferred substitute from the list of substitutes for this occurrence. This will not remove the preferred substitute, so in order to remove the preferred substitute, a different substitute must be preferred first.

Parameters:
parent  (I) Tag of the parent BOMView Revision
occurrence  (I) Tag of the occurrence
child_item  (I) Tag of the child Item or Item Revision

PS_API int PS_describe_client_data ( int  ps_class,
const char *  attr_name,
tag_t *  ref_class,
int *  property 
)

Describes an attribute of a PS class. The class and property of the attribute are returned.

The attribute name must be one that has previously been defined using PS_define_client_data.

Parameters:
ps_class  (I) Token identifying the class of PS object to which this attribute is to be attached
attr_name  (I) Name of the attribute
ref_class  (O) Tag of the POM class which this attribute is to reference
property  (O) The attribute property that is returned will have a value of either PS_copyable (the attribute will copied with the instance) or PS_manage (all operations on the instance are automatically applied to the property).

PS_API int PS_find_note_type ( const char *  name,
tag_t *  note_type 
)

Returns the tag of the note type with the specified name.

Parameters:
name  (I) Name of the note type
note_type  (O) Returns the tag of the note type

PS_API int PS_find_occurrence_type ( const char *  type_name,
tag_t *  occ_type 
)

Returns the tag of the occ classification with the given name.

Parameters:
type_name  (I) The name of the occurrence type to find
occ_type  (O) Tag of the existing occurrence type of the given name

PS_API int PS_find_view_type ( const char *  type_name,
tag_t *  view_type 
)

Returns the tag of the view type with the specified name.

Parameters:
type_name  (I) Name of the view type
view_type  (O) Tag of the view type

PS_API int PS_get_displayable_view_types ( int *  n_types,
tag_t **  view_types 
)

Parameters:
n_types  (O)
view_types  (OF) n_types

PS_API int PS_has_form_attached_to_ug_dataset ( tag_t  item_rev,
logical *  result 
)

Parameters:
item_rev  (I)
result  (O)

PS_API int PS_list_bvrs_of_bom_view ( tag_t  bom_view,
int *  n_bvrs,
tag_t **  bvrs 
)

Returns a list of all the revisions of the specified BOMView which have been saved to the database.

Parameters:
bom_view  (I) Tag of the BOMView
n_bvrs  (O) Number of revisions of the specified BOMView
bvrs  (OF) n_bvrs An array of the tags of the revisions of the BOMView

PS_API int PS_list_occurrence_notes ( tag_t  parent,
tag_t  occurrence,
int *  n_notes,
tag_t **  note_types 
)

An occurrence can have textual notes attached to it. Each note has a note type, which identifies the purpose of that note (e.g., "usage", "color"). An occurrence can have any number of notes, as long as each note is of a different note type. Note types are defined for a Teamcenter installation by the Teamcenter system administrator.

This function returns a list of the notes attached to the specified occurrence. Each note is identified by the tag of its note type. The note text can be found using PS_ask_occurrence_note_text.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
n_notes  (O) The number of notes attached to this occurrence
note_types  (OF) n_notes An array of the tags of the note type of each note attached to this occurrence

PS_API int PS_list_occurrences_of_bvr ( tag_t  bvr,
int *  n_occurrences,
tag_t **  occurrences 
)

Lists all of the occurrences of the specified BOMViewRevision.

Parameters:
bvr  (I) Tag of the BOMView Revision
n_occurrences  (O) Number of occurrences returned
occurrences  (OF) n_occurrences Returned array of the tags of the occurrences

PS_API int PS_list_optional_items ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
int *  count,
tag_t **  opt_items 
)

Parameters:
parent  (I)
occurrence  (I)
child_item  (I)
count  (O)
opt_items  (OF) count

PS_API int PS_list_owning_revs_of_bvr ( tag_t  bvr,
int *  n_item_revs,
tag_t **  item_revs 
)

Lists all the Item Revisions that reference this BOMView Revision.

Note:
If this BOMView Revision is referenced by more than one Item Revision, then you will not be allowed to modify its structure. You must first revise the BOMView Revision in the Item Revision whose structure you want to change.

From V3.4, BOMView Revisions are automatically revised when ItemRevisions are copied. This means that new BOMView Revisions will only ever be referenced by a single Item Revision, and only pre-V3.4 legacy data will contain shared BOMView Revisions.

Parameters:
bvr  (I) Tag of the BOMView Revision
n_item_revs  (O) Number of referencing Item Revisions
item_revs  (OF) n_item_revs Returned array of the tags of the Item Revisions

PS_API int PS_list_predecessors ( tag_t  bvr,
tag_t  occ,
int *  count,
tag_t **  pred 
)

This function returns a list of the predecessor occurrences directly of the given occurrence.

Parameters:
bvr  (I) Tag of the parent bvr
occ  (I) Tag of the occurrence thread that predecessors are needed for
count  (O) Number of predecessors
pred  (OF) count MEM_alloc()ed array of the list of predecessor occurrence thread tags

PS_API int PS_list_related_substitutes ( tag_t  occurrence,
tag_t  sub_item,
int *  n_items,
tag_t **  related_occs,
tag_t **  related_items 
)

Parameters:
occurrence  (I) Tag of the occurrence
sub_item  (I) Tag of the substitute item
n_items  (O) number of related substitute items
related_occs  (OF) n_items Array of related occurrences
related_items  (OF) n_items Array of related substitutes

PS_API int PS_list_substitutes ( tag_t  parent,
tag_t  occurrence,
int *  n_substitutes,
tag_t **  sub_items,
tag_t **  sub_views 
)

Returns a list of all substitutes for the specified occurrence.

The child of a 'regular' occurrence is defined by a pair of tags, one is the Item or Item Revision (which depends on the parent BOMViewRevision being imprecise or precise), the other is a BOMView of the child Item/rev. The BOMView may be NULLTAG presently, in the future this will be used to distinguish between multiple views of the same Item.

V3.2 Substitutes allows a list of substitute children to be attached to a single occurrence. This list therefore contains pairs of Item/rev and BOMView tags.

This function returns the Item/rev and BOMView tags on two MEM_alloc()ed arrays. An Item/rev tag from one array and the BOMView tag from the same position on the second array therefore defines one substitute child.

If the occurrence has no substitutes, this function returns with n_substitutes equal to zero.

Parameters:
parent  (I) Tag of the parent BOMView Revision
occurrence  (I) Tag of the occurrence
n_substitutes  (O) Number of substitute children
sub_items  (OF) n_substitutes List of substitute Item/Item Revisions
sub_views  (OF) n_substitutes List of BOMViews

PS_API int PS_load_variant_expr_blocks ( int  n_blocks,
tag_t *  variant_expression_blocks,
logical  force_sub_expr_check 
)

Loads all the variant expressions in the given set of variant expression blocks (if they are not already loaded). The force_sub_expr_check argument should be used if you've already loaded the root expressions (to check the opcodes for example).

Parameters:
n_blocks  (I) Number of variant expression blocks to load
variant_expression_blocks  (I) n_blocks Tags of variant expression blocks to load
force_sub_expr_check  (I) Check that the first level sub-expressions are loaded too

PS_API int PS_load_variant_exprs ( int  n_exprs,
tag_t *  variant_expressions,
logical  force_sub_expr_check 
)

Loads the given set of variant expressions (if they are not already loaded). The force_sub_expr_check argument should be used if you've already loaded the root expressions (to check the opcodes for example).

Parameters:
n_exprs  (I) Number of variant expressions to load
variant_expressions  (I) n_blocks Tags of variant expressions to load
force_sub_expr_check  (I) Check that the first level sub-expressions are loaded too

PS_API int PS_move_occurrence_down ( tag_t  parent,
tag_t  occurrence 
)

By default, the occurrences of a BOMView Revision are listed in the order in which they were created. This sequence can be altered via PS_move_occurrence_to, PS_move_occurrence_up and PS_move_occurrence_down.

This function moves the specified occurrence one place down (i.e., towards the end of the list) in the occurrences of its parent BOMView Revision.

If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence

PS_API int PS_move_occurrence_to ( tag_t  parent,
tag_t  occurrence,
int  new_index 
)

By default the occurrences of a BOMView Revision are listed in the order in which they were created. This sequence can be altered via PS_move_occurrence_to, PS_move_occurrence_up and PS_move_occurrence_down.

This function moves the specified occurrence to be the new_index in the occurrences of its parent BOMView Revision (starting from zero).

If necessary this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
new_index  (I) New ordering index number for the occurrence within the set of occurrences belonging to the parent BOMView Revision

PS_API int PS_move_occurrence_up ( tag_t  parent,
tag_t  occurrence 
)

By default, the occurrences of a BOMView Revision are listed in the order in which they were created. This sequence can be altered via PS_move_occurrence_to, PS_move_occurrence_up and PS_move_occurrence_down.

This function moves the specified occurrence one place up (i.e., towards the front of the list) in the occurrences of its parent BOMView Revision.

If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence

PS_API int PS_note_type_extent ( int *  n_note_types,
tag_t **  note_types 
)

Returns the list of note types valid for this site.

Parameters:
n_note_types  (O) Number of note types in the list
note_types  (OF) n_note_types Returned array of tags of note types

PS_API int PS_occ_eff_add_eff ( tag_t  bvr,
tag_t  occ,
tag_t  eff 
)

Adds an existing effectivity object to an occurrence.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to attach effectivity to
eff  (I) The existing effectivity object that will be added to the occurrence

PS_API int PS_occ_eff_ask_date_range ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
char **  range_text 
)

Returns the date range of an occurrence effectivity as a text string.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
range_text  (OF) Date range text string

PS_API int PS_occ_eff_ask_dates ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
int *  n_dates,
date_t **  start_end_values,
int *  open_ended_or_stock_out 
)

Returns the date range of an occurrence effectivity as an array.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
n_dates  (O) The size of the array of start-end values
start_end_values  (OF) n_dates The array of start-end dates
open_ended_or_stock_out  (O) One of the following constants: EFFECTIVITY_open_ended, EFFECTIVITY_stock_out or EFFECTIVITY_closed.

PS_API int PS_occ_eff_ask_effs ( tag_t  bvr,
tag_t  occ,
int *  n_effs,
tag_t **  effs 
)

Returns a list of effectivities on an occurrence.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to query
n_effs  (O) Number of effectivities on the occurrence
effs  (OF) n_effs Array of effectivities

PS_API int PS_occ_eff_ask_enditem ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
tag_t *  enditem 
)

Returns the end item for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
enditem  (O) End item

PS_API int PS_occ_eff_ask_enditemrev ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
tag_t *  enditemrev 
)

Returns the end item revision for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
enditemrev  (O) End item

PS_API int PS_occ_eff_ask_id ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
char **  id 
)

Returns the Id for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
id  (OF) Effectivity id

PS_API int PS_occ_eff_ask_protection ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
logical *  protection 
)

Returns protection state of an occurrence effectivity

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
protection  (O) True if effectivity is protected

PS_API int PS_occ_eff_ask_range_type ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
int *  range_type 
)

Returns whether effectivity range is unit or date based.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
range_type  (O) The type of range for this occurrence effectivity: 0 No range, 1 Unit range, 2 Date range

PS_API int PS_occ_eff_ask_unit_range ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
char **  range_text 
)

Returns the unit range of an occurrence effectivity as a text string.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
range_text  (OF) Unit range text string

PS_API int PS_occ_eff_ask_units ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
int *  n_units,
int **  start_end_values,
int *  open_ended_or_stock_out 
)

Returns the unit range of an occurrence effectivity as an array.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence
eff  (I) Effectivity to query
n_units  (O) The size of the array of start-end values
start_end_values  (OF) n_units The array of start-end units
open_ended_or_stock_out  (O) One of the following constants: EFFECTIVITY_open_ended, EFFECTIVITY_stock_out or EFFECTIVITY_closed.

PS_API int PS_occ_eff_create ( tag_t  bvr,
tag_t  occ,
tag_t *  eff 
)

Creates a new occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to attach effectivity to
eff  (O) The newly created occurrence effectivity

PS_API int PS_occ_eff_remove_eff ( tag_t  bvr,
tag_t  occ,
tag_t  eff 
)

Removes an effectivity object from an occurrence.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to remove effectivity from
eff  (I) The effectivity object that will be removed from the occurrence

PS_API int PS_occ_eff_set_date_range ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
const char *  range_text,
logical  append 
)

Sets or appends the date range for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
range_text  (I) Range of dates that define the effectivity. For example, 1-Jan-2000 to 31-Dec-2000. Multiple ranges can be specified using the semi-colon separator 1-Jan-2000 to 31-Dec-2000; 1-Apr-2001 to 30-Apr-2001.
append  (I) Set this to true to add the new range to any existing ranges. Set this to false to overwrite existing ranges.

PS_API int PS_occ_eff_set_dates ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
int  n_dates,
date_t *  start_end_values,
int  open_ended_or_stock_out,
logical  append 
)

Sets or appends the date range for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
n_dates  (I) The size of the array of start-end values
start_end_values  (I) n_dates The array of start-end values of the discontinuous range. For example, consider a discontinuous range consisting of continuous ranges r1, r2, ..., rn where rx has start and end values, rx.start and rx.end. The array of start_end_vals for this discontinuous range will be constructed as { r1.start, r1.end, r2.start, r2.end, ..., rn.start, rn.end }. The last value, rn.end should be omitted if the discontinuous range is open ended.
open_ended_or_stock_out  (I) One of the following constants: EFFECTIVITY_open_ended, EFFECTIVITY_stock_out or EFFECTIVITY_closed.
append  (I) If set to true, the values in the array will be added to the date range, otherwise they will replace them.

PS_API int PS_occ_eff_set_enditem ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
tag_t  enditem 
)

Sets the end item for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
enditem  (I) The new end item for this effectivity

PS_API int PS_occ_eff_set_enditemrev ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
tag_t  enditemrev 
)

Sets the end item revision for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
enditemrev  (I) The new end item revision for this effectivity

PS_API int PS_occ_eff_set_id ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
const char *  id 
)

Sets the Id that can be used to reference an effectivity object. Effectivity objects can be queried by Id using the CFM_find_effectivities function.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
id  (I) The Id to assign to the occurrence effectivity

PS_API int PS_occ_eff_set_protection ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
logical  protection 
)

Protects an effectivity object against being modified.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
protection  (I) Set to true to prevent modification of effectivity.

PS_API int PS_occ_eff_set_unit_range ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
const char *  range_text,
logical  append 
)

Sets or appends a unit range for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
range_text  (I) Range of unit numbers that define the effectivity. For example, 100-199. Multiple ranges can be specified using a comma separator. For example, 100-199, 500-599.
append  (I) Set this to true to add the new range to any existing ranges. Set this to false to overwrite existing ranges.

PS_API int PS_occ_eff_set_units ( tag_t  bvr,
tag_t  occ,
tag_t  eff,
int  n_units,
int *  start_end_values,
int  open_ended_or_stock_out,
logical  append 
)

Sets or appends a unit range for an occurrence effectivity.

Parameters:
bvr  (I) Parent BVR of occurrence
occ  (I) Occurrence to which effectivity is attached
eff  (I) The effectivity object
n_units  (I) The size of the array of start-end values
start_end_values  (I) n_units The array of start-end values of the discontinuous range. For example, consider a discontinuous range consisting of continuous ranges r1, r2, ..., rn where rx has start and end values, rx.start and rx.end. The array of start_end_vals for this discontinuous range will be constructed as { r1.start, r1.end, r2.start, r2.end, ..., rn.start, rn.end }. The last value, rn.end should be omitted if the discontinuous range is open ended.
open_ended_or_stock_out  (I) One of the following constants: EFFECTIVITY_open_ended, EFFECTIVITY_stock_out or EFFECTIVITY_closed.
append  (I) If set to true, the values in the array will be added to the unit range, otherwise they will replace them.

PS_API int PS_occurrence_type_extent ( int *  n_types,
tag_t **  occ_types 
)

This function is used to list all occurrence types in the database.

Parameters:
n_types  (O) Number of occcurrence types in the database
occ_types  (OF) n_types Array of tags of all the occurrence types

PS_API int PS_prefer_substitute ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
logical *  is_temporary 
)

Makes the specified substitute the preferred substitute for the occurrence. This means it is the child that is given by default, e.g. when you call PS_ask_occurrence_child.

If the parent BOMView Revision is write protected or frozen, the change to which substitute is preferred is made in the loaded copy only, and cannot be saved to the database. In this case is_temporary is set to true.

Parameters:
parent  (I) Tag of the parent BOMView Revision
occurrence  (I) Tag of the occurrence
child_item  (I) Tag of the child Item or Item Revision
is_temporary  (O) Flag whether the change can be saved

PS_API int PS_remove_legacy_transform_factor ( tag_t  bvr  ) 

An ITK routine for asking and setting the unit conversion factor.

Removes the legacy transform factor from the specified BOMViewRevision.

Parameters:
bvr  (I) Tag of the BVR

PS_API int PS_remove_optional_item ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
tag_t  opt_item,
tag_t  opt_rev,
tag_t  opt_view 
)

Parameters:
parent  (I)
occurrence  (I)
child_item  (I)
opt_item  (I)
opt_rev  (I)
opt_view  (I)

PS_API int PS_remove_predecessor ( tag_t  bvr,
tag_t  occ,
tag_t  predecessor 
)

This function is used to remove a predecessor directly to the occurrence.

Restrictions:

  1. Both occ and predecessor share the same parent bvr.
  2. predecessor is already a predecessor of occ.
Parameters:
bvr  (I) Tag of the parent bvr
occ  (I) Tag of the successor occurrence thread
predecessor  (I) Tag of the predecessor occurrence thread

PS_API int PS_remove_related_substitutes ( int  n_items,
tag_t *  occurrences,
tag_t *  sub_items 
)

Parameters:
n_items  (I) number of related substitute items
occurrences  (I) Array of related occurrence
sub_items  (I) Array of related substitute items

PS_API int PS_revise_bvr ( tag_t  source_bvr,
const char *  revision_name,
const char *  revision_desc,
tag_t  parent_ir,
tag_t *  new_bvr 
)

Produces a new working BOMViewRevision based on the source BOMViewRevision. The new BOMView Revision is made an attribute of the specified parent Item Revision. This Item Revision must be a revision of the Item that is the parent of the BOMView of which the source BOMView Revision is a revision.

Whenever an Item Revision is revised, the BOMView Revisions are automatically revised as well, rather than being shared between the old and new Item Revisions. Because BOMView Revisions are no longer shared between Item Revisions, it is no longer necessary to revise BOMView Revisions within the same Item Revision.

The purpose of this function is to accommodate legacy data from iMAN 3.3 and earlier, which can contain shared BOMView Revisions. These BOMView Revisions can be revised within the same Item Revision in order to "unshare" them.

Note:
Revising an unshared BOMView Revision is not allowed as it would "orphan" the previous revision, leaving it unattached to any Item Revision.

The new BOMView Revision is not saved. It can be saved to the database using AOM_save. Note that the parent Item Revision is modified and must also be saved.

The reference to the new BOMView Revision replaces the reference to the old one, if the target parent Item Revision already references a revision of this BOMView.

Parameters:
source_bvr  (I) Tag of the BOMViewRevision to base the new revision on
revision_name  (I) Revision name. If NULL or empty string "" is specified, the default name is used. See also PS_default_bvr_name.
revision_desc  (I) A description of the revision (can be NULL)
parent_ir  (I) Tag of the parent Item Revision of the new BOMView Revision
new_bvr  (O) Returns the tag of the newly created BOMView Revision

PS_API int PS_set_bom_view_type ( tag_t  bom_view,
tag_t  view_type 
)

Sets the view type of a BOMView.

Parameters:
bom_view  (I) Tag of the BOMView
view_type  (I) Tag of the view type of BOMView

PS_API int PS_set_bvr_imprecise ( tag_t  bvr  ) 

Makes this BOMView Revision "imprecise." An "imprecise" BOMView Revision can only contain imprecise occurrences of child Items.

If necessary this function loads the BOMView Revision and locks it for modify. To save the new state to the database call function AOM_save.

Note:
This function does not attempt to convert any existing precise occurrences to imprecise. A call to the equivalent BOM ITK function will make this conversion.
Parameters:
bvr  (I) Tag of the BOMView Revision

PS_API int PS_set_bvr_precise ( tag_t  bvr  ) 

Makes this BOMView Revision "precise." A "precise" BOMView Revision can only contain precise occurrences of child Item Revisions.

If necessary this function loads the BOMView Revision and locks it for modify. To save the new state to the database call function AOM_save.

Note:
This function does not attempt to convert any existing imprecise occurrences to precise. A call to the equivalent BOM ITK function works in the context of a Configuration Rule. Because of this, suitable Item Revisions are produced to replace Items and make this conversion.
Parameters:
bvr  (I) Tag of the BOMView Revision

PS_API int PS_set_client_data ( tag_t  instance,
const char *  attr_name,
tag_t  client_data 
)

Sets the client data attributed to the instance for the specified attribute name. The client data must be a tag of a POM object of the class specified in the definition of this attribute. See also PS_define_client_data.

This function is also used to clear an attribute, in which case NULLTAG is passed in place of the client data tag.

Note:
This function is used for setting client data of all PS classes except occurrence. As occurrences are referenced using a parent BOMView Revision, occurrence pairing a separate interface function PS_ask_occurrence_client_data is provided to set the client data of an occurrence.
Parameters:
instance  (I) Tag of an instance of a PS class
attr_name  (I) Name of the attribute to be retrieved
client_data  (I) Tag of a POM object, or NULLTAG to clear the attribute.

PS_API int PS_set_legacy_transform_factor ( tag_t  bvr,
double  legacy_factor 
)

An ITK routine for asking and setting the unit conversion factor.

Sets the unit conversion factor for the specified BOMViewRevision.

Parameters:
bvr  (I) Tag of the BVR
legacy_factor  (I) Returns the legacy transform factor to be set on the BVR

PS_API int PS_set_occurrence_child ( tag_t  parent,
tag_t  occurrence,
tag_t  child_item,
tag_t  child_bom_view 
)

Sets the child Item or Item Revision and BOMView referenced by an occurrence.

If the parent BOMView Revision is "precise," child_item must be the tag of a specific Item Revision.

If the parent BOMView Revision is "imprecise," child_item can be the tag of an Item or an Item Revision. If the tag of an Item Revision is, the occurrence will store a reference to the Item of which it is a revision.

The BOMView specified must belong to the child Item. When multiple views functionality is provided in a future release this will allow differentiation between the views of an item.

If necessary this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
child_item  (I) Tag of the child Item or Item Revision referenced by the occurrence
child_bom_view  (I) Tag of the child BOMView referenced by the occurrence

PS_API int PS_set_occurrence_client_data ( tag_t  parent,
tag_t  occurrence,
const char *  attr_name,
tag_t  client_data 
)

Sets the client data attributed to the occurrence for the specified attribute name. The client data must be a tag of a POM object of the class specified in the definition of this attribute. See also PS_define_client_data.

This function is also used to clear an attribute of an occurrence, in which case NULLTAG is passed in place of the client data tag.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
attr_name  (I) Name of the attribute being set
client_data  (I) Tag of a POM object, or NULLTAG to clear the attribute

PS_API int PS_set_occurrence_flag ( tag_t  parent,
tag_t  occurrence,
int  flag 
)

Sets a flag attribute of an occurrence. Currently, only one flag attribute is implemented, PS_qty_as_required. If set, this occurrence indicates the child Item it references is to be used as required. This interface is intended to support the addition of new flag attributes in the future.

Note:
To clear the flag, use PS_clear_occurrence_flag.
If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.
Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
flag  (I) Integer value defined in ps_tokens.h that identifies the flag. Currently, PS_qty_as_required is the only flag supported.

PS_API int PS_set_occurrence_name ( tag_t  parent,
tag_t  occurrence,
const char *  occurrence_name 
)

Parameters:
parent  (I)
occurrence  (I)
occurrence_name  (I)

PS_API int PS_set_occurrence_note_text ( tag_t  parent,
tag_t  occurrence,
tag_t  note_type,
const char *  text 
)

An occurrence can have textual notes attached to it. Each note has a note type, which identifies the purpose of that note (e.g., "usage," "color"). An occurrence can have any number of notes, as long as each note is of a different note type. Note types are defined for a Teamcenter installation by the Teamcenter system administrator.

This function sets the text of a note of the specified note type attached to the specified occurrence. If the occurrence does not currently have a note of this type then one is created. If the occurrence does already have a note of this type then its text is overwritten with this new string.

If necessary this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
note_type  (I) Tag of the note type
text  (I) A text string for the note

PS_API int PS_set_occurrence_qty ( tag_t  parent,
tag_t  occurrence,
double  qty 
)

Sets the quantity attribute of an occurrence. A negative quantity means "quantity undefined."

Note that a quantity of "as required" can be recorded on an occurrence by setting the PS_qty_as_required occurrence flag. See also PS_ask_occurrence_flag and PS_set_occurrence_flag.

If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
qty  (I) A new quantity value for the occurrence

PS_API int PS_set_occurrence_ref_designator ( tag_t  parentBVR,
tag_t  occThread,
const char *  refDesignator 
)

Inquires the attribute RefDesignator of an occurrence.

Parameters:
parentBVR  (I) Tag of the occurrence's parent BOMView Revision
occThread  (I) Tag of the occurrence
refDesignator  (I) RefDesignator attribute of the occurrence

PS_API int PS_set_occurrence_type ( tag_t  parent,
tag_t  occurrence,
const char *  occTypeString 
)

This function is used to set the occurrence type of an existing occurrence.

Parameters:
parent  (I) Parent bvr of the occurrence
occurrence  (I) Tag of the occurrence thread to ask the type for in the parent bvr
occTypeString  (I) The tag of the occurrence type to be set

PS_API int PS_set_plmxml_transform ( tag_t  parent,
tag_t  occurrence,
double *  transform 
)

An ITK routine for asking and setting the PLM XML format transform.

If the legacy factor is set, or the site preference PS_allow_plmxml_transforms_with_no_legacy_transform_factor is set to "Yes", this function sets the specified PLM XML transform for the given occurrence and removes the legacy transform. If this preference is set to "No" and there is no legacy factor, PS_no_legacy_transform_factor is returned. If a null pointer is passed, both legacy and PLM XML transforms are removed if they exist. If the preference is not present or set to an unspecified value, PS_allow_plmxml_pref_invalid is returned regardless of the presence of any stored transforms or the legacy factor. If necessary, this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.

Return Values:

PS_allow_plmxml_pref_invalid - The PS_allow_plmxml_transforms_with_no_legacy_transform_factor preference is not valid.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
transform  (I) 16 A pointer to an array of 16 doubles representing a PLM XML format 4x4 transform matrix. The transform matrix looks like [ R R R T ] * 'R' is the rotation part; [ R R R T ] * 'T' is the transform vector; [ R R R T ] * 'P' is the perspective part; [ P P P S ] * 'S' is the inverse scale; The components of the transform are specified as the following ( column order): R R R P R R R P R R R P T T T S. With regards to mixed units, Transforms are always in the units of the parent, not the child to which they're applied. In PLM XML, when the attribute type=scale specified on Transform element, it takes priority over the entry 'S' above. More information about PLM XML Transform definition can be found on http://www.plm.automation.siemens.com/en_us/products/open/plmxml/schemas.shtml

PS_API int PS_set_seq_no ( tag_t  parent,
tag_t  occurrence,
const char *  seq_no 
)

Sets the sequence number of an occurrence.

Note:
Sequence numbers are alphanumeric and are therefore stored as text strings.
If necessary this function will load the parent BOMView Revision and lock it for modify. Note that this function modifies the occurrence in the loaded representation of the BOMView Revision only. The modification will only be propagated to the database when the parent BOMView Revision is saved using AOM_save.
Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
seq_no  (I) The sequence number as a string

PS_API int PS_set_variant_data ( tag_t  parent,
tag_t  occurrence,
tag_t  variant_expression_block 
)

Sets the variant condition for this occurrence to be the specified variant expression block. To clear the variant condition, call this routine passing in a NULLTAG value.

Parameters:
parent  (I) Tag of the occurrence's parent BOMView Revision
occurrence  (I) Tag of the occurrence
variant_expression_block  (I) POM object holding the variant condition. Go to bom.h for routines to manipulate a variant expression block.

PS_API int PS_system_default_bom_view_name ( tag_t  item,
tag_t  view_type,
char **  name 
)

Creates the system default name for a BOMView. The name is of the form "<Item ID>-<view type name>" (e.g., 100-Design).

Note:
This function is called by the default implementation of the USER_ps_default_bom_view_name user exit. It should only ever be required for customizing versions of this user exit. It should never be called directly to create a BOMView name; PS_default_bom_view_name should be used instead.

If the view type argument is NULLTAG, the user's default view type is used.

Parameters:
item  (I) Tag of the Item the new BOMView is to be created for
view_type  (I) Tag of the intended type of the BOMView to be created
name  (OF)

PS_API int PS_system_default_bvr_name ( tag_t  item_revision,
tag_t  view_type,
char **  name 
)

Creates the system default name for a BOMView Revision. The name is of the form "<Item Revision ID>-<view type name>", e.g. "100/A-Design."

Note:
This function is called by the default implementation of the user exit USER_ps_default_bvr_name. It should only ever be required for customizing versions of this user exit. It should never be called directly to create a BOMView Revision name; PS_default_bvr_name should be used instead.

If the view type argument is NULLTAG, the user's default view type is used.

Parameters:
item_revision  (I) Tag of the Item Revision of the BOMView Revision
view_type  (I) Tag of the view type of the BOMView Revision
name  (OF)

PS_API int PS_verify_occurrence_conditions ( tag_t  parent_rev_tag,
tag_t  child_rev_tag 
)

Validate if the parent and the child satisfy occurrence conditions

Parameters:
parent_rev_tag  (I)
child_rev_tag  (I)

PS_API int PS_view_type_ask_default_occurrence_type ( tag_t  view_type_tag,
tag_t *  occ_type_tag 
)

Returns the default occurrence type for this view type, if defined

Parameters:
view_type_tag  (I)
occ_type_tag  (O)

PS_API int PS_view_type_ask_valid_occurrence_types ( tag_t  type_tag,
tag_t **  valid_occs,
int *  count 
)

Returns the list of valid occurrence types for this view type, if defined

Parameters:
type_tag  (I)
valid_occs  (O)
count  (O)

PS_API int PS_view_type_extent ( int *  n_types,
tag_t **  view_types 
)

Returns the list of BOMview types valid for this site.

Parameters:
n_types  (O) Number of view types in the list
view_types  (OF) n_types Returned array of view type tags

PS_API int PS_where_used_all ( tag_t  target_tag,
int  n_levels,
int *  n_parents,
int **  levels,
tag_t **  parents 
)

Returns a list of all Item Revision and occurrence groups having structure which references the specified Item Revision; either with a precise reference to the Item Revision itself, or via an imprecise reference to the Item of which it is a revision.

The following figure shows a where used tree structure to illustrate the result of a where used search on 6413/C.

psfi01.gif

Calling a where used function on Item Revision 6413/C in the above example will return the following arrays:

indexlevelparent
0 1 6628/A
1 2 8128/A
2 2 6880/D
3 3 5605/C
4 3 6807/A
5 4 5955/A
6 3 4899/A
7 4 5955/A
8 1 4064/A
9 2 5546/B
10 3 3336/A

Note that as 5955/A includes two different sub-assemblies both of which ultimately use 6413/C, 5955/A appears twice to indicate the different paths through the usage tree.

To extract 'top-level-only' results from a where used, you need to do the following: 1. Call the appropriate where used function (PS_where_used_all, PS_where_used_precise, or PS_where_used_configured) passing n_levels=PS_where_used_all_levels to give you where used at all levels. 2. Process this result to identify only those entries that are 'top level'. If a particular entry is _not_ a top level, then you expect the following entry to have a value of level one greater than this one. So, it follows that if the following entry has a value of level that is _not_ one greater than the current one, or (special case) it's the last entry on the array, then that must be a top level. So for example this could be coded as:

PS_where_used_all( item_revision, PS_where_used_all_levels, &n_parents, &levels, &parents ); int index; for ( index = 0; index < n_parents; index++ ) { if ( index == n_parents - 1 || levels[index] >= levels[index+1] ) { parents[index] is a top level item rev. Display result or whatever. } else { Not a top level so ignore. } }

Parameters:
target_tag  (I) Tag of the object whose parents are sought
n_levels  (I) Depth of search. PS_where_used_all_levels means report all grandparents up to top level products (for example, those assemblies which are not part of any larger assembly).
n_parents  (O) Total number of parent Item Revisions found
levels  (OF) n_parents Array containing the level of each parent found, starting from 1 for an immediate parent of the specified Item Revision.
parents  (OF) n_parents Array of tags of occ grps and/or item revs if target_tag is occ grp, else only item revs if target_tag is Item Revision

PS_API int PS_where_used_configured ( tag_t  target_tag,
tag_t  rev_rule,
int  n_levels,
int *  n_parents,
int **  levels,
tag_t **  parents 
)

Returns a list of all the Item Revisions having structure which references the specified Item Revision, in the context of the specified Revision Rule.

NOTE: If preference PS_wu_configd_imprecise_only is set to true, and the specified Revision Rule contains only non-precise entries, referencing Item Revisions which are not themselves configured by the Revision Rule will be omitted.

Parameters:
target_tag  (I) Tag of the object whose parents are sought
rev_rule  (I) Tag of the Revision Rule
n_levels  (I) Depth of search. PS_where_used_all_levels means report all grandparents up to top level products (for example, those assemblies which are not part of any larger assembly).
n_parents  (O) The total number of parent Item Revisions found
levels  (OF) n_parents Array containing the level of each parent found, starting from 1 for an immediate parent of the specified Item Revision
parents  (OF) n_parents Array of tags of occ grps and/or item revs if target_tag is occ grp, else only item revs if target_tag is Item Revision

PS_API int PS_where_used_precise ( tag_t  target_tag,
int  n_levels,
int *  n_parents,
int **  levels,
tag_t **  parents 
)

Returns a list of all the Item Revisions having structure with a precise reference to the specified Item Revision.

Parameters:
target_tag  (I) Tag of the object whose parents are sought
n_levels  (I) Depth of search. PS_where_used_all_levels means report all grandparents up to top level products (for example, those assemblies which are not part of any larger assembly).
n_parents  (O) Total number of parent Item Revisions found
levels  (OF) n_parents Array containing the level of each parent found, starting from 1 for an immediate parent of the specified Item Revision
parents  (OF) n_parents Array of tags of occ grps and/or item revs if target_tag is occ grp, else only item revs if target_tag is Item Revision