INFOIMAGE DESKTOP MANAGER

Transcription

1 INFOIMAGE DESKTOP MANAGER Indexing User Exits Reference Manual Copyright 1999 Unisys Corporation. All rights reserved. Unisys is a registered trademark of Unisys Corporation. June 1999 Printed in USA

2 The names, places, and/or events used in this publication are not intended to correspond to any individual, group, or association existing, living, or otherwise. Any similarity or likeness of the names, places, and/or events with the names of any individual, living or otherwise, or that of any group or association is purely coincidental and unintentional. NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. RESTRICTED Use, reproduction, or disclosure is restricted by DFARS and /FAR & for commercial computer software. Correspondence regarding this publication should be forwarded to Unisys Corporation by addressing remarks to Product Information, Unisys Corporation, Suite C, Harris Oaks Blvd, Charlotte, NC U.S.A. Comments about documentation can also be sent through to doc@unisys.com. Unisys is a registered trademark of Unisys Corporation. All other terms mentioned in this document that are known to be trademarks or service marks have been appropriately capitalized. Unisys Corporation cannot attest to the accuracy of this information. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

3 Contents About This Document... vii Section 1. Introduction to the DTM Indexing User Exits Capabilities Triggering Activities Functions That You Can Perform Functions Available from Desktop Manager About the Sample Source Code Section 2. The DTM Index Form Properties Events Functions Event: CharCheck_Event Syntax Comments Return Codes Example Event: FieldExit_Event Syntax Comments Return Codes Example Event: FormClose_Event Syntax Comments Example Event: FormLoad_Event Syntax Comments Example Event: MenuItem_Click_Event Syntax Comments Example Function: GetFieldDefaultValue Syntax Returns Comments Unisys Corporation June 1999 iii

4 Contents Example Function: GetFieldValue Syntax Returns Comments Example Function: GoToField Syntax Comments Example Function: MenuItemAdd Syntax Comments Example Function: MenuItemDisable Syntax Comments Example Function: MenuItemEnable Syntax Comments Example Function: SetFieldCheckType Syntax Comments Example Function: SetFieldRange Syntax Comments Example Function: SetFieldValue Syntax Comments Example Function: SetMenuCaption Syntax Comments Example Function: WarningMessage Syntax Comments Example Section 3. Developing User Exits for the DTM Index Form Software Components User Exit Architecture Version Compatibility Sample User Exit Code Sample Steps to Implement a DTM Index Form User Exit Registering Your New User Exit iv Unisys Corporation June

5 Contents Handling Multiple Document Classes Section 4. The Customized Index Form Properties Events Functions Event: FormLoad_Event Syntax Comments Example Event: FormShow_Event Syntax Comments Example Event: FormUnload_Event Syntax Comments Example Function: GetFieldDefaultValue Syntax Returns Comments Example Function: GetFieldFlags Syntax Returns FieldFlags Enumeration Example Function: GetFieldStatus Syntax Returns FieldStatus Enumeration Example Function: GetFieldValue Syntax Returns Comments Example Function: SetFieldValue Syntax Comments Example Function: NotifyClient Syntax Comments Example Section 5. Developing Visual Basic Index Forms Unisys Corporation June 1999 v

6 Contents Software Components User Exit Architecture Version Compatibility Sample User Exit Code Sample Steps to Implement an Index Form User Exit Registering Your New User Exit Handling Multiple Document Classes vi Unisys Corporation June

7 About This Document Purpose Scope Audience This document describes the architecture and use of User Exits. With this information a programmer can design and write User Exit programs using the function set provided. The data structures and functions of the programming interface are described along with sample program snippets, and error codes. The prerequisite information for developing Windows programs, and coding various languages is beyond the scope of this document. The primary audiences for this document are those personnel responsible for designing, developing, and implementing DTM user exits. Prerequisites An understanding of the design philosophy of the system as a whole, its operating principle, and capabilities that would otherwise be accessed through the user interface Visual Basic 5.0 ActiveX DLL programming expertise. Visual Basic 5.0 and at least Service Pack 2 installed Unisys Corporation June 1999 vii

8 About This Document viii Unisys Corporation June

