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

Reservation

Detailed Description

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:

To use reservation ITK functions, include the res_itk.h file in the source code.

The ImanReservation class has the following significant attributes:

Attribute Description
Reason Descriptive character string, holding the check-out purpose.
Change ID Character string. In previous Teamcenter Engineering releases this was referred to as Project ID. Typically, this will be used to reference a change proposal job name.
Reservation Type Integer that indicates whether check-out is with or without export. This attribute can have the following values:
RES_EXCLUSIVE_RESERVE (check-out only)
RES_EXPORT_FILE (check-out with export)
Export Directory NameCharacter 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.
Reservation State 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)
RES_UNRESERVE (state indicating associated object is not checked out)

Notification List VLA containing the tags of users that wish to be notified when the associated object's check-out status changes.
User Tag to the user that currently holds the associated object's check-out.
Date A date_t that holds the date of the current check-out.

Modules

Reservation states stored in the reservation object

Reservation messages to be used with Method

Reservation types

Defines

Functions

Define Documentation

#define RES_cancel_checkout_msg   "RES_cancel_checkout"

Definition at line 88 of file res_itk.h.

#define RES_checkin_msg   "RES_checkin"

Definition at line 87 of file res_itk.h.

#define RES_checkout_msg   "RES_checkout"

Definition at line 86 of file res_itk.h.

#define RES_EXCLUSIVE_LOCAL_RESERVE   3

Definition at line 99 of file res_itk.h.

#define RES_EXCLUSIVE_RESERVE   2

Definition at line 98 of file res_itk.h.

#define RES_EXPORT_FILE   1

Definition at line 97 of file res_itk.h.

#define RES_notification_msg   "RES_notification"

Definition at line 90 of file res_itk.h.

#define RES_RESERVE   0

Definition at line 69 of file res_itk.h.

#define RES_RESERVE_AND_EXPORT   3

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.

Definition at line 78 of file res_itk.h.

#define RES_SHORT_TERM_RESERVE   5

Definition at line 106 of file res_itk.h.

#define RES_transfer_checkout_msg   "RES_transfer_checkout"

Definition at line 89 of file res_itk.h.

#define RES_Type   "ImanReservation"

Definition at line 84 of file res_itk.h.

#define RES_UNRESERVE   1

Definition at line 70 of file res_itk.h.

Function Documentation

RES_API int RES_add_to_notifylist ( tag_t  reservation_tag,
tag_t  user_tag 
)

This function adds the input user to the input reservation's notification list.

Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you want to update
user_tag  (I) Unique identifier (tag) of user to be added to the notification list

RES_API int RES_ask_audit_file ( tag_t  object_tag,
tag_t *  file_tag 
)

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.

Parameters:
object_tag  (I) Unique identifier (tag) of object being asked
file_tag  (O) Unique identifier (tag) of the associated audit file object

RES_API int RES_ask_audit_history ( tag_t  object_tag,
int *  event_count,
char ***  dates,
char ***  users,
char ***  actions,
char ***  change_ids,
char ***  reasons 
)

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

Parameters:
object_tag  (I) Unique identifier (tag) of auditable object.
event_count  (O) Number of events in the history field arrays.
dates  (OF) Date and time.
users  (OF) User information.
actions  (OF) Reservation action.
change_ids  (OF) User change identifier.
reasons  (OF) User comment.

