format Command

Use a format definition to capture information about different application file formats. A format stores the name of the application, the product version, and the suffix (extension) used to identify files. It also contains the commands necessary to automatically launch the application and load the relevant files. Formats are the definitions used to link 3DSpace to the other applications in the users’ environment.

For conceptual information on this command, see MQL Concepts: Formats.

This page discusses:

User Level

Business Administrator

Add Format

Format definitions are created using the Add Format command. This command has the syntax.

Syntax

add format NAME [ADD_ITEM {ADD_ITEM}]
  • ADD_ITEM provides more information about the format. They also provide information on how a file with that format should be processed. The Add Format clauses are:
description VALUE
icon FILENAME
creator NAME
type NAME
edit PROGRAM_OBJECT_NAME
print PROGRAM_OBJECT_NAME
suffix VALUE
mime VALUE
version VALUE
view PROGRAM_OBJECT_NAME
[!|not] hidden
property NAME [to ADMINTYPE NAME] [value STRING]
history STRING

Creator and Type Clauses

The Creator and Type fields are Macintosh file system attributes (like Protection and Owner on UNIX systems). They should not be confused with users or types. The following is an example Creator clause of the Add Format command:

creator ‘MPSX’

The following is an example Type clause of the Add Format command:

type ‘TEXT’

This would identify a script file created by the Macintosh toolserver. Both fields are four bytes in length and are generally readable ASCII. If you specify a value for only one of the two clauses, the other clause assumes the same value. The values for creator and type are registered with Apple for each Macintosh application. When a file is checked out to a Macintosh, these attribute settings will be applied. If Macintoshes are not used, the fields can be left blank.

View, Edit, and Print Clauses

Theses clauses specify the program to use to view (open for view), edit (open for edit), or print files checked into the format. When you specify the program, you are actually specifying the name of the program object that represents the program.

For Windows platforms, if you want to open files for view, edit, or print based on their file extensions and definitions in the Windows Registry, you can leave out the corresponding clause. For example, by default Windows uses MS Paint to open files with a file extension of .bmp. Keep in mind that each user’s PC contains its own Windows Registry database, which is editable; the databases are not shared between computers. If you want to provide a more complex and flexible format that will use the file association mechanism of windows, see Format Definition Example Program.

Program Object Requirements

To be used in a format definition, a program object definition must include these characteristics:

  • The Needsbusinessobject clause must be true.
  • The Code clause must contain the command needed to execute the program and the syntax for the command must be appropriate for the operating system.
  • The Code clause should end with the $FILENAME macro so the program opens any file. Enclose the macro in quotes to ensure that files with spaces in their names are opened correctly.

For more information, see Code Clause for the Add Program Command.

Syntax

The View, Edit, and Print clauses of the Add Format command use this syntax:

view PROGRAM_OBJECT_NAME
edit PROGRAM_OBJECT_NAME
print PROGRAM_OBJECT_NAME

For example, the following is a sample format definition for CADplus, a computer aided design system:

add format CADplus
   description “CADplus Computer Aided Design System"
   version 10
   suffix “.cad"
   view CADview.exe
   edit CADedit.exe;

After this format is defined, 3DSpace can open a file checked in with this format using CADview for viewing or using CADedit for editing.

Suffix Clause

This clause specifies the default suffix for the format. If an object is selected that contains no files, “open for edit” generates the name of the file from the object name. 3DSpace attempts to open a file with that name and the default format suffix.

Assume you want to add a note to a business object. You might use the TextTYPE or BestBooks word processing programs to create the note. TextTYPE uses a default file suffix of .tex for document files and BestBooks uses .bb. These suffixes enable users to quickly identify file types. For example:

add format
 “TextTYPE"
   description “For documents created with TextTYPE"
   version 3.1
   suffix “.tex";
add format “BestBooks"
   description “For documents created with BestBooks"
   version 6.0
   suffix “.bb";

After these definitions are made, any file that uses a TextTYPE format will have a suffix of .tex and any file that uses a BestBooks format will have a suffix of .bb.

The suffix specified in the Format is not used in the launching mechanism. The file itself is passed to the operating system and its extension (or suffix) is used to determine what application should be opened.

Mime Clause

You can specify the MIME (Multi-Purpose Internet Mail Extension) type for a format. MIME types are used when files are accessed via a Web browser.

To specify a MIME type, use the Mime clause in the format definition:

creator VALUE

  • VALUE is the content type of the file. The format of VALUE is a type and subtype separated by a slash. For example, text/plain or text/jsp .