9 Section 1 Introduction to the DTM Indexing User Exits User Exits are customer-written program functions that enable customized capabilities to be added to the Desktop Manager (DTM) Indexing function. With your own functions you might perform special look-up or validation processes or write processes that work in conjunction with existing form functions. Desktop Manager has two types of indexing user exits. The DTM Index Form user exit and the Customized Index Form user exit. The DTM Index Form user exit is activated when DTM displays its standard index form. The Customized Index Form user exit displays an index form created by a programmer. DTM notifies the user exit when to display the custom-written index form. Both types of user exits can be used but not on the same document class. If you create a customized index form for one document class the other document classes can still utilize the DTM index form. Capabilities User exits are custom-written functions that provide additional processing for designated index forms or individual fields on a form. Using your own code, and by making calls to several functions built into the user exit skeleton, you can perform specialized processing required in your specific workplace. For instance, you might enable your data entry staff to enter abbreviations and have a user exit spell out the full text. Triggering Activities You can create user exits that run after any of these user actions: DTM Index Form: When a form is opened After a keystroke is entered into a field When a field is implicitly completed by tabbing to another field or closing the form When a form is closed When a custom menu is selected from the Index form menu bar Unisys Corporation June

10 Introduction to the DTM Indexing User Exits Customized Index Form: When the user wants to display the index form When the index form must be closed Functions That You Can Perform DTM Index Form: For the DTM indexing user exit there is one user exit module (ActiveX DLL) for each document class Index form created with the InfoImage Forms Creator. Within a user exit routine, you can include programming functionality that your environment supports, but you should avoid time consuming processes. For instance, you might look up values on an external database or perform mathematical calculations. The triggering mechanisms mentioned above specifically help to perform the following types of activities: Provide special default values upon opening the form Verify or manipulate each keystroke as you type it into the field Verify or manipulate field values once you have typed them Perform validation of fields upon closing the form Display custom menu items on the index form upon opening the form Perform special processes when a custom menu item is selected Customized Index Form: For the Customized Index form there is one user exit module (ActiveX DLL) for all document classes for which you create your own Visual Basic forms. Your can create as many Visual Basic forms as necessary. Typically, there is one Visual Basic form for each document class. These Visual Basic forms are part of the user exit module. Within the customized index form user exit, you can include programming functionality that your environment supports and is supported in a Visual Basic ActiveX DLL. For example, on your Visual Basic form you can include any OCX control that you require. Functions Available from Desktop Manager DTM Index Form: In creating your routines, you can call functions that already exist within the DTM Indexing user exit to do the following; Access all field data in the DTM Indexing form; including defaults Read or change and field value 1 2 Unisys Corporation June

11 Introduction to the DTM Indexing User Exits Temporarily change the value range for a field Update all field values Display messages to the user Customized Index Form: In creating your routines, you can call functions that already exist with the Customized Index form user exit to do the following; Access all field values for a document or folder Identify to DTM which fields to update About the Sample Source Code Included on the install CDROM is sample source code for each type of user exit. To compile your own user exits, to modify and recompile the skeleton source code you need the Microsoft Visual Basic 5.0 Professional Edition or Enterprise Edition and all service packs Unisys Corporation June

12 Introduction to the DTM Indexing User Exits 1 4 Unisys Corporation June

13 Section 2 The DTM Index Form Properties The DTM Index Form User Exit allows you to add validation to the indexing process when using the standard DTM Indexing Form. The DTM Index Form User Exit uses properties, events and functions. The following table describes the Index Form User Exit Properties: Events Property Type Description Object_Class String Identifies the document class of the workitem currently being indexed. Object_ID String Identifies the ID of the workitem currently being indexed. Object_Name String Identifies the external name of the workitem currently being indexed. Object_Type String Identifies the type of the workitem currently being indexed. The following table describes the Index Form User Exit Events: Event Parameters Description CharCheck FieldExit FormClose FieldName As String, FieldValue As String, NewChar As String FieldName As String, FieldValue As String Cancel As Boolean, SaveOption As Boolean DTM activates this event when the user enters a keystroke and the field was identified to have each character checked as it is entered. DTM activates this event when the user exits a field and the field was identified to have a field check performed on it. DTM activates this event when the index form is about to close. FormLoad Cancel As Boolean DTM activates this event whenever the index form is loaded. MenuItem_Cli ck MenuID As String DTM activates this event when the user clicks on a user exit menu Unisys Corporation June