RES_API int RES_ask_change_id ( tag_t  reservation_tag,
char  change_id[WSO_name_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use RES_ask_change_id2
Gets 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.
Parameters:
reservation_tag  (I) Unique identifier (tag) of the reservation object that you're inquiring on
change_id  (O) Change ID used for check-out

RES_API int RES_ask_change_id2 ( tag_t  reservation_tag,
char **  change_id 
)

Gets 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.
Parameters:
reservation_tag  (I) Unique identifier (tag) of the reservation object that you're inquiring on
change_id  (OF) Change ID used for check-out

RES_API int RES_ask_exp_directory ( tag_t  reservation_tag,
char  directory[SS_MAXPATHLEN+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use RES_ask_exp_directory2
Gets the export directory from a reservation object.
Parameters:
reservation_tag  (I)
directory  (O)

RES_API int RES_ask_exp_directory2 ( tag_t  reservation_tag,
char **  directory 
)

Gets the export directory from a reservation object.

Parameters:
reservation_tag  (I)
directory  (OF)

RES_API int RES_ask_export_on_checkout ( tag_t  reservation_tag,
logical *  export_flag 
)

Queries if reservation object is set to have file(s) exported when the object is checked out.

Parameters:
reservation_tag  (I)
export_flag  (O) Returns TRUE if the reservation is setup to export file on checkout

RES_API int RES_ask_group ( tag_t  reservation_tag,
tag_t *  group_tag 
)

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

Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you're inquiring on
group_tag  (O) Unique identifier (tag) of group that holds the check-out

RES_API int RES_ask_notifylist ( tag_t  reservation_tag,
int *  no_users,
tag_t **  notifylist 
)

This function returns the list of user's tags, for the users in the reservation object notification list.

Parameters:
reservation_tag  (I) Unique identifier (tag) of the reservation object that you're inquiring on
no_users  (O) Number of user tags in the list
notifylist  (OF) no_users List of user tags, memory must be freed by caller of this function

RES_API int RES_ask_reason ( tag_t  reservation_tag,
char  reason[WSO_desc_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use RES_ask_reason2
This function returns reason attribute of the reservation object
Parameters:
reservation_tag  (I)
reason  (O)

RES_API int RES_ask_reason2 ( tag_t  reservation_tag,
char **  reason 
)

This function returns reason attribute of the reservation object

Parameters:
reservation_tag  (I)
reason  (OF)

RES_API int RES_ask_reservation_date ( tag_t  reservation_tag,
date_t *  date 
)

This function returns the last date of check-out for the object associated with the input reservation object.

Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you're inquiring on
date  (O) Date object was last checked out

RES_API int RES_ask_reservation_object ( tag_t  object_tag,
tag_t *  reservation_tag 
)

Returns the reservation object of the input object. If a reservation object is not associated with the object, the reservation_tag will be set to NULLTAG.

Parameters:
object_tag  (I) Unique identifier (tag) of object that you're inquiring on
reservation_tag  (O) Unique identifier (tag) of the associated reservation object

RES_API int RES_ask_reservation_state ( tag_t  reservation_tag,
int *  reservation_state 
)

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.

Parameters:
reservation_tag  (I)
reservation_state  (O)

RES_API int RES_ask_reservation_type ( tag_t  reservation_tag,
int *  reservation_type 
)

This function returns the reservation type of the reservation object

Parameters:
reservation_tag  (I)
reservation_type  (O)

RES_API int RES_ask_reserved_object ( tag_t  reservation_tag,
int *  tag_count,
tag_t **  reserved_object_tags 
)

This function returns the count and list of objects referencing (connected to) the reservation object. At present only one object is connected.

Parameters:
reservation_tag  (I)
tag_count  (O)
reserved_object_tags  (OF) tag_count

RES_API int RES_ask_user ( tag_t  reservation_tag,
tag_t *  user_tag 
)

Returns the latest user by whom the object connected to the input reservation object is checked out.

Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you're inquiring on
user_tag  (O) Unique identifier (tag) of user that holds the check-out

RES_API int RES_assert_object_modifiable ( tag_t  object_tag  ) 

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.
Parameters:
object_tag  (I) Unique identifier (tag) of object that you're inquiring on

RES_API int RES_cancel_checkout ( tag_t  object_tag,
logical  copy_flag 
)

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.

Parameters:
object_tag  (I) Object being checked out
copy_flag  (I) Indicates whether a modified dataset should be saved, before its contents are restored to its pre check-out state.

RES_API int RES_checkin ( tag_t  obj_tag  ) 

Checks in the input object.

Parameters:
obj_tag  (I) Object being checked out

RES_API int RES_checkout ( tag_t  object_tag,
const char  reason[WSO_desc_size_c+1],
const char  change_id[WSO_name_size_c+1],
const char  dir_name[SS_MAXPATHLEN+1],
int  reservation_type 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use RES_checkout2
This function checks out the input object. The other arguments set attributes in the ImanReservation object that is created as a result of a check-out.
Parameters:
object_tag  (I) Object being checked out
reason  (I) Required text
change_id  (I) Optional system change_id/project_id
dir_name  (I)
reservation_type  (I) Set to RES_EXCLUSIVE_RESERVE for regular check-out, or set to RES_EXPORT_FILE for check-out with export (datasets only).

RES_API int RES_checkout2 ( tag_t  object_tag,
const char *  reason,
const char *  change_id,
const char *  dir_name,
int  reservation_type 
)

This function checks out the input object. The other arguments set attributes in the ImanReservation object that is created as a result of a check-out.

Parameters:
object_tag  (I) Object being checked out
reason  (I) Required text
change_id  (I) Optional system change_id/project_id
dir_name  (I)
reservation_type  (I) Set to RES_EXCLUSIVE_RESERVE for regular check-out, or set to RES_EXPORT_FILE for check-out with export (datasets only).

RES_API int RES_extent_reservation ( int *  tag_count,
tag_t **  reservation_tags 
)

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.

Parameters:
tag_count  (O) The size of the array
reservation_tags  (OF) tag_count The array of tags

RES_API int RES_find_reservations_by_group ( tag_t  group_tag,
int *  tag_count,
tag_t **  reservation_tags 
)

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.

Parameters:
group_tag  (I)
tag_count  (O)
reservation_tags  (OF) tag_count

RES_API int RES_find_reservations_by_user ( tag_t  user_tag,
int *  tag_count,
tag_t **  reservation_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.

Parameters:
user_tag  (I)
tag_count  (O)
reservation_tags  (OF) tag_count

RES_API int RES_init_module (  ) 

This function will initialize all the Reservation function that are implemented using Teamcenter Engineering Method mechanism. Currently there are three RES functions, RES_checkin, RES_checkout, and RES_cancel_checkout that are implemented using method.

RES_API int RES_is_checked_out ( tag_t  object_tag,
logical *  is_reserved 
)

This function determines if a object is checked out.

Parameters:
object_tag  (I) Unique identifier (tag) of object that you're inquiring on
is_reserved  (O) Returned value of TRUE if object is checked out, otherwise FALSE

RES_API int RES_list_checkout ( tag_t  user_tag,
int *  tag_count,
tag_t **  object_tags 
)

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.

Parameters:
user_tag  (I) Unique identifier (tag) of user whose checked-out objects is to be listed
tag_count  (O) Number of objects that user has in list
object_tags  (OF) tag_count VLA of object tags, memory must be freed by the function caller

RES_API int RES_remove_from_notifylist ( tag_t  reservation_tag,
tag_t  user_tag 
)

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.
Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you want to update
user_tag  (I) Unique identifier (tag) of user to be removed from the notification list

RES_API int RES_save_reservation ( tag_t  reservation_tag,
logical  whether_to_unload 
)

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.

Parameters:
reservation_tag  (I) Unique identifier (tag) of reservation object that you're updating
whether_to_unload  (I) Logical flag indicating whether or not the system should unload

RES_API int RES_transfer_checkout ( tag_t  object_tag,
tag_t  user_tag,
tag_t  group_tag 
)

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.

Parameters:
object_tag  (I) Unique identifier (tag) of object whose check-out (reservation object) is being transferred
user_tag  (I) Unique identifier (tag) of new user to receive object check-out (exclusive write access)
group_tag  (I) This argument is not currently significant, and NULLTAG is the recommended value

RES_API int RES_who_checked_object_out ( tag_t  object_tag,
tag_t *  user_tag,
tag_t *  group_tag 
)

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

Parameters:
object_tag  (I)
user_tag  (O)
group_tag  (O)