The major MIME types are application, audio, image, text, and video. There are a variety of formats that use the application type. For example, application/x-pdf refers to Adobe Acrobat Portable Document Format files. For information on specific MIME types (which are more appropriately called “media” types) refer the Internet Assigned Numbers Authority Web site at http://www.isi.edu/in-notes/iana/assignments/media-types/. The IANA is the repository for assigned IP addresses, domain names, protocol numbers, and has also become the registry for a number of Web-related resources including media types.

To find the MIME types defined for a particular format, use the following command:

print format FORMAT_NAME select mime;

Version Clause

This clause identifies the version number of the software required to process the file. The software version is useful when tracking files created under different software releases.

Upward and downward compatibility is not always assured between releases. If you install a new software release that cannot process existing files, you can create a new format for the new release and leave the old format in place. The old format automatically references the older version of the software while the new format references the new version.

The version clause does not check the version number against the software you are using. You can enter any value. However, you should use the actual version number or identifier if possible. For example:

add format ASCII version Standard;
add format “TextTYPE” version 3.1;

History Clause

The history keyword adds a history record marked “custom” to the format that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

Copy Format

After a format is defined, you can clone the definition with the Copy Format command. This command lets you duplicate defining clauses with the option to change the value of clause arguments.

Syntax

copy format SRC_NAME DST_NAME [MOD_ITEM] {MOD_ITEM};
  • SRC_NAME is the name of the format definition (source) to copied.
  • DST_NAME is the name of the new definition (destination).
  • MOD_ITEMs are modifications that you can make to the new definition. For more information, see Modify Format.

History Clause

The history keyword adds a history record marked “custom” to the format that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects.

Modify Format

After a format is defined, you can change the definition with the Modify Format command. This command lets you add or remove defining clauses and change the value of clause arguments:

modify format NAME [MOD_ITEM] {MOD_ITEM};
  • NAME is the name of the format you want to modify.
  • MOD_ITEM is the type of modification you want to make.

There are different types of modifications you can make. Each modification is specified in a Modify Format clause, as listed in the following table. You only need to specify fields to be modified.

Modify Format Clause Specifies
description VALUE The current description, if any, is changed to the value entered.
creator NAME For Macintosh only, the current creator name is changed to the value entered.
edit PROGRAM_OBJECT_NAME The program object that represents the program to use to open the business object file for editing or modification.
icon FILENAME The image is changed to the new image in the field specified.
name NEW_NAME The current format name is changed to that of the new name entered.
print PROGRAM_OBJECT_NAME The program object that represents the program to use to print the business object file.
suffix VALUE The default file suffix specified is used when creating new files.
type NAME For Macintosh only, the current type name is changed to the value entered.
mime VALUE The MIME type for the format, which is used when a file is accessed via a Web browser.
version VALUE The version number is set for the software processing a file with this format.
view PROGRAM_OBJECT_NAME The program object that represents the program to use to open the business object file for viewing.
hidden The hidden option is changed to specify that the object is hidden.
nothidden The hidden option is changed to specify that the object is not hidden.
property NAME [to ADMINTYPE NAME] [value STRING] The named property is modified.
add property NAME [to ADMINTYPE NAME] [value STRING] The named property is added.
remove property NAME [to ADMINTYPE NAME] [value STRING] The named property is removed.
history STRING Adds a history record marked "custom" to the format that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

As you can see, each modification clause is related to the clauses and arguments that define the format. For example, the following command changes the name and version of the format named “TextTYPE Version 9.1”:

modify format “TextTYPE Version 9.1”
   name “TextTYPE Version 10”
   version 10.0;

When modifying a format, remember the question of upward and downward compatibility between software versions. Since all files with the defined format are effected by the change, you should test sample files or read the release notes to determine whether or not old files will be negatively effected. If they will be, you might want to create a new format for the new software version rather than modify the existing format definition.

In some cases, the suffix will be different for documents created in a new release of the application software. Therefore, a separate format is required (at lease until all files are updated).

Delete Format

If a format is no longer required, you can delete it with the Delete Format command.

delete format NAME;
  • NAME is the name of the format to be deleted.

Searches the list of formats. If the name is not found, an error message is displayed. If the name is found and there are no files with that format in the database, the format is deleted. If there are files that use that format within the database, they must be migrated to a different format (for more information, see Moving Files) or deleted from the business object before you can remove the format from the format list.

For example, delete the TextTYPE Version 9.1 format, enter the following command:

delete format “TextTYPE Version 9.1”;

After this command is processed, the format is deleted and you receive an MQL prompt for another command.