Customer Portal

If you haven’t already, register for the Customer Portal: unlock a wealth of useful information and submit cases in an easier, more efficient way! Find out more here.

Key issues when automating OyezForms

Launching OyezForms in dotnet

Applications automating OyezForms should use either the oyezfrms.tlb type library file or the OyezV8EZ.ocx control (for early binding), both of which are installed to the application directory. Dotnet programmers who wish to launch OyezForms from a non-form context should use InteropServices to access the .tlb (see example code).

Oyezforms has several dispatch interfaces providing automation, only the OyezAutomation interface should be used by other applications. Only one instance of OyezForms can be created. Only the currently active form can be manipulated. OyezForms does not support a collection of open forms.

Referencing the .OCX control (recommended)

  1. In a form's design view, right-click in the 'General' area of the Toolbox panel and select 'Choose Items...'
  2. In the 'Choose Toolbox Items' dialog, select the 'COM Components' tab
  3. Scroll down the list of components and put a tick next to 'OyezV8EZ', then click 'OK'.
  4. The ocx will appear on the Toolbar. Double-click on it to add it to your application's form.
  5. In the 'Solution Explorer' tree, a reference named 'AxOyezV8EZ1' will be created.

Referencing the .tlb file using InteropServices (if your project has no form object)

  1. Select 'Add reference' in your project.
  2. choose 'Browse', and select oyezfrms.tlb (installed to the application folder)
  3. using System.Runtime.InteropServices;
    Type OyezAp = Type.GetTypeFromProgID("OyezLegalForms.Application");
    OyezFrms.OyezAutomation oa = (OyezFrms.OyezAutomation)Activator.CreateInstance(OyezAp);

If you use the .tlb for automating OyezForms, you will should only use the .methods() provided by OyezForms, not .Properties. This is due to issues with DotNet's handling of properties declared in the type library. Properties are listed below with their replacement method. Upgrade to OyezForms v10.01K+.

  Property Replacement Method
  .fieldlist .getfieldlist()
  .fields .getfields()
  .field .getfields()
  .form .getfoms()
  .library .getlibrary()
  .pages .getpages()
  .page .getpage()
  .error .geterror()

Retrieving a list of available forms

OyezForms stores data about its current library of forms in the mastlibr.mdb access database.

Locate mastlibr.mdb as follows:

  1. If HKCU\Software\Oyez\Oyez Legal Forms\User\LibraryPath string value is present, use this and append master\mastlibr.mdb
  2. Else, construct path from .executablepath() and append \library\master\mastlibr.mdb

You can query the mastlibr.mdb to retrieve the following fields from the LegalForms table:

<formname>
<Description>
<Revision> (YYYYMMDD)
<Copyright> (used to show last relevant EFIS release see Editorials)
<CategoryID> (links to Category table, below)
<OyezID> (Oyez's stable ID, assigned to each form)
<path> (CategoryID-OyezID-alpanumeric representation of revision)
<RevLetter> See table, below.

Multiple revisions will exist in the database for most forms. Descriptions may occasionally change across revisions. The Categories table lists Oyez's form range organisation. The <CategoryID> field links to the <Category> field in the LegalForms table.

  • SELECT Categories.Category, LegalForms.* FROM LegalForms INNER JOIN Categories ON LegalForms.CategoryID = Categories.CategoryID WHERE RevLetter = 65 AND pages <> -2 ORDER BY Categories.Category, LegalForms.FormName

The above query is the simplest way of returning an up-to-date list of legal titles in the library. The filter on -2 in the pages field removes Word Templates which should be treated as normal Word resources in your software, see Developers word templates. Locks on the database should only ever be read-only. The table contents should never be changed.

The RevLetter field contains 3 possible values indicating a form revision's status. These may be used to alter your selection:

65 Form is live, and this revision is the most recent. It will display in FILE>NEW by default, unless its date lies in the future.
66 This is an older revision of a 'live' form. See 65, above. It will not display in FILE<NEW unless 'show all revisions' is checked, or the newer revision has a future date.
24 Form is no longer editorially 'live' and will not appear in File>New unless 'show all revisions' is checked.

 

Mapping data to OyezForms fields

Note: Word Templates supplied by Active Library cannot be filled via the OyezForms api. See technical discussion.

Data from your application can be inputted into fields on any form after it is created by the new command.

When retrieving label or fieldID lists, you should first specify the page to be interrogated via the .selectpage command.

OyezForms supports descriptive fieldlabels that are stable across pages, form revisions, and within a range of forms. We strongly recommend using fieldlabels as your primary route for mapping data to OyezForms via the .fill command. A list of labels on the current page of a form can be retrieved programmatically via the .labellist command < .labellist().Split(',') >.

As fieldlabels were introduced during the lifetime of OyezForms, a number of less-frequently updated forms do not have fieldlabels. If creating a mapping interface for your users, you should ensure they also have the option to target OyezForms' numeric fieldIDs, using the .fillat command. A list of FieldIDs for the current page can be retrieved programmatically via the .fieldlist property. FieldIDs repeat across pages, and are not stable between form revisions; if extra fields are added to a page, the ID sequence will be reset.

You can find a field label associated with a fieldID by calling .getlabel using a fieldID as parameter.

OyezForms users can see where fieldlabels/fieldIDs appear on any form by selecting Tools>Options>PrintLabels/PrintIDs

Printing from OyezForms

The targetprint command allows you to programmatically target a selected printer, tray and duplex option, ready for printing via a subsequent print command.

< .targetprint("HP LaserJet 1020", 2, 0) >   uses tray 2 on the specified printer without duplex printing.

Targetting last until program session finshes. It should be followed by the print command:

< .print(4, axOyezV8EZ1.Pages); >

The above example prints page 4 through to the last page of the currently active form. When using the print command without targetprint, OyezForms will auto-target a printer in the following order:

  1. As set by OyezForms user in Tools>Options>Print:'Initial Printer'
  2. The operating System's default printer

You can control which pages are printed by using the setpagestoprint command.

Exporting PDFs from OyezForms

The exporttopdf command allows you to save a form as a flattened PDF file. This export cannot be subsequently re-edited, so should be used as an archive, or as a 'for signature' option. The export process is not synchronous, so it may be desirable to check for the task to finish via Actioncomplete.

  • oa.exporttoPDF(@"c:\temp\out.pdf");
    while (oa.ActionsComplete() != true)
    {
    System.Windows.Forms.Application.DoEvents();
    }

The PDF export facility is based on novaPDF technology and is silently installed in standalone installs. This is also the case in the manual attachment of client PCs to a networked copy of OyezForms (see install help); however, if Active Directory is used with the \setup\setup_AD.msi file to roll out the attachment of client PCs, then the user will need to invoke File > 'Export to PDF' once in order to install the required components.

See also: Configuring OyezForms' PDF engine