14 The DTM Index Form Functions The following table describes the Index Form User Exit Functions: Function Parameters Description GetFieldDefaultValue FieldName As String Returns the default value for a field. GetFieldValue FieldName As String Returns the current value for a field. GoToField FieldName Sets the field to where the cursor will move next. MenuItemAdd MenuID As String, MenuCaption As String) Creates a menu item on the index form. MenuItemDisable MenuID As String Gray-out a menu item. MenuItemEnable MenuID As String Allow a menu item to be selected. SetFieldCheckType SetFieldRange SetFieldValue FieldName As String, CheckType As FieldCheckType FieldName As String, LowValue As String, HighValue As String FieldName As String, Value As String Set the type of check to perform on a field Changes the High and Low ranges for a field. Changes the value for a field. SetMenuCaption MenuCaption As String Set the name of the user exit menu in the Index form Menu bar. WarningMessage Message As String Sets a message to display to the user. 2 2 Unisys Corporation June

15 The DTM Index Form Event: CharCheck_Event Syntax CharCheck_Event (FieldName As String, FieldValue As String, NewChar As String) As CharCheck_Int Parameter FileName FieldValue NewChar Description Contains the name of the field to validate. Contains the FieldValue before the new character was entered. Contains the new character to validate. Comments DTM activates this event when the user enters a keystroke and the field was identified to have each character checked as it is entered. To identify a field to use character checking call the SetFieldCheckType function in the FormLoad_Event for each field you wish to validate. To change the character entered to a different character, set NewChar equal to the desired character. Return Codes Example CHAR_NOTTESTED - character was not tested CHAR_ACCEPTED - character is valid CHAR_REJECTED - character is not-valid CHAR_REPLACE - replace the character with something else (Set NewChar = <replacement character>) Unisys Corporation June

