You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
552 lines
24 KiB
552 lines
24 KiB
/*==============================================================================
|
|
Copyright (c) 2003-2005 UGS Corporation
|
|
Unpublished - All Rights Reserved
|
|
==============================================================================*/
|
|
|
|
/**
|
|
@file
|
|
|
|
Definition of structures and functions prototypes
|
|
associated with RESERVATION ITK module.
|
|
*/
|
|
|
|
/* */
|
|
|
|
/**
|
|
@defgroup RES Reservation
|
|
|
|
The reservation (RES) ITK functions provide check-out, check-in, transfer check-out,
|
|
cancel check-out, list check-out, notification list, and check-out history functionality.
|
|
They also provide information about ImanReservation objects that are created when objects are checked out.
|
|
An ImanReservation object is associated with each checked out object via an IMAN_RES_checkout GRM relation.
|
|
|
|
Not all objects can be checked out. The following classes and their sub-classes are valid for check-out:
|
|
<UL>
|
|
<LI>Dataset
|
|
<LI>Folder
|
|
<LI>Form
|
|
<LI>Item
|
|
<LI>ItemRevision
|
|
<LI>PSBOMView
|
|
<LI>PSBOMViewRevision
|
|
</UL>
|
|
|
|
To use reservation ITK functions, include the res_itk.h file in the source code.
|
|
|
|
The ImanReservation class has the following significant attributes:
|
|
|
|
<table>
|
|
<tr><td>Attribute </td><td>Description </td></tr>
|
|
<tr><td>Reason </td><td>Descriptive character string, holding the check-out purpose. </td></tr>
|
|
<tr><td>Change ID </td><td>Character string. </td></tr>
|
|
In previous Teamcenter Engineering releases this was referred to as Project ID.
|
|
Typically, this will be used to reference a change proposal job name. </td></tr>
|
|
<tr><td>Reservation Type </td><td>Integer that indicates whether check-out is with or without export.
|
|
This attribute can have the following values: <br>
|
|
#RES_EXCLUSIVE_RESERVE (check-out only)<br>
|
|
#RES_EXPORT_FILE (check-out with export) </td></tr>
|
|
<tr><td>Export Directory Name</td><td>Character string used if a dataset is checked out with export.
|
|
If so, this attribute holds the full OS directory path that
|
|
the dataset was exported to. </td></tr>
|
|
<tr><td>Reservation State </td><td>Integer that holds ImanReservation object current check-out state.
|
|
This attribute can have the following values:
|
|
|
|
#RES_RESERVE (state indicating associated object is checked out)<br>
|
|
#RES_UNRESERVE (state indicating associated object is not checked out) </td></tr>
|
|
<tr><td>Notification List </td><td>VLA containing the tags of users that wish to be notified when
|
|
the associated object's check-out status changes. </td></tr>
|
|
<tr><td>User </td><td>Tag to the user that currently holds the associated object's check-out.</td></tr>
|
|
<tr><td>Date </td><td>A date_t that holds the date of the current check-out. </td></tr>
|
|
</table>
|
|
|
|
@{
|
|
*/
|
|
|
|
/**
|
|
@name Reservation states stored in the reservation object
|
|
@{
|
|
*/
|
|
#define RES_RESERVE 0
|
|
#define RES_UNRESERVE 1
|
|
/** @} */
|
|
|
|
/**
|
|
Not a reservation state stored in the reservation object,
|
|
it is used by UIF for display reasons only.
|
|
You are advised not to use it.
|
|
*/
|
|
#define RES_RESERVE_AND_EXPORT 3
|
|
|
|
/**
|
|
@name Reservation messages to be used with Method
|
|
@{
|
|
*/
|
|
#define RES_Type "ImanReservation"
|
|
|
|
#define RES_checkout_msg "RES_checkout"
|
|
#define RES_checkin_msg "RES_checkin"
|
|
#define RES_cancel_checkout_msg "RES_cancel_checkout"
|
|
#define RES_transfer_checkout_msg "RES_transfer_checkout"
|
|
#define RES_notification_msg "RES_notification"
|
|
/** @} */
|
|
|
|
/**
|
|
@name Reservation types
|
|
@{
|
|
*/
|
|
|
|
/**
|
|
Checkout object with export option.
|
|
*/
|
|
#define RES_EXPORT_FILE 1
|
|
/**
|
|
This indicates a regular long term check-out.
|
|
*/
|
|
#define RES_EXCLUSIVE_RESERVE 2
|
|
/**
|
|
This is used by NX/Manager to avoid remote check-out.
|
|
*/
|
|
#define RES_EXCLUSIVE_LOCAL_RESERVE 3
|
|
/** @} */
|
|
|
|
/** @if DOX_IGNORE
|
|
Subrata PR#420726 - RES_SHORT_TERM_RESERVE is being moved in here
|
|
from res_internal.h. It is a published reservation type now.
|
|
@endif */
|
|
#define RES_SHORT_TERM_RESERVE 5
|
|
|
|
/** @if DOX_IGNORE
|
|
kulkaamo PR#6567666 - RES_SHORT_TERM_SYSTEM_RESERVE is defined
|
|
res_internal.h. as it should not be published Adding a note in
|
|
res_itk.h so that same number (6) should not be used again
|
|
|
|
#define RES_SHORT_TERM_SYSTEM_RESERVE 6
|
|
@endif */
|
|
|
|
#ifndef RES_ITK_H_INCLUDED
|
|
#define RES_ITK_H_INCLUDED
|
|
|
|
#include <tc/tc_startup.h>
|
|
#include <ss/ss_const.h>
|
|
#include <tccore/workspaceobject.h>
|
|
#include <res/libres_exports.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"{
|
|
#endif
|
|
|
|
/**
|
|
This function returns the count and list of objects referencing (connected to) the reservation object.
|
|
At present only one object is connected.
|
|
*/
|
|
extern RES_API int RES_ask_reserved_object (
|
|
tag_t reservation_tag, /**< (I) */
|
|
int* tag_count, /**< (O) */
|
|
tag_t** reserved_object_tags /**< (OF) tag_count */
|
|
);
|
|
|
|
|
|
/**
|
|
Retrieves the reason attribute of the reservation object
|
|
*/
|
|
extern RES_API int RES_ask_reason2 (
|
|
tag_t reservation_tag, /**< (I) */
|
|
char **reason /**< (OF) */
|
|
);
|
|
|
|
/**
|
|
Queries if reservation object is set to have file(s) exported when the object is checked out.
|
|
*/
|
|
extern RES_API int RES_ask_export_on_checkout (
|
|
tag_t reservation_tag, /**< (I) */
|
|
logical* export_flag /**< (O) @c true if the reservation is setup to export file on checkout */
|
|
);
|
|
|
|
|
|
|
|
/**
|
|
Retrieves the export directory from a reservation object.
|
|
*/
|
|
extern RES_API int RES_ask_exp_directory2 (
|
|
tag_t reservation_tag, /**< (I) */
|
|
char **directory /**< (OF) */
|
|
);
|
|
|
|
/**
|
|
Retrieves the reservation type of the reservation object
|
|
*/
|
|
extern RES_API int RES_ask_reservation_type (
|
|
tag_t reservation_tag, /**< (I) */
|
|
int* reservation_type /**< (O) */
|
|
);
|
|
|
|
/**
|
|
This function is used to return the reservation state of a reservation object.
|
|
The reservation_state can be one of the following states: #RES_RESERVE or #RES_UNRESERVE.
|
|
*/
|
|
extern RES_API int RES_ask_reservation_state (
|
|
tag_t reservation_tag, /**< (I) */
|
|
int* reservation_state /**< (O) */
|
|
);
|
|
|
|
/**
|
|
Allocates an array of tags and stores in the array all of the reservation objects in the database.
|
|
|
|
The caller is responsible for deallocating the array of tags.
|
|
*/
|
|
extern RES_API int RES_extent_reservation (
|
|
int* tag_count, /**< (O) The size of the array */
|
|
tag_t** reservation_tags /**< (OF) tag_count The array of tags */
|
|
);
|
|
|
|
/**
|
|
Finds reservation objects that are owned by the input user.
|
|
It is the caller's responsibility to free the array of tags passed as the output parameter by this function.
|
|
*/
|
|
extern RES_API int RES_find_reservations_by_user (
|
|
tag_t user_tag, /**< (I) */
|
|
int* tag_count, /**< (O) */
|
|
tag_t** reservation_tags /**< (OF) tag_count */
|
|
);
|
|
|
|
/**
|
|
Finds reservation objects that are owned by the input group.
|
|
It is the caller's responsibility to free the array of tags passed as the output parameters by this function.
|
|
*/
|
|
extern RES_API int RES_find_reservations_by_group (
|
|
tag_t group_tag, /**< (I) */
|
|
int* tag_count, /**< (O) */
|
|
tag_t** reservation_tags /**< (OF) tag_count */
|
|
);
|
|
|
|
/**
|
|
This function returns the user and group by whom the input object is checked out.
|
|
Note that with the 3.4 revised implementation of the reservation class,
|
|
the group tag has lost its importance, it's the user that is important.
|
|
We still store the group for compatibility with existing customer ITK code.
|
|
Note that after Iman 4.0, either the user tag or the group tag will be #NULLTAG.
|
|
This will be the case after group checkout is implemented,
|
|
so that either a reservation is held by a particular group (user would be #NULLTAG)
|
|
or the reservation is held by a particular user (group will be #NULLTAG).
|
|
*/
|
|
extern RES_API int RES_who_checked_object_out (
|
|
tag_t object_tag, /**< (I) */
|
|
tag_t* user_tag, /**< (O) */
|
|
tag_t* group_tag /**< (O) */
|
|
);
|
|
|
|
|
|
/**
|
|
Checks out the input object.
|
|
The other arguments set attributes in the ImanReservation object that is created as a result of a check-out.
|
|
*/
|
|
extern RES_API int RES_checkout2 (
|
|
tag_t object_tag, /**< (I) Object being checked out */
|
|
const char *reason, /**< (I) The reservation reason. */
|
|
const char *change_id, /**< (I) The System change_id/project_id. This can be passed as a NULL pointer. */
|
|
const char *dir_name, /**< (I) The export directory for the checked-out object. */
|
|
int reservation_type /**< (I) This should be set to #RES_EXCLUSIVE_RESERVE for regular check-out,
|
|
or set to #RES_EXPORT_FILE for check-out with export (datasets only). */
|
|
);
|
|
|
|
/**
|
|
Checks out @p object for @p user. If @p user is #NULLTAG it will checkout @p object for the logged in user.
|
|
The other arguments set attributes in the ImanReservation object that is created as a result of a check-out.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success
|
|
<li>#RES_NO_OBJECT_TO_RESERVE if @p object is #NULLTAG
|
|
<li>#RES_OBJECT_IS_RESERVED if @p object is already reserved
|
|
<li>#RES_UNSUPPORTED_TYPE if @p object does not support reservation
|
|
<li>#RES_INVALID_RESERVATION_TYPE if @p reservation_type is invalid
|
|
<li>#AM_invalid_tag if @p user is invalid
|
|
<li>#POM_access_denied if @p user has no write access to @p object
|
|
<li>#RES_RESERVE_TO_OTHER_SITE if @p object is checked out to another site
|
|
</ul>
|
|
*/
|
|
extern RES_API int RES_checkout_for_user(
|
|
tag_t object, /**< (I) The object being checked out. */
|
|
const char *reason, /**< (I) The reservation reason. */
|
|
const char *change_id, /**< (I) The system change_id/project_id. This can be passed as a NULL pointer. */
|
|
const char *dir_name, /**< (I) The export directory for the checked-out object. */
|
|
int reservation_type, /**< (I) This should be set to #RES_EXCLUSIVE_RESERVE for regular check-out,
|
|
or set to #RES_EXPORT_FILE for check-out with export (only for datasets). */
|
|
tag_t user /**< (I) The user for which the object is being checked-out. It can be #NULLTAG. */
|
|
);
|
|
|
|
/**
|
|
Checks in the input object.
|
|
*/
|
|
extern RES_API int RES_checkin (
|
|
tag_t obj_tag /**< (I) Object being checked out */
|
|
);
|
|
|
|
/**
|
|
Cancels the check-out of the input object.
|
|
Cancel check-out is only valid for datasets,
|
|
and it causes the dataset to be restored to its precheck-out state.
|
|
copy_flag is used to specify whether the current modified dataset is to be saved or not.
|
|
If copy_flag is true, then the current state of the dataset will be copied to
|
|
the user's Newstuff folder only if the dataset has been versioned (modified) since it was checked out.
|
|
If copy_flag is false, then no copy will be made.
|
|
*/
|
|
extern RES_API int RES_cancel_checkout (
|
|
tag_t object_tag, /**< (I) Object being checked out */
|
|
logical copy_flag /**< (I) Indicates whether a modified dataset should be saved,
|
|
before its contents are restored to its pre check-out state. */
|
|
);
|
|
|
|
/**
|
|
Transfers the check-out of the object to the input user and group.
|
|
Currently the group tag is not important and we allow it to be set to #NULLTAG.
|
|
The group tag may become more significant in a later release if we implement group check-outs.
|
|
*/
|
|
extern RES_API int RES_transfer_checkout (
|
|
tag_t object_tag, /**< (I) Unique identifier (tag) of object whose check-out
|
|
(reservation object) is being transferred */
|
|
tag_t user_tag, /**< (I) Unique identifier (tag) of new user to receive object check-out
|
|
(exclusive write access) */
|
|
tag_t group_tag /**< (I) This argument is not currently significant,
|
|
and #NULLTAG is the recommended value */
|
|
);
|
|
|
|
/**
|
|
This function provides a list of all the object tags of the object that a user currently has checked out.
|
|
Only system administrators will be allowed to list the check-outs of another user.
|
|
*/
|
|
extern RES_API int RES_list_checkout (
|
|
tag_t user_tag, /**< (I) Unique identifier (tag) of user whose checked-out objects is to be listed */
|
|
int* tag_count, /**< (O) Number of objects that user has in list */
|
|
tag_t** object_tags /**< (OF) tag_count VLA of object tags, memory must be freed by the function caller */
|
|
);
|
|
|
|
/**
|
|
This function determines if a object is checked out.
|
|
*/
|
|
extern RES_API int RES_is_checked_out (
|
|
tag_t object_tag, /**< (I) Unique identifier (tag) of object that you're inquiring on */
|
|
logical* is_reserved /**< (O) @c true if object is checked out, otherwise @c false. */
|
|
);
|
|
|
|
/**
|
|
This function is used to check if an object is modifiable by the login user,
|
|
in terms of a reservation.
|
|
An object is modifiable if it is not checked-out or
|
|
it is checked-out by the current login user and not exported.
|
|
|
|
@note ACL checks for the correct access are not made here,
|
|
instead this function would supplement such an access check.
|
|
This function returns #ITK_ok if the object is modifiable in terms of reservations.
|
|
Otherwise, an integer error code will be returned.
|
|
*/
|
|
extern RES_API int RES_assert_object_modifiable (
|
|
tag_t object_tag /**< (I) Unique identifier (tag) of object that you're inquiring on */
|
|
);
|
|
|
|
/**
|
|
This function returns the list of user's tags, for the users in the reservation object notification list.
|
|
*/
|
|
extern RES_API int RES_ask_notifylist (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of the
|
|
reservation object that you're inquiring on */
|
|
int* no_users, /**< (O) Number of user tags in the list */
|
|
tag_t** notifylist /**< (OF) no_users List of user tags,
|
|
memory must be freed by caller of this function */
|
|
);
|
|
|
|
/**
|
|
This function adds the input user to the input reservation's notification list.
|
|
*/
|
|
extern RES_API int RES_add_to_notifylist (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you want to update */
|
|
tag_t user_tag /**< (I) Unique identifier (tag) of user to be added to the notification list */
|
|
);
|
|
|
|
/**
|
|
This function removes the input user from the input reservation's notification list.
|
|
|
|
@note If the last user is removed from the notification list using this ITK call,
|
|
then you must check if the reservation object must be deleted.
|
|
If the reservation's state is not equal to #RES_RESERVE (use #RES_ask_reservation_state)
|
|
and the notification list is empty (use #RES_ask_notifylist)
|
|
then the reservation object should be deleted using #AOM_delete only.
|
|
These checks were not internalized as it would have been misleading and against ITK standards to have
|
|
an ITK function that modifies an object attribute,
|
|
and have that same call in some circumstances delete the object itself.
|
|
*/
|
|
extern RES_API int RES_remove_from_notifylist (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you want to update */
|
|
tag_t user_tag /**< (I) Unique identifier (tag) of user to be removed from the notification list */
|
|
);
|
|
|
|
/**
|
|
Retrieves the latest user by whom the object connected to the input reservation object is checked out.
|
|
*/
|
|
extern RES_API int RES_ask_user (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you're inquiring on */
|
|
tag_t* user_tag /**< (O) Unique identifier (tag) of user that holds the check-out */
|
|
);
|
|
|
|
/**
|
|
Retrieves the latest group by whom the object connected to the input reservation object is checked out.
|
|
With the current implementation users check out objects and so the group is not important,
|
|
therefore this function may return a #NULLTAG for group_tag.
|
|
In the future we may implement group check-out and the group will then become significant.
|
|
*/
|
|
extern RES_API int RES_ask_group (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you're inquiring on */
|
|
tag_t* group_tag /**< (O) Unique identifier (tag) of group that holds the check-out */
|
|
);
|
|
|
|
/**
|
|
This function returns the last date of check-out for the object associated with the input reservation object.
|
|
*/
|
|
extern RES_API int RES_ask_reservation_date (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you're inquiring on */
|
|
date_t* date /**< (O) Date object was last checked out */
|
|
);
|
|
|
|
|
|
/**
|
|
Retrieves the change ID from a reservation object.
|
|
|
|
@note The project_id and change_id attributes are one and the same attribute in the reservation object.
|
|
Change IDs are not always setfor they are an optional entry on the check-out dialog box.
|
|
*/
|
|
extern RES_API int RES_ask_change_id2 (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of the
|
|
reservation object that you're inquiring on */
|
|
char **change_id /**< (OF) Change ID used for check-out */
|
|
);
|
|
|
|
/**
|
|
Retrieves the reservation object for @p object_tag.
|
|
@note This operation will return a #NULLTAG for @p reservation_tag (even if it is associated with @p object_tag) if the reservation state is unreserved.
|
|
|
|
@returns
|
|
<ul>
|
|
<li>#ITK_ok on success
|
|
<li>#POM_invalid_tag if @p object_tag is a #NULLTAG or not a persistent object tag.
|
|
</ul>
|
|
*/
|
|
extern RES_API int RES_ask_reservation_object (
|
|
tag_t object_tag, /**< (I) Unique identifier (tag) of object that you're inquiring on */
|
|
tag_t* reservation_tag /**< (O) Unique identifier (tag) of the associated reservation object */
|
|
);
|
|
|
|
/**
|
|
This function gets the reservation audit file associated with the specified object.
|
|
If the object has never been checked out, no audit file exists.
|
|
Therefore, the file_tag returned will be #NULLTAG.
|
|
*/
|
|
extern RES_API int RES_ask_audit_file(
|
|
tag_t object_tag, /**< (I) Unique identifier (tag) of object being asked */
|
|
tag_t* file_tag /**< (O) Unique identifier (tag) of the associated audit file object */
|
|
);
|
|
|
|
/**
|
|
Retrieves the audit history for the specified object.
|
|
If the object has never been checked, out no history events exist.
|
|
In this case the event_count will be 0 and the field arrays will be null.
|
|
On error, the event_count will be 0 and the field_arrays will be null.
|
|
*/
|
|
extern RES_API int RES_ask_audit_history(
|
|
tag_t object_tag, /**< (I) Unique identifier (tag) of auditable object. */
|
|
int* event_count,/**< (O) Number of events in the history field arrays. */
|
|
char*** dates, /**< (OF) Date and time. */
|
|
char*** users, /**< (OF) User information. */
|
|
char*** actions, /**< (OF) Reservation action. */
|
|
char*** change_ids, /**< (OF) User change identifier. */
|
|
char*** reasons /**< (OF) User comment. */
|
|
);
|
|
|
|
/**
|
|
This function saves the reservation object.
|
|
The reservation object used in pre Version 3.4 used a different object model than the current one.
|
|
The old model performing an #AOM_save on the reservation led to the check-out functionality being
|
|
triggered for the associated object. With the new model,
|
|
the new reservation object is saved prior to it being associated to the check-out object via a GRM relation.
|
|
|
|
In order to support legacy code written prior to Version 3.4,
|
|
#AOM_save has been set up to support the old model.
|
|
However, if you're creating new code using the new model, you should not use #AOM_save.
|
|
It will work but it will be inefficient.
|
|
Instead, use either this function or #POM_save_instances,
|
|
which will save the reservation object without triggering an extraneous check-out mechanism.
|
|
*/
|
|
extern RES_API int RES_save_reservation (
|
|
tag_t reservation_tag, /**< (I) Unique identifier (tag) of reservation object that you're updating */
|
|
logical whether_to_unload /**< (I) Logical flag indicating whether or not the system should unload */
|
|
);
|
|
|
|
/**
|
|
Initializes all the Reservation messages:
|
|
RES_checkout_msg, RES_checkin_msg, RES_cancel_checkout_msg, RES_transfer_checkout_msg and RES_notification_msg are initiliazed.
|
|
*/
|
|
extern RES_API int RES_init_module ();
|
|
|
|
/** @} */
|
|
|
|
/**
|
|
@name Utility Functions
|
|
|
|
These are utility functions that support Remote CICO funtionality which allow checkouts on replica objects
|
|
@{
|
|
*/
|
|
|
|
extern RES_API int RES_list_remote_checkout(
|
|
tag_t remote_site, /**< (I) */
|
|
const char* remote_user, /**< (I) */
|
|
const char* remote_group, /**< (I) */
|
|
int* tag_count, /**< (O) */
|
|
tag_t** object_tags /**< (OF) tag_count */
|
|
);
|
|
|
|
extern RES_API int RES_list_replica_checkout(
|
|
tag_t remote_site, /**< (I) */
|
|
tag_t local_user_tag, /**< (I) */
|
|
tag_t local_group_tag, /**< (I) */
|
|
int* tag_count, /**< (O) */
|
|
tag_t** object_tags /**< (OF) tag_count */
|
|
);
|
|
|
|
extern RES_API int RES_is_checked_out_by_remote_user(
|
|
tag_t object_tag, /**< (I) */
|
|
logical* is_reserved /**< (O) */
|
|
);
|
|
|
|
extern RES_API int RES_is_checked_out_replica(
|
|
tag_t object_tag, /**< (I) */
|
|
logical* is_reserved /**< (O) */
|
|
);
|
|
|
|
extern RES_API int RES_ask_remote_user_and_group(
|
|
tag_t reservation_tag, /**< (I) */
|
|
char** remote_user, /**< (OF) */
|
|
char** remote_group /**< (OF) */
|
|
);
|
|
|
|
extern RES_API int RES_ask_remote_site(
|
|
tag_t reservation_tag, /**< (I) */
|
|
tag_t* remote_site /**< (O) */
|
|
);
|
|
|
|
/**
|
|
* This function determines if an object is checkoutable or not.
|
|
* @return
|
|
**/
|
|
extern RES_API int RES_is_checkoutable(
|
|
tag_t object_tag, /**< (I) Tag of a selected object */
|
|
logical* is_checkoutable /**< (O) Indicates if object is checkoutable or not */
|
|
);
|
|
/** @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#include <res/libres_undef.h>
|
|
|
|
#endif
|