Information on External References in CM/400

Answer

Read this document if you are a user of Content Manager for AS/400 VisualInfo (VI/400) but have other repositories of data on your AS/400 machines, or within your networks, and you want to access this data through the VI/400 Windows® client and programming interfaces. Treat these "external documents" as VI/400 documents, including search, additions to folders, and inclusions in workflow.

To define an external reference to VI/400, first create a file that contains location and VI/400 indexing information, such as index class, key fields, and content class. Each record in the file represents one document to be indexed into VI/400. By indexing all documents in the file at once, instead of calling VI/400 APIs for each document, processing time is minimized.

Four types of external references are now supported in VI/400:

• An OS/400® file
• A workstation (or network) file
• Data retrieved by a program called on a server
• Data retrieved by a program called on a workstation

Once the external references have been indexed, access them through the VI/400 APIs. These APIs are used today by the VisualInfo (VI) client, the ContentConnect or the EIP client, and other external applications.

When the VisualInfo for AS/400 client opens a document, the content class that is associated with the document controls whether it will be displayed by the VI viewer or passed to another application. For example, if a video or audio clip is imported, identify the content class as "QVI". When the document is opened, the VI client starts MPLAY32 to play the video. This gives VI/400 the capability to index, locate through search interfaces, and display any type of document through its view capability or the capability of an alternate application.

To create an External Reference:

1. Create the following files using the DDS source in QVI/EKDSRC4:

• EKD0313
• EKD0314
• EKD0314L1
• EKD0314L2
• EKD0314L3

2. Grant authority to the above objects for the VI/400 group profile.

3. Use the AS/400 Data File Utility (DFU) or write a custom program, and update the EKD0314 file with the data for each object indexed into VI/400. The following is the field description for each field in the EKD0314 file:

• INDEX CLASS: This is the index class that the external reference is indexed into. Index class does not have to be defined at the time the file is updated; however, before beginning the index function, it must be created.
• KEY1-KEY8 DATA: This is the keyfield information used when accessing the external reference document. Keyfield information is optional; however, it can narrow the search when you are accessing the external reference.
• CREATE DATE: This is the date you choose to be associated with this external reference. No date verification is performed on this field. It will be stored as it is written in this field.
• CREATE TIME: This is the time you choose to be associated with this external reference. No time verification is performed on this field. It will be stored as it is written in the field.
• USERID: This is the user ID you choose to associate with this external reference. No verification is performed on this field. It will be stored as it is written in the field.
• CONTENT CLASS: Content class associates the external reference to the viewer for this object. If the external reference is to be viewed by the VI/400 client, enter a zero in this field.
  For a list of all other content classes, review file EKD0318. If the viewer you want to use doesn't exist in file EKD0318, use DFU function on EKD0318 to add a new content class to that file.
• EXTERNAL REFERENCE TYPE: Valid values are as follows:
• The data in the external reference field represents the information passed to another program (Object Handler) to retrieve the data. In this example, a fully-qualified AS/400 library, file, and member name is passed to the program QVIXRFSMP.
• The data in the external reference field represents a fully-qualified AS/400 path. This might be a library/file/member, as above, or the name of an IFS file.
• The data in the external reference field represents another program (Object Handler) on the workstation that is called to retrieve the data. The specified program must be a DLL containing the function "vi400extref".
• The data in the external reference field represents a fully-qualified path that can be accessed from the workstation. The data represents the external reference that is to be deleted. See the section called Deleting an External Reference below.
• EXTERNAL REFERENCE: This field contains the location of the external reference as it was defined in the EXTERNAL REFERENCE TYPE field above.
• OBJECT HANDLER LIBRARY: For a type 1 reference only, this is the name of the AS/400 library that contains the object handler.
• OBJECT HANDLER PROGRAM: For a type 1 reference only, this is the name of the AS/400 program that receives the reference. This is a "stand alone" program which receives as input the following structure:
• RCAREA - CHAR(8) - Non-blank return code. If the return code is not zero, it will be written to the EKD0080 error file.
• FILENAME - CHAR(256) - The content to be returned through the VI/400 APIs must be written to the temporary file specified.
• EXTREF - CHAR(256) - The external reference, or location information, used to locate the external reference content.
  For a type 3 reference, the Object Handler is the name of a workstation DLL containing the following function:
  

int_Export_System vi400extref (
HSESSION hsession,  
/* VI/400 session handle */
char    
* extref,    
/* External reference   */
/* converted to             */
/* workstation code page */
FILE      
* filehandler
/* Handle of file to     */
/* receive document        */
/* content.  Must not be */
/* closed.                  */

A non-zero return code will be returned in SimLibOpenObject.

• ITEMID - CHAR(12) - This field should be set to spaces. It will be set to the Item ID created by the indexing process. If this field is not blank, it will be assumed that this external reference has been indexed and it will be ignored.

4. After the EKD0314 file is populated, call the index program QVIXRFINX from a command line or a custom program. There are no parameters on this program. When this program is called, it will open all required files, reserve a block of document identifiers, and index the data into the VI/400 environment. If QVIXRFINX fails for any reason, call QVIXRFINX and only those records which haven't already been indexed will be processed.

Limitations to creating an external reference

Documents are indexed using this batch approach to provide the best possible performance. At this time, there is no API provided to index such objects from another application. There is no security checking, so only selected users should be give authorization to QVIXRFINX. Fields are not validated during execution.

Deleting an external reference

QVIXRFDEL lets you submit delete requests for external references. QVIXRFDEL deletes all occurrences of external references from the VI/400 database. You can submit more than one delete job at a time, which might be useful if you have a very large number of delete requests.

To successfully delete an external reference, populate the EKD0314 file with the EXTERNAL REFERENCE TYPE set to zero and populate the ITEMID field with the correct item ID. Once the EKD0314 records are created, call QVIXRFDEL to execute the delete requests. The delete requests are removed from EKD0314 during the delete process.

Do not delete any records from EKD0314. Use the file as a cross-reference file between your application and VI/400. If you choose to delete the external reference, modify the EXTERNAL REFERENCE TYPE to a zero. At that time, the cord will be deleted from the file by the delete process.