Checkin Business Object

Syntax

To check a file into an object, you must first have Checkin privileges. If you do, you can check in the file using the checkin businessobject command.

checkin businessobject OBJECTID [format FORMAT_NAME][store STORE_NAME][unlock] 
[client|server] [append] {FILENAME};

• OBJECTID is the OID or Type Name Revision of the business object.
• FORMAT_NAME is the name of the format to be assigned to the files being checked in. (For more information, see Format Clause for the Add Policy Command. If you include a format and a store, you must include the format first.
• STORE_NAME is the name of the store where the file(s) should be checked in. This can be used to override the default store defined in the policy that determines where a governed business object’s files are kept. For example, a business applications’s checkin page could be used by several different companies, each with its own file store. The logic on the page could be designed to check which company the current user is employed by, and check the file into the store assigned to that company. If you are going to include both a format and a store, you must include the format first.
• FILENAME is the full directory path to the files you want to associate with this business object. When including multiple filenames, separate each with a space. Filename must be specified last.

As an example of using the Checkin Businessobject command, assume you have written procedures for assembling and disassembling a telephone. You now want to associate these procedures with the telephone object. To do that, you might write a command similar to:

checkin businessobject Assembly "Phone Model 324" AD
    $MATRIXHOME/telephones/assemble324.doc
    $MATRIXHOME/telephones/disassemble324.doc;

In this example, it is assumed that the default format is for document files. If a default format is some other format, you would need to modify the above command to include the Format clause. Assume that the two files are standard ASCII text files. Since that is not the default format, the above command would have to be modified as:

checkin businessobject Assembly "Phone Model 324" AD
   format "ASCIItext"
    $MATRIXHOME/telephones/assemble324.txt
    $MATRIXHOME/telephones/disassemble324.txt;

If someone wants to access the files, the associated format will define the commands used to view, edit, and print the files.

Although the format identifies how the files are to be accessed, it does not necessarily mean that access is permitted. Access is controlled by the policy. Also, editing access can be controlled by the use of exclusive editing locks (for more information, see MQL Concepts: Locking and Unlocking a Business Object).

Checkin Performance

The first MQL checkin after a machine restart, or when the OS file cache has been invalidated, could take some time because of the need to load JVM jars and DLL files. You can prevent this behavior by keeping the necessary files loaded into the OS file cache by periodically launching a small MQL command that executes a JPO in the background.

To accomplish this, follow these steps:

1. Create a C:\tmp\JVMINIT.java file with the following content:

   import matrix.db.*; 
   import java.io.*; 
   public class ${CLASSNAME} 
   {
     public ${CLASSNAME} () {}
     public int mxMain(Context context, String[] args) throws Exception
     {
       return 0;
     } 
   }

2. To add the JPO to the system, run the following command under the MQL prompt within the admin user context:

   add prog JVMINIT java file C:\temp\JVMINIT.java;

3. Then compile the JPO and grant execute permission on that program to the user guest:

   compile prog JVMINIT; mod prog JVMINIT execute user guest;

4. In order to run the JPO periodically in the background, you need to use a batch file. You can find a sample batch file ( mqljvminit_sample.bat ) under the Modeling_Studio_Install_Path\Platform\code\bin\ directory. The content of the mqljvminit_sample.bat file is as follows:

   @echo off
   :beginning
   start /wait /b 
   Modeling_Studio_Install_Path\Platform\code\bin\mql.exe -c "execute prog JVMINIT;" -d -p
   ping -n 300 127.0.0.1 > nul
   goto beginning

   • Replace Modeling_Studio_Install_Path with your custom installation path.
   • Replace Platform with either intel_a (for x86 platforms) or win_b64 (for x64 platforms).
5. To prevent a black command prompt window from appearing, you can launch the batch file with the following mqljvminit.js file:

   var WshShell = new ActiveXObject("WScript.Shell");
   WshShell.run("Modeling_Studio_Install_Path\\Platform\\code\\bin\\mqljvminit.bat", 0, false)

   You can find a sample of this file under: Modeling_Studio_Install_Path\Platform\code\bin\mqljvminit_sample.js.

   If you use these sample files, rename the mqljvminit_sample.bat file to mqljvminit.bat and rename the mqljvminit_sample.js file to mqljvminit.js.

There are several possible ways to launch mqljvminit.js:

• You can force mqljvminit.js to run at machine boot time by using the following Windows registry key:

  HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run

  and adding a new key MQLJVMINIT of type REG_SZ with the value:

  Modeling_Studio_Install_Path\Platform\code\bin\mqljvminit.js

• You can also force mqljvminit.js to run at machine boot time by creating a shortcut for it in the Startup directory:

  C:\Documents and Settings\All Users\Start Menu\Programs\Startup

• You can launch mqljvminit.js manually by simply running it from the Modeling_Studio_Install_Path\Platform\code\bin\ directory.

Unlock Clause

When an object first has files checked in, it is probably not locked. However, when files are later checked out to be updated, the object should be locked to prevent other users from editing the file’s contents. Checking in the file has the effect of updating the database with the latest version of the file. But typically, the object owner will want to maintain editing control over the file. For example, the owner could be editing a CAD file and the file is still undergoing changes. If the owner checks in the file, others can monitor the process even though they cannot make changes. After the edit is complete the owner would remove the lock. The owner would include the Unlock clause in the Checkin command. Alternatively, if access permitted, the lock could be removed with the unlock businessobject command.

If locking is enforced in the object’s policy, the checkin will fail if:

• The object is not locked
• The user performing the checkin in is not the one who locked it

When an object is locked, no files can be checked in to the object. This means that attempts to open for edit, as well as checkin, will fail. Files can be checked out of a locked object, and also opened for view. This behavior ensures that one user is not overwriting changes made by another.

Client and Server Clauses

The client and server 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.

The default file location for checkin from the Web is the Collaboration Server. Programmers can specify client to have the file copied from the Web client machine instead. For example:

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

would look for the file text.txt on the server, while the following would look for it on the client:

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

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

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

yields the same results as:

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

Append Clause

Use the append clause when the files should be added to the contents of the object. Without this flag, the checkin command overwrites any files that are contained in the object, even if the file names are unique. For example:

checkin businessobject Assembly “Phone Model 324” AD
   format “ASCIItext”
   $MATRIXHOME/telephones/assemble324.doc;
checkin businessobject Assembly “Phone Model 324” AD
   format “ASCIItext”
   append $MATRIXHOME/telephones/disassemble324.doc;

Without the append flag, the Assembly Phone Model 324 AD would contain just one file: disassemble324.doc.

Be aware that when you use the Append clause to check in a file, and the business object already contains a file of the same name, the file is overwritten without a prompt for verification.

Store Clause

The store clause can be used to override the default store (defined in the policy) that determines where a governed business object’s files are kept. For example, a business application’s checkin page could be used by several different companies, each with its own file store. The logic on the page could be designed to check which company the current user is employed by, and check the file into the store assigned to that company. For example:

checkin bus Part Sprocket 3 append store CAD c:\sprocket.cad;