Checkout Business Object

Syntax

To check a file out of an object, you must first have Checkout privileges. If you do, you can check out the files by using the Checkout Businessobject command. Otherwise, 3DSpace prevents you from checking out the file.

• OBJECTID is the OID or Type Name Revision of the business object. It can also include the in VAULTNAME clause, to narrow down the search.
• FORMAT_NAME is the name of the format of the files to be checked out. For more information, see Format Clause for the Add Policy Command. If no format is specified, only files of the default format are checked out. If a format is specified, but no filenames, all files of the specified format are checked out.
• FILENAME is a specific file (or files) that you want to check out, or specify all to checkout all files in the specified format.
• DIRECTORY is the complete directory path where you want the checked out copies. If the directory is omitted, the checked out copies are copied to the current system directory.

For example, assume you have written procedures for assembling and disassembling a telephone. After checking them in, you allow users to edit the procedures to correct errors or ambiguities. To do this, they might write a command similar to:

checkout businessobject Assembly "Phone Model 324" AD file assemble324.doc $MATRIXHOME\telephones;

After this command is processed, a copy of the named file will appear in the directory specified. If the directory is not specified, the files are copied to the current system directory.

If you have checked out an earlier version of a file to edit, be careful not to overwrite the external file with the new checked out file. If the same file name already exists in the target directory, no error message appears in MQL. The new file will overwrite the existing file without further warning.

When you check out a file, the checkout operation triggers multi-site file sync, if needed, and writes to the history file. The read/write operation has to complete before you can use a file.

Lock Clause

In the Checkout command, it is assumed that the file being checked out is unlocked to allow other users to edit the file’s contents. To prevent other users from checking files in, lock it by including the keyword lock within the Checkout command. Only the person who locks the object will be allowed to check in files.

For example, the following command locks and checks out a file:

checkout businessobject Assembly “Phone Model 324” AD lock;

Using the lock to prevent editing is useful when you are making extensive changes to an external file. While those changes are being made, you do not want to worry about any other users modifying the original file without your knowledge. When you have completed your changes, you can check the file in and remove the lock at the same time.

A locked object can be unlocked by a user with unlock access. For example, a manager might need to unlock an object locked by an employee who is out sick. If locking is enforced in the object’s policy the object MUST be locked within the checkout command if the updated file is to be checked back in.

Server and Client Clauses

The server and client clauses allow programmers to specify where files are to be located when their programs are executed from a Web client (either downloaded or run on the Collaboration Server). These clauses are used to override the defaults and are ignored when executed on the desktop client.

By default, the checkout command executed from the Web stores files on the Web client machine. The server clause allows programmers to alternatively specify the server as the file location for the operation. For example, the following command in a Tcl program object that is run from the Web client will land the file text.txt on the client:

mql checkout bus Assembly Wheel 0 format ascii file text.txt \tmp;

while the following would look for it on the server:

mql checkout bus Assembly Wheel 0 server format ascii file text.txt \tmp;

The client clause can be specified to force the default location. For example:

mql checkout bus Assembly Wheel 0 client format ascii file text.txt \tmp;

yields the same results as:

mql checkout bus Assembly Wheel 0 format ascii file text.txt \tmp;

Format Clause

In addition to checking out all files of the default format from the object, you can check out only specific formats of the file. Files can be checked in using multiple formats. For example, a text file can be checked in using two formats that represent two different versions of a word processing program. You can check out only the file associated with the specific format by using the Format clause.

The Format clause of the Checkout Businessobject command specifies the format of the files to check out. If no format is specified, the default format is assumed. For example, the following command checks out all files associated with the 1998 word processing program.

checkout businessobject “Phone Book” “Boston Region” K format 1998;

Opening Files

Files that have been checked in to a business object using the Checkin command can be opened for either viewing or editing.

To open files and launch the appropriate application for viewing, use the following command:

openview businessobject OBJECTID [format FORMAT_NAME] [file FILENAME];

To open files and launch the appropriate application for editing, use the following command:

openedit businessobject OBJECTID [format FORMAT_NAME] [file FILENAME];

• OBJECTID is the OID or Type Name Revision of the business object.
• FORMAT_NAME is the file format in which the file has been checked in.
• FILENAME is the name of the file.

For more information, see Modify Business Object.