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

Teamcenter File
[System Administration]

Detailed Description

We use tags to refer to file objects. However, we use file descriptors when actually manipulating the file. A file descriptor is only valid between the time a file is created or the descriptor is asked for and the time that the file is closed. AOM functions work with Teamsenter Engineering Files because they are POM application objects. Include ss_const.h and tcfile.h to pass the correct SS_ constants to IMF routines.

Teamcenter enforces a rule where operating system files are never modified; instead, new revisions of them are created. Teamcenter does not let you open an existing file for write. You must first make a copy, then open the copy for write.

Modules

Defines

Typedefs

Functions

Define Documentation

#define IMF_filename_size_c   132

Definition at line 40 of file tcfile.h.

#define IMF_relative_path_size_c   240

Definition at line 41 of file tcfile.h.

Typedef Documentation

typedef SS_file_status IMF_file_status

Definition at line 44 of file tcfile.h.

typedef void* IMF_file_t

Definition at line 43 of file tcfile.h.

Function Documentation

SA_API int IMF_ask_file_descriptor ( tag_t  file_tag,
IMF_file_t *  file_descriptor 
)

Returns the file descriptor for the database file object.

Parameters:
file_tag  (I)
file_descriptor  (O)

SA_API int IMF_ask_file_pathname ( tag_t  file_tag,
int  mach_type,
char  pathname[SS_MAXPATHLEN] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_ask_file_pathname2
Returns the full pathname of the physical file on disk associated with the given TcFile. The format of the pathname will depend on the value of machine_type, it will be either SS_WNT_MACHINE or SS_UNIX_MACHINE.
Parameters:
file_tag  (I)
mach_type  (I)
pathname  (O)

SA_API int IMF_ask_file_pathname2 ( tag_t  file_tag,
int  mach_type,
char **  pathname 
)

Returns the full pathname of the physical file on disk associated with the given TcFile. The format of the pathname will depend on the value of machine_type, it will be either SS_WNT_MACHINE or SS_UNIX_MACHINE.

Parameters:
file_tag  (I)
mach_type  (I)
pathname  (OF)

SA_API int IMF_ask_file_tag ( IMF_file_t  file_descriptor,
tag_t *  file_tag 
)

Returns the tag of the database object for the given file descriptor.

Parameters:
file_descriptor  (I)
file_tag  (O)

SA_API int IMF_ask_original_file_name ( tag_t  file_tag,
char  name[IMF_filename_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_ask_original_file_name2
Asks for the original name of a file.

Restrictions: The file name should not exceed 30 characters long if the preference TC_truncate_file_name is set. Otherwise the limit should be the CFI limit of 128 chars.

Parameters:
file_tag  (I)
name  (O)

SA_API int IMF_ask_original_file_name2 ( tag_t  file_tag,
char **  name 
)

Asks for the original name of a file.

Restrictions: The file name should not exceed 30 characters long if the preference TC_truncate_file_name is set. Otherwise the limit should be the CFI limit of 128 chars.

Parameters:
file_tag  (I)
name  (OF)

SA_API int IMF_ask_relative_path ( tag_t  file_tag,
char  relative_path[IMF_relative_path_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_ask_relative_path2
Parameters:
file_tag  (I)
relative_path  (O)

SA_API int IMF_ask_relative_path2 ( tag_t  file_tag,
char **  relative_path 
)

Parameters:
file_tag  (I)
relative_path  (OF)

SA_API int IMF_ask_security_level ( void   ) 

Returns the current security level for a file system.

0 Normal file management
1 Full security
2 Partially secure (allows ITK routines to read files directly).

SA_API int IMF_ask_volume ( tag_t  fileTag,
tag_t *  volumeTag 
)

Returns the volume tag for the database file object.

Parameters:
fileTag  (I)
volumeTag  (O)

SA_API int IMF_close_file ( IMF_file_t  file_descriptor  ) 

Closes a file.

Parameters:
file_descriptor  (I)

SA_API int IMF_copy_file ( tag_t  file_tag,
const char *  new_filename,
tag_t *  new_file_tag,
IMF_file_t *  file_descriptor 
)

Creates a new file in the operating system and a new file object in the database that is a copy of the original file. This function leaves the file opened for read/write and locked. It returns both the tag and the file descriptor.

If new_filename is not NULL, then the string is used as the name of the file (if that name does not already exist). If new_filename is NULL, then a unique file name is automatically generated.

Parameters:
file_tag  (I)
new_filename  (I)
new_file_tag  (O)
file_descriptor  (O)

SA_API int IMF_create_file ( const char *  filename,
int  file_type,
tag_t *  file_tag,
IMF_file_t *  file_descriptor 
)

Creates a new file object in the database. An operating system file is not created. It is the responsibility of the application to create the file using the path name returned from IMF_ask_file_pathname. The file can also be created with the correct parameters with IMF_open_file. It returns both the tag and the file descriptor.

Parameters:
filename  (I) Not NULL - the string is used as the name of the file (if that name does not already exist).
NULL - a unique file name is automatically generated.
file_type  (I) SS_TEXT
SS_BINARY
SS_TRANSLATE | SS_BINARY
file_tag  (O)
file_descriptor  (O)

SA_API int IMF_expand_path ( const char *  oldpath,
char *  newpath 
)

Routine to expand a path. Any environment variables in the pathname are translated to their literal values.

Parameters:
oldpath  (I) Path (with environment variables) you wish to expand
newpath  (O) Expanded path name of the file

SA_API int IMF_export_file ( tag_t  file_tag,
const char *  pathname 
)

Puts an TcFile into the operating system at the input pathname. The pathname can be relative to the current working directory.

Parameters:
file_tag  (I)
pathname  (I)

SA_API int IMF_fmsfile_export ( tag_t  file_tag,
const char *  pathname 
)

Pre-requisite: The Preference Fms_BootStrap_Urls should be pointing to the FSC process serving the TC Volume. This function uses FMS to copy an Team Center Engineering File into the local system at the input pathname. The pathname can be relative to the current working directory

Parameters:
file_tag  (I)
pathname  (I)

SA_API int IMF_fmsfile_import ( const char *  osFileName,
const char *  newFilename,
int  fileType,
tag_t *  newFileTag,
IMF_file_t *  fileDescriptor 
)

Pre-requisite: The Preference Fms_BootStrap_Urls should be pointing to the FSC process serving the TC Volume. This function is used to bring existing files under the control of Teamcenter. It creates a new file in the operating system and a new TcFile object in the database, where the new operating system file is a copy of the input OS file. Further both new file and TcFile Object will be saved after successful import. It returns both the tag and the file descriptor.

Parameters:
osFileName  (I)
newFilename  (I) Not NULL - the string is used as the name of the file (if that name does not already exist).
NULL - a unique file name is automatically generated.
fileType  (I) SS_TEXT
SS_BINARY
SS_TRANSLATE | SS_BINARY
newFileTag  (O)
fileDescriptor  (O)

SA_API int IMF_get_absolute_transient_volume_file_path ( int  tier,
char *  ticket_string,
char **  ticket_file_path 
)

This function extracts the absolute path of the transient volume file from a ticket string.

An error VM_INVALID_SERVER_MODE (14164) will be returned if the value of the tier argument is neither 2 nor 4. An error VM_INVALID_TRANSIENT_TICKET (14150) will be returned if the ticket_string argument is not a valid FMS transient file ticket. An error PF_NOTFOUND (1700) will be returned if the preference Transient_Volume_RootDir does not exist.

Parameters:
tier  (I) The tier type to be used when requesting the Transient Volume Root Directory. Must be 2 or 4.
ticket_string  (I) The ticket string in its original form.
ticket_file_path  (OF) The extracted absolute file path of the transient volume file.

SA_API int IMF_get_transient_file_read_ticket ( int  file_type,
int  server_mode,
logical  deleteSW,
const char *  transient_volume_file_path,
char **  transient_volume_file_read_ticket 
)

This function obtains an FMS read ticket for a file in a transient volume.

Parameters:
file_type  (I) SS_TEXT < br> SS_BINARY
server_mode  (I) 2 for a 2-tier ticket, 4 for a 4-tier ticket.
deleteSW  (I) true to delete file from transient volume after reading it, false to retain file in transient volume after reading it.
transient_volume_file_path  (I) The absolute path to the file in the transient volume that is to be downloaded.
transient_volume_file_read_ticket  (OF) The FMS ticket generated from the above information.

SA_API int IMF_get_transient_volume_root_dir ( int  tier,
char **  transientVolRootDir 
)

This function obtains the Transient Volume Root Directory for the specified tier.

Parameters:
tier  (I) The tier type to be used when requesting the Transient Volume Root Directory. Must be 2 or 4.
transientVolRootDir  (OF) The Transient Volume Root Directory for the specified tier.

SA_API int IMF_import_file ( const char *  osFileName,
const char *  newFilename,
int  fileType,
tag_t *  newFileTag,
IMF_file_t *  fileDescriptor 
)

Pre-requisite: The Preference Fms_BootStrap_Urls should be pointing to the FSC process serving the TC Volume. This function is used to bring existing files under the control of Teamcenter. It creates a new file in the operating system and a new TcFile object in the database, where the new operating system file is a copy of the input OS file. The new file is closed and TcFile Object is locked for further modification. It returns both the tag and the file descriptor.

Parameters:
osFileName  (I)
newFilename  (I) Not NULL - the string is used as the name of the file (if that name does not already exist).
NULL - a unique file name is automatically generated.
fileType  (I) SS_TEXT
SS_BINARY
SS_TRANSLATE | SS_BINARY
newFileTag  (O)
fileDescriptor  (O)

SA_API int IMF_move_file ( tag_t  fileTag,
tag_t  volumeTag 
)

Moves the file to the given volume.

Parameters:
fileTag  (I)
volumeTag  (I)

SA_API int IMF_open_file ( IMF_file_t  file_descriptor,
int  ss_file_access_mode 
)

Opens the file for read or write.

Note:
Teamcenter does not let you open an existing file for write. You must first make a copy, then open the copy for write.
Parameters:
file_descriptor  (I)
ss_file_access_mode  (I) SS_RDONLY, SS_WRONLY, SS_APPEND or SS_RDWRITE

SA_API int IMF_read_file ( IMF_file_t  file_descriptor,
int  datatype_count,
int  data_type,
int *  items_read_count,
void *  items_read 
)

Reads a block of data from a file where a block is the number of bytes specified by the datatype_count parameter.

For data types SS_VOID, SS_CHAR, SS_WCHAR, and SS_BYTE this is the actual number of bytes specified by datatype_count. For all other data types it is datatype_count times the sizeof() the data_type.

The items_read parameter will return a pointer to the items retrieved. The items_read_count parameter will return the actual number of bytes read from the file.

Can only be used if the file referenced by file_descriptor is a binary file. Determination of the file type (i.e., text vs binary) is based upon how the file was created (e.g., using IMF_create_file or IMF_fmsfile_import). An attempt to read a text file with this will result in a VM_NO_READ error.

Parameters:
file_descriptor  (I) The file descriptor for the database file object.
datatype_count  (I) The number of bytes to read.
data_type  (I) SS_VOID, SS_CHAR, SS_WCHAR, SS_BYTE,
SS_SHORT, SS_LONG, SS_FLOAT, SS_DOUBLE
items_read_count  (O) The number of bytes read from the file.
items_read  (O) A pointer to the items read from the file.

SA_API int IMF_read_file_line ( IMF_file_t  file_descriptor,
char  text_line[SS_MAXLLEN] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_read_file_line2
Reads a line of text from an ASCII text file. The text up to and including the terminating newline character will be returned. The initial call to this function will return the first line in the text file. Each subsequent call will return the next line in the file. SS_EOF will be returned on calls following the last line of valid data.
Parameters:
file_descriptor  (I)
text_line  (O)

SA_API int IMF_read_file_line2 ( IMF_file_t  file_descriptor,
char **  text_line 
)

Reads a line of text from an ASCII text file. The text up to and including the terminating newline character will be returned. The initial call to this function will return the first line in the text file. Each subsequent call will return the next line in the file. SS_EOF will be returned on calls following the last line of valid data.

Parameters:
file_descriptor  (I)
text_line  (OF)

SA_API int IMF_replace_file ( tag_t  file_tag,
const char *  new_file_pathname,
logical  retain_orig_filename 
)

This method replaces the existing volume file associated with file_tag with a new OS file located under new_file_pathname. The replacement will not alter the volume path and file UID of the file_tag.

If retain_orig_filename is set to true, it sets the original file name of a given TcFile to the original file name of file_tag. No new ImanFile UID is created in the database.

This is intended for use with UG/Manager refile. Otherwise, the function IMF_replace_file_and_get_new_tag should be used.

Parameters:
file_tag  (I)
new_file_pathname  (I)
retain_orig_filename  (I)

SA_API int IMF_replace_file_and_get_new_tag ( tag_t  old_file_tag,
const char *  new_file_pathname,
logical  retain_orig_filename,
tag_t *  new_file_tag 
)

This method should be used in place of IMF_replace_file. This method imports an OS file located under new_file_pathname to new_file_tag. The volume and sd_path_location attributes of new_file_tag will be the same as that of old_file_tag.If retain_orig_filename is set to true, it sets the original file name of a given TcFile to the original file name of old_file_tag.

If the old file tag represents a standalone ImanFile object then nothing further needs to be done. If it represents the ImanFile object that is associated with a dataset then the following calls need to be made:

AOM_lock(dataset); AE_replace_dataset_named_ref(dataset, file_tag, reference_name, reference_type, new_file_tag); AE_save_myself(dataset); AOM_unlock(dataset);

Furthermore the old_file_tag can be deleted if it is not referenced anywhere.

Parameters:
old_file_tag  (I)
new_file_pathname  (I)
retain_orig_filename  (I)
new_file_tag  (O)

SA_API int IMF_set_original_file_name ( tag_t  file_tag,
const char  name[IMF_filename_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_set_original_file_name2
Sets the original file name of a given TcFile. Teamcenter uses this original file name when exporting the file.

Restrictions: The file name should not exceed 30 characters long if the preference TC_truncate_file_name is set. Otherwise the limit should be the CFI limit of 128 chars.

Parameters:
file_tag  (I)
name  (I)

SA_API int IMF_set_original_file_name2 ( tag_t  file_tag,
const char *  name 
)

Sets the original file name of a given TcFile. Teamcenter uses this original file name when exporting the file.

Restrictions: The file name should not exceed 30 characters long if the preference TC_truncate_file_name is set. Otherwise the limit should be the CFI limit of 128 chars.

Parameters:
file_tag  (I)
name  (I)

SA_API int IMF_set_relative_path ( tag_t  file_tag,
const char  relative_path[IMF_relative_path_size_c+1] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_set_relative_path2
Parameters:
file_tag  (I)
relative_path  (I)

SA_API int IMF_set_relative_path2 ( tag_t  file_tag,
const char *  relative_path 
)

Parameters:
file_tag  (I)
relative_path  (I)

SA_API int IMF_stat ( const char *  path,
IMF_file_status *  stats 
)

Gets the status of a file. The status includes the owner id, group id, protection mode, file type (file or directory), creation date, date last modified, file format (text or binary), file size, and the full path name of the file.

Parameters:
path  (I) Path of the file
stats  (O) Status of the file

SA_API int IMF_write_file ( IMF_file_t  file_descriptor,
int  datatype_count,
int  data_type,
void *  items_to_write,
int *  items_written_count 
)

Writes items to a file. If the actual number of items written is not datatype_count, then an error is returned.

Parameters:
file_descriptor  (I)
datatype_count  (I)
data_type  (I)
items_to_write  (I)
items_written_count  (O) The actual number of bytes written to the file

SA_API int IMF_write_file_line ( IMF_file_t  file_descriptor,
const char  text_line[SS_MAXLLEN] 
)

Deprecated:
This function is deprecated and will be removed from Tc12. In Tc10 onwards, please use IMF_write_file_line2
Writes a line of text to an ASCII text file.
Parameters:
file_descriptor  (I)
text_line  (I)

SA_API int IMF_write_file_line2 ( IMF_file_t  file_descriptor,
const char *  text_line 
)

Writes a line of text to an ASCII text file.

Parameters:
file_descriptor  (I)
text_line  (I)