16 The DTM Index Form Event: FieldExit_Event Syntax FieldExit_Event(FieldName As String, FieldValue As String As FieldExit_Int Parameter FileName FieldValue Description Contains the name of the field to validate Contains the data to validate. Comments Return Codes Example DTM activates this event when a field is exited and the field was identified to have a field exit check performed on it. To identify a field to use Field checking, call the SetFieldCheckType function for each field you wish to validate in the FormLoad_Event. FIELD_OK - Validation was successful FIELD_ERROR - Validation failed This example validates FIELD1 and FIELD2. FIELD1 is validated for a 1 or 2. FIELD2 is used along with FIELD3 to set FIELD Unisys Corporation June

17 The DTM Index Form Event: FormClose_Event Syntax Sub FormClose_Event(Cancel As Boolean, ByVal SaveOption As Boolean) Parameter Cancel SaveOption Description Flag that determines whether the user exit will allow the form to be closed. Flag that identifies whether the chose to save changes. Comments This function is activated when the index form is being closed. Example This example validates FIELD1 for XXXX. When XXXX is found in FIELD1 the form will not be closed and a warning message is displayed Unisys Corporation June

18 The DTM Index Form Event: FormLoad_Event Syntax Sub FormLoad_Event(Cancel As Boolean) Parameter Cancel Description Flag that determines whether this user exit will handle the index form for this document class. If you do not want to process this Object and want the DTM to display the DTM index form set Cancel to True. Comments Add code to this event to use GetFieldValue to get the current values of each index field or use the FormField collection to enumerate through the index fields. Use the SetFieldValue function to update the fields that you wish to be changed. Example This example set the type of check for FIELD1 to be field exit and FIELD5 to be character checking. It sets the default values for FIELD2 and FIELD6. It also adds two menu items to the DTM Index form, Send and Receive. 2 6 Unisys Corporation June

19 The DTM Index Form Event: MenuItem_Click_Event Syntax Sub MenuItem_Click_Event(MenuID As String) Parameter MenuID Description Text string of an ID assigned to a menu item. Comments This function is activated when a user exit menu item is clicked on. You must add menu items by calling the MenuItemAdd function for each menu item you wish to create. Do this in the FormLoad_Event. This function is purely to trigger the user exit to perform a customized function. Also See; MenuItemEnable and MenuItemDisable. Example This example toggles the menu items from enabled to disabled Unisys Corporation June

20 The DTM Index Form Function: GetFieldDefaultValue Syntax Function GetFieldDefaultValue(ByVal FieldName As String) As String Parameter Description FieldName Name of the field to retrieve the default value. Returns The default value for the specified field is returned by this function. Comments Use this function in the FormLoad_Event. Example This example gets the default value for FIELD4 and places it in a variable. 2 8 Unisys Corporation June

21 The DTM Index Form Function: GetFieldValue Syntax Function GetFieldValue(ByVal FieldName As String) As String Parameter Description FieldName Name of the field to retrieve the default value. Returns The current value for the specified field is returned by this function. Comments Use this function in the FormLoad_Event. Example This example gets the current value for FIELD7 and places it in a variable Unisys Corporation June

22 The DTM Index Form Function: GoToField Syntax Sub GoToField(FieldName As String) Parameter Description FieldName Name of the field. Comments Set the field to where the cursor moves next. Example This example moves the cursor to FIELD2 on the form Unisys Corporation June

23 The DTM Index Form Function: MenuItemAdd Syntax Sub MenuItemAdd(MenuID As String, MenuCaption As String) Parameter MenuID MenuCaption Description Unique text string identifying the menu item. Caption for this menu item. Comments Creates a menu item on the index form. Example This example creates two menu items and names the menu Unisys Corporation June

24 The DTM Index Form Function: MenuItemDisable Syntax Sub MenuItemDisable(MenuID As String) Parameter MenuID Description Unique text string identifying the menu item. Comments This function is used to gray-out a menu item so that it cannot be selected. Example This example disables the send menu item Unisys Corporation June

25 The DTM Index Form Function: MenuItemEnable Syntax Sub MenuItemEnable(MenuID As String) Parameter MenuID Description Unique text string identifying the menu item. Comments This function allows a menu item to be selected. Example This example enables the Send menu item Unisys Corporation June

26 The DTM Index Form Function: SetFieldCheckType Syntax SetFieldCheckType(FieldName As String, CheckType As FieldCheckType) As Integer Parameter Description FieldName CheckType Name of the field Type of check to perform on the field. The following are the valid constants: NO_CHECK CHAR_CHECK FIELD_EXIT Comments Use this function to set the type of check to perform on a field. Example This example sets FIELD1 for field exit validation and FIELD5 for character checking Unisys Corporation June

27 The DTM Index Form Function: SetFieldRange Syntax Sub SetFieldRange(FieldName As String, LowValue As String, HighValue As String) Parameter Description FieldName LowValue HighValue Name of the field Value for the low end of the range. Value for the high end of the range. Comments Use this function to change the range values for a field. Example This example sets the range values to FIELD3 to 0 and the low value and 4 as the high value Unisys Corporation June

28 The DTM Index Form Function: SetFieldValue Syntax Sub SetFieldValue(FieldName As String, Value As String) Parameter Description FieldName Value Name of the field. New value for field. Comments Use this function in the FormUnload_Event to set the value of a field. Example This example set value for FIELD4 using the VarField2 variable Unisys Corporation June

29 The DTM Index Form Function: SetMenuCaption Syntax Sub SetMenuCaption(MenuCaption As String) Parameter MenuCaption Description Text for the caption of the menu in the Index Form menu bar. Comments Set the caption for the user exit menu on the index form. Example This example sets the menu caption to Terminal Unisys Corporation June

30 The DTM Index Form Function: WarningMessage Syntax Sub WarningMessage(Message As String) Parameter Message Description Text for the message to display in a message box. Comments Set the text message for a warning message that is displayed to the user. Example This example sets the message to display Unisys Corporation June

31 Section 3 Developing User Exits for the DTM Index Form Software Components The following software components are required to develop the DTM index form user exit: Visual Basic 5.0 with all service packs. Desktop Manager Index Form User Exit Visual Basic 5.0 Project files. These files are found on the Desktop Manager install CDROM in the UserExit directory. Desktop Manager must be installed on your development workstation, so that you can test your user exit. User Exit Architecture The DTM Index Form User exit is an ActiveX DLL written in Visual Basic 5.0. Desktop Manager checks for the presence of this DLL. If it is found, DTM calls the FormLoad_Event function. The FormLoad_Event function decides whether to perform user exit functions. A separate user exit must be created for each document class that requires extra validation. Version Compatibility Do not change the names or syntax of the functions in the Class module (UserExit.cls) of the user exit. If you do, DTM is NOT able to access the DLL. You must ensure that whatever changes you make keep the DLL Project compatible with the original version. For More Details see, "Version Compatibility in ActiveX Components" in Chapter 7, "Building Code Components" in the Visual Basic 5.0 Component Tools Guide. Sample User Exit Code Included on the DTM install CDROM is a sample project that illustrates how to create a user exit for your own document classes. Use the sample project as a template for your user exit Unisys Corporation June

32 Developing User Exits for the DTM Index Form Sample Steps to Implement a DTM Index Form User Exit This section describes a series of steps you can use to implement a simple user exit. We start with the files from the Sample User Exit on the install CDROM. While we can t expect to reduce the entire scope of a VB development project to a step-by-step procedure, the steps listed here show how the coding steps fit together with the imaging system components. The following procedure shows you how to set up your own code from the sample user exit code: 1. Desktop Manager is installed with the Sample Desktop and operable. 2. Use an existing document class or Create a new document class using the System Admin Tool 3. Visual Basic 5.0 and all service packs are installed. 4. Copy all files of the Sample User Exit code from the DTM Install CDROM (\UserExit\DTM\DTMIndex) to a directory under the Visual Basic 5.0 directory and name the directory using the document class name. 5. Rename DTMIndex.vbp using the document class name with the VBP as the extension. (<DocumentClass>.vbp) 6. Start VB and open the project your document class.vbp file. (If you get an invalid key error for Apartment Threading Model then the VB 5.0 service packs are not installed. You must at least install VB5 Service Pack 2.) 7. Open the UserExit class module, View the FormLoad_Event procedure. Enter the following statement: 8. In the VB5 Menu, Project Properties; In the Project Name field, change the "MyDocClass" text to the name of the document class for which you are creating a user exit. Also change the Project Description field to identify the document class this user exit is processing. 9. Compile the project (Make your DLL from the File menu of VB) and name the DLL using the document class name, <DocumentClass>.DLL. 10. Run the DTM Sample Desktop, Retrieve a document of your document class and open the index form to verify that your user exit is activated when the index form is displayed. 3 2 Unisys Corporation June

33 Developing User Exits for the DTM Index Form Registering Your New User Exit When compiling and making a DLL, Visual Basic automatically registers the DLL on your workstation. To use the DLL on another workstation you must use RegSvr32.exe to register the DLL. The syntax is: RegSvr32.exe <Path>\<DocumentClass>.dll. Handling Multiple Document Classes Perform the steps in the previous sections for each document class that requires user exit processing Unisys Corporation June

34 Developing User Exits for the DTM Index Form 3 4 Unisys Corporation June

35 Section 4 The Customized Index Form Properties The Customized Index Form User Exit allows you to create your own index form in Visual Basic for the indexing process to handle all input and validation. The following table describes the Customized Index Form User Exit Properties: Events Property Type Description Object_Class String Identifies the document class of the workitem currently being indexed. Object_ID String Identifies the ID of the workitem currently being indexed. Object_Name String Identifies the external name of the workitem currently being indexed. Object_Type String Identifies the type of the workitem currently being indexed. The following table describes the Customized Index Form User Exit Events: Event Parameters Description FormLoad Cancel As Boolean DTM activates this event when the index form should be displayed. FormShow Cancel As Boolean DTM activates this event when the index form should be re-displayed. FormUnload Cancel As Boolean, SaveOption As Boolean DTM activates this event when the user or DTM wants to close the index form Unisys Corporation June

36 The Customized Index Form Functions The following table describes the Customized Index Form User Exit Functions: Function Parameters Description GetFieldDefaultValue FieldName As String Returns the default value for a field. GetFieldFlags FieldName As String Returns the flags value for a field. GetFieldStatus FieldName As String Returns the status value for a field. GetFieldValue FieldName As String Returns the current value for a field. SetFieldValue FieldName As String, Value As String Changes the value for a field. NotifyClient EventType As EventType_Int Raises an event to DTM. Use this to notify DTM that the index form is closed and whether to the save changes. 4 2 Unisys Corporation June

37 The Customized Index Form Event: FormLoad_Event Syntax Sub FormLoad_Event(Cancel As Boolean, Reserved As Boolean, Modal As Boolean) Parameter Cancel Reserved Modal Description Flag that determines whether this user exit will handle the index form for this document class. If you do not want to process this Object and want DTM to display the DTM index form set Cancel to True. Flag that identifies whether the object is reserved for changes. Flag that identifies whether the index form should be displayed as modal or modeless. Comments Add code to display the appropriate Visual Basic Form. In the Visual Basic forms, use GetFieldValue to get the current values of each index field, or use the FormField collection to enumerate through the index fields. Use the SetFieldValue function to update the fields that you wish to be changed. You must also raise the event NotifyClient to signify to DTM that the Index Form is closed and pass the parameter whether DTM should update the changes or discard them. The syntax is as follows: or Unisys Corporation June

38 The Customized Index Form Example This example tests for the MyClass document class and creates an instance of the appropriate Visual Basic form and displays it. 4 4 Unisys Corporation June

39 The Customized Index Form Event: FormShow_Event Syntax Sub FormShow_Event() Parameter Description Comments None This event is called when the form should be redisplayed. Example This example redisplays the Visual Basic form mform Unisys Corporation June

40 The Customized Index Form Event: FormUnload_Event Syntax Sub FormUnload_Event(Cancel As Boolean) Parameter Cancel Description Flag that determines whether the user exit will close the form. Set Cancel to True to specify that the form will not be closed by the user exit. Comments This event is called when DTM or the user needs to close the index form. Example This example unloads the Visual Basic form mform. 4 6 Unisys Corporation June

41 The Customized Index Form Function: GetFieldDefaultValue Syntax Function GetFieldDefaultValue(ByVal FieldName As String) As String Parameter Description FieldName Name of the field to retrieve the default value. Returns The default value for the specified field is returned by this function. Comments Use this function in the FormLoad_Event. Example This example gets the default value for FIELD4 and places it in a variable Unisys Corporation June

42 The Customized Index Form Function: GetFieldFlags Syntax Function GetFieldFlags(ByVal FieldName As String) As FieldFlags_lng Parameter FieldName Description Name of the field to retrieve the flags value. Returns The flags value for the specified field is returned by this function. The flags field can be a combination of values. Use the FieldFlags_lng enumeration to determine which flags are set. FieldFlags Enumeration Required = 1 DisplayOnly = 2 NoEcho = 4 UpperCase = 8 RighttJustify = 16 AutoClear = 32 AutoAdvance = 64 GroupTab = 128 RetainZeros = 256 YesNo = 512 Verify = 1024 Scratch = 2048 ValueList = Unisys Corporation June

43 The Customized Index Form Example This example gets the flags value for FIELD7 and places it in a variable and then does a check to see is the field is a required entry Unisys Corporation June

44 The Customized Index Form Function: GetFieldStatus Syntax Function GetFieldValue(ByVal FieldName As String) As FieldStatus_lng Parameter FieldName Description Name of the field to retrieve the status value. Returns The status value for the specified field is returned by this function. FieldStatus Enumeration Example KeyVerify = 1 OCRVerify = 2 KeyUpdate = 4 ReadOnly = 8 ReadOnlyOverride = 16 This example gets the status value for FIELD7 and places it in a variable and then does a check to see is the field is read only. If it is a read only field then lock the control so that no one can enter data into it Unisys Corporation June

45 The Customized Index Form Function: GetFieldValue Syntax Function GetFieldValue(ByVal FieldName As String) As String Parameter Description FieldName Name of the field to retrieve the current value. Returns The current value for the specified field is returned by this function. Comments Use this function in the FormLoad_Event to retrieve the value of a field. Example This example gets the current value for FIELD7 and places it in a variable Unisys Corporation June

46 The Customized Index Form Function: SetFieldValue Syntax Sub SetFieldValue(FieldName As String, Value As String) Parameter Description FieldName Value Name of the field to set the value. New value for field. Comments Must use this function in the FormUnload_Event to change a value for a field. Example This example sets value for FIELD4 using the VarField2 variable Unisys Corporation June

47 The Customized Index Form Function: NotifyClient Syntax Event NotifyClient(EventType As EventType_Int) Parameter EventType Type of event to signify to DTM: FORM_CLOSED_SAVE_CHANGES or FORM_CLOSED_DISCARD_CHANGES Description Comments Use this function when the indexing form is closed. Example This example raises an event to DTM with the FORM_CLOSED_SAVE_CHANGES option Unisys Corporation June

48 The Customized Index Form 4 14 Unisys Corporation June

49 Section 5 Developing Visual Basic Index Forms Software Components The following software components are required to develop the customized index form user exit: Visual Basic 5.0 with all service packs. Desktop Manager Customized Index Form Visual Basic 5.0 Project files. These files are found on the Desktop Manager install CDROM in the UserExit directory. Desktop Manager must be installed on your development workstation, so that you can test your user exit. User Exit Architecture The Customized Index Form User exit is an ActiveX DLL written in Visual Basic 5.0. Desktop Manager checks for the presence of this DLL. If it is found, DTM calls the FormLoad_Event function. The FormLoad_Event function decides whether to process the request or let DTM display the standard index form. The User exit is defined using with Events. This is the mechanism used to communicate back to DTM that the Index form is closed. The User exit can notify DTM to save changes or discard changes via the defined event. DTM checks the parameter and save the index values, if so specified. The user exit must allow multiple index forms to be displayed concurrently. To do this the user exit must create a new instance of the Visual Basic form in the FormLoad_Event function. Version Compatibility Do not change the names or syntax of the functions in the Class module (UserExit.cls) of the user exit. If you do, DTM is NOT able to access the DLL. You must ensure that whatever changes you make keep the DLL Binary compatible with the original version. For More Details see, "Version Compatibility in ActiveX Components in Chapter 7, "Building Code Components" in the Visual Basic 5.0 Component Tools Guide Unisys Corporation June

50 Developing Visual Basic Index Forms Sample User Exit Code Included on the DTM install CDROM is a sample project that illustrates how to use a Visual Basic Form in the user exit as an index form. MyForm.frm is the sample Visual Basic Form that is used. You can use this as a model for your own VB Form. Use the steps listed in the next section to modify this project with the field names from your document class to test how the index form user exit works. You can include/create additional VB modules to do processing of the index values. The Form_Load function of MyForm.frm shows how to handle form views using the flags and status properties, display the current field values and how to deal with a value list. The Form_Unload function of MyForm.frm shows how to update field values after the user has made changes. Sample Steps to Implement an Index Form User Exit This section describes a series of steps you can use to implement a simple user exit. We start with the files from the Sample User Exit on the install CDROM. While we can t expect to reduce the entire scope of a VB development project to a step-by-step procedure, the steps listed here show how the coding steps fit together with the imaging system components. The following procedure shows you how to set up your own code from the sample user exit code: 1. Desktop Manager is installed with the Sample Desktop and operable. 2. Use an existing document class or Create a new document class using the System Admin Tool 3. Visual Basic 5.0 and all service packs are installed. 4. Copy all files of the Sample User Exit code from the DTM Install CDROM (\UserExit\DTM\DTMForm) to a directory under the Visual Basic 5.0 directory. 5. Start VB and open the project DTMForm.vbp (If you get an invalid key error for Apartment Threading Model then the VB 5.0 service packs are not installed. You must at least install VB5 Service Pack 2.) 6. Pick four fields from your document class to use in this sample. The last field on the form is a combo box control (combo1), pick a field that has a values list for that field. This shows you how values list can be used. 7. Open the UserExit class module, in the FormLoad_Event procedure, find the following statement and replace ProdLine with the name of your document class: 8. Open MyForm.frm and change the Caption property of the four label fields to names that match the four fields you chose in step In the FormLoad procedure of MyForm.frm, change the names of the index fields to the four selected in step Unisys Corporation June

51 Developing Visual Basic Index Forms 10. In the FormUnload procedure of MyForm.frm, change the names of the index fields to the four selected in step Compile the project (Make DTMForm.dll from the File menu of VB). 12. Run the DTM Sample Desktop, Retrieve a document of your document class and open the index form to verify that your index form is displayed. Registering Your New User Exit When compiling and making a DLL, Visual Basic automatically registers the DLL on your workstation. To use the DLL on another workstation you must use RegSvr32.exe to register the DLL. The syntax is: RegSvr32.exe <Path>\DTMForm.dll. Handling Multiple Document Classes To create an index form for an additional document class add another Visual Basic form to the project and in the FormLoad_Event of the UserExit class module, add code similar to what is already there for the sample document class ProdLine Unisys Corporation June

52 Developing Visual Basic Index Forms 5 4 Unisys Corporation June