Skip to main content

Migration and Conversion Utilities

This chapter discusses some specialized tools and techniques that can be used when migrating a Caché database to a new system.

  • Using cvendian to Convert Between Big-Endian and Little-Endian Systems — describes a utility to convert the byte order of a Caché database for migration between Big-endian and Little-endian platforms. It also provides an option to report on the byte order of a given database.

  • Using cdbmerge To Consolidate Database Extents Into One File describes the cdbmerge utility, which that is useful if you use Caché extents. In past releases, Caché allowed a single database to span multiple files called extents, partly to avoid the limitations of disk hardware and filesystems at that time. These limitations no longer apply, and Caché no longer supports extents. The cdbmerge utility enables you to consolidate an extent-style database into a single database file.

  • Converting FileMan Files into Caché Classes — describes FileMan Mapping Utility, which reads files created by FileMan (metadata utilities for MUMPS applications) and generates Caché classes that map them.

  • WebLink Developer Tags for Conversion to CSP — describes a set of WebLink Developer tags that can be useful when migrating applications from Weblink Developer to Caché Server Pages (CSP).

Using cvendian to Convert Between Big-Endian and Little-Endian Systems

Caché provides a utility to convert the byte order of a Caché database from Big-endian (that is, most-significant byte first) to Little-endian (that is, least-significant byte first), and vice versa. It is called cvendian, for convert endian. This is useful when moving a database among platforms of the two types. It also provides an option to report on the byte order of a given database.

For information about the Endianness of supported platforms, see “Platform Endianness” in the online InterSystems Supported PlatformsOpens in a new tab document for this release.

Important:

This utility cannot be used on a mounted database.

Location of Utility

The cvendian utility is the file install-dir\Bin\cvendian.exe.

Conversion Process

You can run cvendian on either the system that has the files to be converted or the system that will be using the converted files.

For example, to convert a database from a Little-endian to a Big-endian system, you can perform the conversion on the Little-endian system and then transfer the database to the Big-endian system, or you can transfer the file first, and then convert it.

Note:

This utility does not work for backup and journal files. You must restore databases on a platform of the same endian, move the restored databases to the different endian platform, and then use the cvendian utility to convert the databases.

To convert a database, the process is:

  1. Make a copy of your database files, because the utility replaces the source files with the converted files.

  2. Run cvendian using the syntax described in the “Utility Syntax” section.

Utility Syntax

With the cvendian endian utility, you can specify the desired byte order, or you can report the current byte order without conversion. Use the following syntax:

cvendian [-option] file

The option argument is one of the following:

  • -big — convert the database to Big-endian

  • -little — convert the database to Little-endian

  • -report — report the byte order of the database

You can shorten the options to their initial letter. If this is a conversion request (-big or -little), and the database already has the specified byte order, the utility displays a warning message and stops processing.

If you do not provide the option argument, the utility converts the database from the existing byte order to the other byte order. It is recommended, however, that you use the option argument.

The file argument is the file to convert, and can include a complete pathname.

The utility performs the following actions:

  • Auto-detects the byte order of the database

  • Displays endian information and other information

  • Performs the conversion

  • Displays a message indicating success or failure

Example

For example, suppose you are converting a database for use on IBM AIX® for Power System-64 from Windows Server 2016. This means you must convert from Little-endian (for Intel) to Big-endian (for POWER). The output from running cvendian on the Windows system before moving the file to the AIX system looks similar to this:

C:\CacheSys\Bin>cvendian -big c:\temp\powerdb\cache.dat

This database is little-endian.
This database has a block size of 8192 bytes.

This database has 1 volume and 1 map.
The last block in the primary volume is 18176.

Original manager directory is c:\temp\powerdb\

No extension volumes.

Done converting c:\temp\powerdb\cache.dat to big-endian

C:\CacheSys\Bin>

You can now move the converted database file to the AIX system.

Using cdbmerge To Consolidate Database Extents Into One File

Historically, Caché allowed databases to span multiple files called extents. This was due, in part, because of the disk hardware and filesystems were unable to support files large enough to contain the entirety of a database.

Advances in storage technology and in filesystem capabilities have removed that impediment. As a result, the support for extents is no longer needed. In Caché version 2010.1, support for extents was deprecated; in version 2014.1, it was removed entirely.

Occasionally, however, it is necessary to mount and read extent-style databases. To address this issue, beginning with version 2012.2.4, InterSystems provides a stand-alone utility to consolidate a directory containing a database and its extents into a single cache.dat database file. That utility is called cdbmerge. It is located in the Bin subdirectory of <install_dir>.

To effect this conversion, do the following:

  1. Restore the database and extents to be consolidated to its own directory.

  2. Run the cdbmerge utility on that directory.

  3. Configure and mount the converted database on Caché.

The cdbmerge command has two forms:

cdbmerge <Original_Dir>

cdbmerge -srcdir <Original_Dir> -destdir <Final_Dir>

where

  • <Original_Dir> is the location of the directory containing the base cache.dat file and its associated extents

  • <Final_Dir> is the (optional) location of the merged cache.dat. If not specified, the database will be merged in place.

Note:

InterSystems recommends having a copy of the <Original_Dir> available before doing the merge as a safeguard against unexpected errors.

Converting FileMan Files into Caché Classes

FileMan is a set of utilities that provide metadata storage, access, and manipulation for MUMPS applications. This section describes how to map FileMan files to Caché classes. The FileMan source code is in the public domain and is not provided by InterSystems. However, Caché provides the FileMan Mapping Utility, which reads files created by FileMan and generates Caché classes that map them.

This section discusses the following topics:

This section assumes that the FileMan globals (^DD and ^DIC) are already loaded into the desired namespace in your system.

Overview of the FileMan Mapping Utility

The FileMan wizard enables you to quickly and easily create custom class mappings for your FileMan files. The classes created by the mapping utility enable you to access the file data via ObjectScript and via SQL. You can map just one, many, or all FileMan files in a namespace. For each file, you can control details such as the following:

  • Which fields are mapped

  • Whether the classes are read-only or have write access

  • Formats for the names of the generated classes and properties (tables and fields)

  • The superclass list for the generated classes

  • Whether word-processing fields are mapped as list collections or as child tables

Accessing the FileMan Wizard

To access the FileMan wizard:

  1. Open the Management Portal.

  2. Click System Explorer > SQL.

  3. Check the namespace in the header. Click Switch to change to the correct namespace, if necessary.

  4. Click Wizard > FileMan.

On this page, you can do the following:

  • Specify the default settings to use when mapping FileMan files.

  • Map one, some, or all of the FileMan files in the current namespace, thus generating Caché classes.

  • View the log for past mapping activities.

  • View any background tasks.

Specifying the Default Settings

The FileMan wizard uses many settings that control how it generates classes. It is worthwhile to review these settings, modify them to values that you use most of the time, and save these as the default settings.

To modify the settings:

  1. Open the Management Portal.

  2. Click System Administration > Configuration > SQL and Object Settings > FileMan Conversion Settings.

  3. Make changes as needed and click Save.

Or access the wizard as described in “Accessing the FileMan Wizard”, modify the values on the first page, and then click Save As Default.

The available settings are as follows:

  • Owner of the Classes Created — Specifies the username to use as the owner of the classes created. The default is the current value in $Username.

  • Package Name to Create the Classes in — Specifies the name of the package to create the classes in.

    Note:

    If you previously mapped to one package and map the FileMan files again to a new package, the old classes are not automatically deleted.

  • Super Classes — Specifies the superclass list for each of the mapped classes. Specify a string with a comma-separated list of class names.

  • Table Name Format Based on the File Name and Number — Specifies the format of the generated table name. For this setting, specify a string that uses the following keywords along with any characters that are valid to use as table names:

    • <FILENAME> — Replaced with the name of the FileMan file

    • <FILENUMBER> — Replaced with the file number

    If you use <FILENAME>, any decimal place characters in the file number are converted to underscore characters.

    See the examples for Child Table Name Format Based on the File Name and Number.

  • Child Table Name Format Based on the File Name and Number — Specifies the format of the generated child table names. For this setting, specify a string that uses the following keywords along with any characters that are valid to use as table names:

    • <FILENAME> — Replaced with the name of the FileMan file

    • <FILENUMBER> — Replaced with the file number

    • <PARFILENAME> — Replaced with the name of the parent file

    • <PARFILENUMBER> — Replaced with the file number of the parent file

    If you use <FILENAME> or <PARFILENUMBER>, any decimal place characters in the file number are converted to underscore characters.

    Some examples of this setting:

    • SUB_<FILENAME> — In this example, the table name of a child table is the string SUB_followed by the name of the file. For example: SUB_ACCESSIBLE_FILE

    • f<PARFILENUMBER>c<FILENUMBER> — In this example, the table name of a child table is the string f, followed by the number of the parent file, followed by c, followed by the number of this file. For example: f200c200_032

    • <FILENAME> — In this example, the child table name is simply the same as the filename.

  • Maximum length of Property, Trigger, and Foreign Key names — Specifies the maximum length of property names, foreign key names, and trigger names produced by this utility. The default is 180, which corresponds to an increase in the length of Caché class member names in a recent release. Use this option if you want to keep the names of these items at the previous shorter maximum (31 characters).

  • Field Name Format Based on the Fileman Field Name — Specifies how the utility will generate the SQL field name. Choose of the following:

    • Exact — The SQL field name will use exactly the same case as the FileMan field name. For example, FileMan field 'DEA EXPIRATION DATE' becomes SQL field name 'DEA_EXPIRATION_DATE'.

    • Upper — Letters in the FileMan field name are folded to upper case to generate the SQL field name. For example, FileMan field 'DEA expiration date' becomes SQL field name 'DEA_EXPIRATION_DATE'.

    • Lower — Letters in the FileMan field name are folded to lower case to generate the SQL field name. For example, FileMan field 'DEA EXPIRATION DATE' becomes SQL field name 'dea_expiration_date'.

    • Pascal — The first letter in the identifier and the first letter of each subsequent concatenated word are capitalized. Also, spaces and underscored are removed. For example, FileMan field 'DEA EXPIRATION DATE' becomes the SQL field name 'DeaExpirationDate'.

    • Camel — Thee first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is capitalized. Also, spaces and underscored are removed. For example, FileMan field 'DEA EXPIRATION DATE' becomes the SQL field name 'deaExpirationDate'.

  • Datatype to use for FileMan Date fields — Specifies the data type to use when mapping FileMan DATE fields. The default is %Library.FilemanDateOpens in a new tab.

  • Datatype to use for FileMan DateTime fields — Specifies the data type to use when mapping FileMan DATE/TIME fields. The default is %Library.FilemanTimeStampOpens in a new tab.

  • Define STRICTDATA=1 for %FilemanData* datatypes — Specifies whether the generated classes include STRICTDATA=1 in the definitions of any properties of type %Library.FilemanDateOpens in a new tab and %Library.FilemanTimeStampOpens in a new tab.

    This STRICTDATA parameter affects the LogicalToOdbc() and LogicalToDisplay() methods for these data types. When STRICTDATA=0, the default, the methods will contain the same code they did previously. When STRICTDATA=1, the code in the LogicalToFormat() methods that handles invalid Logical date and time values is removed. Use STRICTDATA=1 if your database contains invalid or incomplete date or time values, and you do not want assumptions made about what the correct data should be.

  • Expand Pointers? — Specifies whether the utility creates additional computed properties to expand the pointer field. Select one of the following options:

    • No — The utility does not add any computed properties to expand the pointer field.

    • Yes(1) - As FIELD and FIELD_NAME — The utility adds a computed property that expands the pointer field and is equal to the NAME (.01) field in the referenced file.

    • Yes(2) - As FIELDID and FIELD — The utility adds a computed property that expands the pointer field and is equal to the NAME (.01) field in the referenced file. The naming conventions used for this option is the pointer field will be named after the referenced file with “_ID” appended to the field name.

    • Yes(3) - As FIELD_fPointerFilenID and FIELD – This option is the same as 2 except that the name of the reference field will be <Field>_f<pointed-to-file-id#>ID.

  • Expand Set Of Codes fields — Specifies whether to define an expanded SOC (SetOfCodes) table for each Set Of Codes field that is mapped.

    • If this option is Yes, then for each such field that is mapped to a class, the utility will generate a read-only class/table that maps to the CODE and MEANING of the Set Of Codes. The name of the table is <tablename>_SOC_<fieldname>. The SOC table has two fields. CODE maps to the name of the CODE and MEANING is the external meaning for the CODE. This table is mapped directly to the ^DD global, so any updates to the definition in the ^DD global will be immediately reflected in the data returned by the table.

    • If this option is No (the default), these SOC class/tables will not be created.

  • Create Value for Variable Pointer fields? — Specifies how to handle variable pointer fields. If this option is selected, then for each variable pointer field mapped, FM2Class will also create a computed property that expands the variable pointer field value and is equal to the .01 field in the referenced file. This field will be named <Variable_Pointer_Field_VALUE>.

    For example, an FM variable pointer field WHO is defined to point to either the EMPLOYEE file or the PATIENT file. By default, FM2Class creates two fields, one that points to the EMPLOYEE file and another one that points to the PATIENT file. Only one of these fields will be non-NULL. If WHO is an EMPLOYEE, the WHO_EMPLOYEE field will contain the ID/IEN of the EMPLOYEE. If WHO is a PATIENT, WHO_PATIENT will contain the ID/IEN of the PATIENT.

    If this setting is selected, FM2Class also creates third field, WHO_VALUE, which computes to the .01 field of the EMPLOYEE record if the WHO points to an EMPLOYEE, or the .01 field of the PATIENT record if WHO points to a PATIENT. If this setting is cleared, FM2Class does not create this third field.

  • Define Set Of Codes fields as type? — Specifies the data type to use when mapping a Set Of Codes field. The options are %Library.EnumStringOpens in a new tab (the default) and %Library.StringOpens in a new tab.

    Using %Library.EnumStringOpens in a new tab provides an advantage because it provides the OdbcToLogical() and LogicalToOdbc() methods, which allow you to use the meaning of the Set Of Codes, rather than the code value from xDBC client applications.

  • Define Required Properties for — Controls which required FileMan fields are defined as required properties.

    • If this setting is REQUIRED FIELDS (the default), FileMan fields marked as required are defined as required properties.

    • If this setting is REQUIRED IDENTIFIERS, only FileMan fields defined as Required Identifiers are defined as required properties.

  • Extended Mapping — Specifies a string to be inserted into the global name in the map definitions for extended mapping purposes. For example, you might specify ["SD"] and your global is mapped as ^["SD"]LR(...) instead of ^LR(...).

    This can be any valid string that can be used for extended global mapping and must include the [...] or |...| brackets.

  • Name of the IEN Field — Specifies the name of the IEN field, which is IEN by default.

  • Retain Class? — Specifies whether to recreate the entire class if it already exists.

    • If this setting is No, the utility deletes and recreates the class, which means that SQL privileges and any add-ons to the class are lost.

    • If this setting is Yes, the utility recreates the properties, storage, indexes, foreign keys, and so on, rather than the entire class. Notes:

      • You must have run the FM2Class utility at least once with the Caché 2010.2 or higher before manually adding your own items to the class definition; this is necessary because earlier versions do not save the required metadata needed for this feature.

      • After mapping a class, if you move the class to another namespace or another system, and attempt to map it again from the new location with the Retain Class? set to Yes, you must also manually move/copy the ^oddFMD global too, because this global stores the metadata required by the Retain Class? feature.

      • The Retain Class? feature is not meant to work with SOC classes produced when you set the Expand Set Of Codes fields to Yes; that is, if you add your own parameters, properties, indices, and so on to these classes, those changes are not retained, even if Retain Class? is set to Yes.

  • Recursion — Controls whether sub-files and pointer are also mapped:

    • If this setting is No recursion, only this file is mapped. No sub-files or pointers are mapped.

    • If this setting is Partial recursion, the file is mapped, along with one level of sub-files and pointers.

    • If this setting is Full recursion, the file is mapped, along with all sub-files and pointers. This is the default.

  • Word-Processing Fields Conversion – Specifies how to map word-processing fields. Select Convert as child tables > Convert as list collections, or Convert as list collections and child tables.

  • Read Only? — Specifies whether the generated classes should be read-only.

  • Log File — Specifies the name of the file into which the utility should log output. Click Browse... and select a file. Or type a filename.

  • Compile Classes? — Specifies whether to compile the classes after creating them.

  • Compile Flags — Specifies any class compiler qualifiers and/or flags.

  • Delete Flags — Specifies any class deletion qualifiers and/or flags.

  • Display Result — Controls how the results are displayed. Select Full screen display (the default), Minimal screen display, or No screen display.

Mapping FileMan Files

To map FileMan files to Caché classes:

  1. Access the FileMan wizard (see “Accessing the FileMan Wizard”).

  2. Optionally change settings on the first page of the wizard. For information on the settings, see the previous section, “Specifying the Default Settings”.

  3. Click Next.

    You use the next page of the wizard to specify which files to map.

  4. Enter a complete or partial file name and click Search.

    The wizard displays all the FileMan files in this namespace that start with the given string.

  5. Do one of the following:

    • Click Map All. The wizard prompts you for confirmation. Click OK.

      The wizard immediately starts a background task that maps the files. The remaining steps in this section do not apply in this case.

    • Click Select All. Then click Next.

    • Click the Select link for one or more files. For each file, the wizard displays a list of the fields to map (all fields by default). Optionally double-click a field if you do not want to map it. When you are done selecting files and their fields, click Add to Cart.

    • Click the Add to Cart link for one or more files. With this option, all fields are mapped, but the wizard operates more quickly because it does not need to retrieve the fields at this stage. After selecting the files, click Next.

  6. Review the selected files.

    The wizard displays your selected files in a tree, with fields for each file. If you want to remove any of them, click a file name then click the "Remove" link above the tree. If you click a field then click "Remove" then the file name for that field is removed too. If you want to empty the Cart (remove all of them), just click the "Clear Cart" link above the tree.

  7. Optionally do any of the following:

    • Remove a file, by clicking the file name and then clicking the Remove link above the tree.

    • Remove a field, by clicking the field name and then clicking the Remove link.

    • Remove all files, by clicking Clear Cart. (If you do this, the wizard returns to the previous page.)

  8. Click Finish.

    The wizard then starts the background job that map the files.

Programmatic Access

The FileMan wizard uses the %fm2class routine, which is installed as part of Caché and Ensemble 2009.1.

You can also obtain this routine as an XML file and install it in Caché or Ensemble version 5.0.* or higher.

This section describes how to install this routine, if needed, and how to use it. Rather than invoking the routine directly, you use the methods in $SYSTEM.OBJ.FM2Class.

System Requirements

You must be running a standard Caché or Ensemble installation, version 5.0.* or higher.

You need a working FileMan installation.

Installing the Routine on Earlier Product Versions

The %fm2class routine is delivered as an XML file that can be loaded into the system. To install on Caché or Ensemble version 5.1 or higher:

  1. First make sure the CACHELIB database is not mounted read only.

  2. Then load the XML file into the %SYS namespace using the following command:

    Do $SYSTEM.OBJ.Load("C:\Kits\FM2Class_v101.xml","psc") 
    

    Replace "C:\Kits\" with your actual path name. You are now ready to run the utility.

To install on Caché or Ensemble version 5.0, contact InterSystems Support for assistance.

Specifying Configuration Settings

The %fm2class routine uses the same settings that you specify in the FileMan wizard, as shown in the following table. For any setting that is displayed as a drop-down list, the following table indicates the corresponding values to use. For all yes/no settings, 1 means yes, and 0 means no. For other settings, use the same value as documented for the wizard.

Setting Name in FileMan Wizard Internal Name of Setting; Notes
Owner of the Classes Created owner
Package Name to Create the Classes in package
Super Classes superClasses
Table Name Format Based on the File Name and Number tableNameFormat
Child Table Name Format Based on the File Name and Number childTableNameFormat
Maximum length of Property, Trigger, and Foreign Key names nameLength
Field Name Format Based on the Fileman Field Name fieldNameFormat
Datatype to use for FileMan Date fields dateType
Datatype to use for FileMan DateTime fields datetimeType
Define STRICTDATA=1 for %FilemanData* datatypes strictData
Expand Pointers? expandPointers
Expand Set Of Codes fields xpandSetOfCodes
Create Value for Variable Pointer fields? variablePointerValueField
Define Set Of Codes fields as type? setOfCodesEnum
Define Required Properties for Fields that are requiredType
Extended Mapping extendedMapping
Name of the IEN Field ienFieldName
Retain Class? retainClass
Recursion recursion

0 means no recursion, 1 means partial recursion, and 2 means full recursion.

Word-Processing Fields Conversion wpIsList
Read Only? readonly
Log File logFile
Compile Classes? compile
Compile Flags compileQSpec
Delete Flags deleteQSpec
Display Result display

0 means no display, 1 means minimal display, and 2 means full display.

To modify the default settings, use a command like the following:

Set ^%SYS("sql","fm2class",setting) = value

Where setting is an internal setting name as shown in the previous table, and value is the value to assign to it.

When you use the %fm2class routine, you can pass in an array of the following format:

arrayName(setting) = value

For example:

%fm("display")=1 
%fm("package")="VISTA" 
%fm("superClasses")="%XML.Adaptor" 
%fm("wpIsList")= 1  

Mapping FileMan Files Programmatically

As noted earlier, rather than invoking the %fm2class routine directly, you use methods in %System.OBJ.FM2Class, as follows:

  • To map all FileMan files in the current namespace:

     Do $SYSTEM.OBJ.FM2Class.All(.fmSettings, .classCount)
  • To map one FileMan file:

     Do $SYSTEM.OBJ.FM2Class.One(fileNumber,.fmSettings,.fmFields,.classCount) 
  • To map some of FileMan files in the current namespace:

     Do $SYSTEM.OBJ.FM2Class.Some(fileList,.fmSettings,.fmFields,.classCount)

The arguments are as follows:

  • fmSettings is an optional array passed by reference with any settings you would like the utility to use, as described earlier in this section.

  • classCount is optional and is also passed by reference. It returns the number of classes created by the mapper utility.

  • fileNumber is the FileMan file number of the file you want to map.

  • fmFields, if defined, limits the fields in the file that are mapped. This is an array of the form fmFields(file-number,field-number). Any required fields and fields defined in this array are mapped in the class definition. If this array is empty or not defined, all fields in the file are mapped. This array is passed by reference.

  • fileList is the FileMan file numbers of the files you want to map. Specify a comma-delimited list of file number or ranges of file numbers. Or specify an array of file numbers passed by reference.

The class %System.OBJ.FM2Class also provides the methods Version() and GetVersion().

Next Steps

After using the conversion utility, you should verify that you have SQL access to the generated classes. To do so, use Management Portal. At a minimum, check that you can do the following:

  • Browse the schema.

  • Execute SQL queries against the new classes.

It may also be necessary to create global and routine mappings in the namespace. Check the routines used in your generated classes to be sure that all of them are available in this namespace.

Notes

This section contains notes about how the %fm2class routine generates Caché class definitions.

Basics

To orient yourself, you may find it helpful to compare a simple FileMan file to the resulting Caché class definitions.

Consider the simple example of a file called PostalCode. If we look at the file attributes for this file (via the FileMan Data Dictionary Utility), we see the cross-references and indices for this file. For example:

generated description: convert afileman attributes

The same utility also shows us the definitions of the fields in this file. In this case, the titles of the fields are as follows (when listed alphabetically)

  • City

  • City Abbrevation

  • City Key

  • County

  • Inactive Date

  • Mail Code

  • Preferred City Key

  • State

  • Unique Key (VA)

The FileMan Data Dictionary Utility also shows that the PostalCode file includes two pointers:

  • A pointer to the County Code file

  • A pointer to the State file

If we map this file, five classes are created. This includes a class to represent PostalCode, as well as classes to which this class refers. In Studio, we would see the following, if we had specified TEST as the package name:

generated description: convert afileman package

The class definition for TEST.POSTALCODE is too long to show, but the details are summarized here:

  • The DATECREATED class parameter is set equal to the time when the class was created or updated.

  • The FILEMANFILENAME parameter is set equal to "POSTAL CODE" and the FILEMANFILENUMBER parameter is set equal to 5.12. These two parameters indicate the FileMan file from which this class was mapped.

  • The class includes the following properties:

    • CITY

    • CITYABBREVIATION

    • CITYKEY

    • COUNTY

    • IEN

    • INACTIVEDATE

    • MAILCODE

    • PREFERREDCITYKEY

    • STATE

    • UNIQUEKEYVA

    The definitions of these properties are derived from the definitions of the corresponding fields. Also note that the FileMan Internal Entry Number is represented explicitly as a property.

    Descriptive text is carried over and is used as comments. For example:

    /// FileMan Field Label: 'STATE'  FileMan Field Number: '3'
    /// This field contains a pointer to the State File to represent the state 
    /// associated with this Postal Code.
    Property STATE As TEST.STATE [ SqlColumnNumber = 6, SqlFieldName = STATE ];
    

    Several of these properties (like this one) are references to the other generated classes. This representation addresses the cross-references defined in the PostalCode file.

  • This utility creates foreign key constraints for each pointer field created. The foreign key constraint simply references the ID of the referenced table.

    In this example, the class includes the following foreign keys to represent the pointer references in the PostalCode file:

    • FKeyCOUNTY(COUNTY), which references TEST.COUNTYCODE()

    • FKeySTATE(STATE), which references TEST.STATE()

    Also see the section “Mapping of Variable Pointer Fields,” later in this section.

  • The class includes one index:

    Index IDKeyIndex On IEN
    
  • Finally, the class includes three triggers that act when filing is performed through the FileMan filer:

    • BeforeDeleteFiling

    • BeforeInsertFiling

    • BeforeUpdateFiling

Mapping of Variable Pointer Fields

Each variable pointer field in the file that is mapped to a Caché class defines a property in the class that is marked with the SqlComputed keyword. For each file to which this variable pointer field refers, an additional property is created in the class, and this property is marked with the SqlComputed and Calculated keywords. If VariablePointerFieldName is the name of the variable pointer field, and PointerFileName is the name of the file to which it points, the added property is VariablePointerFieldNamePointerFileName; the SQL field name for this property is VariablePointerFieldName_PointerFileName.

For example, suppose the file ABC includes a variable pointer field called VP. The VP field can point to the Red, White, or Blue files. This creates the following properties in the class definition:

Property SqlFieldName Details
VP   SQL computed upon INSERT and UPDATE. Stored in the map definition. Contains the internal value for the variable pointer field. Usually something like "41;DIC(40.7,", which means it points to row 41 in the 40.7 file.
VPRed VP_Red A computed field that is null unless the VP field for this row points to the Red file. To update the value of VP via SQL INSERT or UPDATE to point to a row in the Red table/file, set the value of VP_Red to the ID of that row.
VPWhite VP_White A computed field that is null unless the VP field for this row points to the White file. To update the value of VP via SQL INSERT or UPDATE to point to a row in the White table/file, set the value of VP_White to the ID of that row.
VPBlue VP_Blue A computed field that is null that is NULL unless the VP field for this row points to the Blue file. To update the value of VP via SQL INSERT or UPDATE to point to a row in the Blue table/file, set the value of VP_Blue to the ID of that row.

In all cases, the VP field is computed and stored automatically.

In addition to defining the three reference fields VP_Red, VP_White, and VP_Blue, the utility also creates three foreign key constraints in the ABC class for these references. This is done to ensure referential integrity is maintained between the files.

Mapping of New-Style Cross-References

This utility converts new-style cross-references to index maps if the cross-reference is defined by simple set/kill logic. This allows the Caché query optimizer to choose a new-style cross-reference index (if one exists) and increase query performance in some cases.

Mapping of Cross-References That Use DUZ(9)

As of 2017.1, FM2Class maps a cross-reference (original or new style) that was previously not mapped because the cross-reference subscripts included a reference to the variable DUZ(9) or the subscript had the form +$G(varname), where varname represents any variable reference.

If you have such cross-reference definitions, make sure that the DUZ(9) variable, or possibly any variable referenced by +$G(varname) is defined in any process running SQL queries against tables with indices mapped from these cross-references. To set DUZ(9) for a process connecting via xDBC, use $SYSTEM.SQL.SetServerInitCode().

Advanced Queries

You can use the classes %FileMan.FileOpens in a new tab and %FileMan.FieldOpens in a new tab to query the FileMan data dictionary.

Also, you can use the classes %FileMan.MappedFileOpens in a new tab and %FileMan.MappedFieldOpens in a new tab to view metadata regarding the mapping between FileMan and the class definition.

For information on the %FileMan classes, see the InterSystems Class Reference.

WebLink Developer Tags for Conversion to CSP

The tags listed in this section have been superseded by CSP tags. They are documented here to assist in migrating applications from Weblink Developer to Caché Server Pages (CSP).

For more information on each tag, please see the Weblink Developer GuideOpens in a new tab.

<WLD:A>
<WLD:A>...</WLD:A>

This rule implements the action= mechanism of WLD.

WLD:ACTIONSCRIPT
<WLD:ACTIONSCRIPT>...</WLD:ACTIONSCRIPT>

The <CSP:METHOD> tag is superseded by the <SCRIPT LANGUAGE=CACHE METHOD> tag.

Attribute Description Value
MethodName The name of the generated method. Must be a valid method name. methodName:STRING
ReturnType The return type of the method. dataType:STRING
Arguments A list of arguments for the method. spec:STRING
<WLD:DHTMLGRID>
<WLD:DHTMLGRID>...</WLD:DHTMLGRID>

This rule implements the <WLD:DHTMLGRID> tag.

Attribute Description Value
Name Name of the grid. A string.
Cols Maximum number of columns. An integer.
Rows Maximum number of rows. An integer.
<WLD:END>
<WLD:END>

Required. This tag should be put at the very end of any page that uses the WLD functionality, just before the </BODY> tag.

<WLD:ERROR>
<WLD:ERROR>

The <WLD:ERROR> tag displays the Error variable as an alert, as per Developer.

<WLD:FOCUS>
<WLD:FOCUS>

The <WLD:FOCUS> tag forces focus onto a field, as per WebLink Developer. Note the execution is carried out in the <WLD:END> tag.

Attribute Description Value
FIELD Field name on which to focus. A string.
FORM Form number containing field. A string.
<WLD:GRID>
<WLD:GRID>...</WLD:GRID>

This rule implements the standard <WLD:GRID> tag.

Attribute Description Value
Name Name of the grid. A string.
Cols Maximum number of columns. An integer.
Rows Maximum number of rows. An integer.
<WLD:GRIDDATA>
<WLD:GRID>...<WLD:GRIDDATA>...</WLD:GRIDATA>

The purpose of this empty rule is to instantiate the <WLD:GRIDDATA> tag into the DOM.

Attribute Description Value
Value Value to be displayed. A string.
Col Column of the cell where the value is to be displayed. An integer.
Row Row of the cell where the value is to be displayed. An integer.
<WLD:GRIDHEADING>
<WLD:GRID>...<WLD:GRIDHEADING>...</WLD:GRIDHEADING>

The purpose of this empty rule is to instantiate the <WLD:GRIDHEADING> tag into the DOM.

Attribute Description Value
Name The name for the column. A string.
Col The column where the heading is to be displayed. An integer.
<WLD:OPTIONS>
<LIST>...<WLD:OPTIONS>

The <WLD:OPTIONS> tag generates options from the LIST array.

<WLD:PostPageScript>
<WLD:PostPageScript>...</WLD:PostPageScript>

Script to run after this page.

<WLD:PrePageScript>
<WLD:PrePageScript>...</WLD:PrePageScript>

Script to run before this page.

<WLD:SHOWLV>
<WLD:SHOWLV>

The WLDSHOWLV displays all request and session object contents.

<WLD:START>
<WLD:START>

Required. This tag should be put at the start of any page that uses the WLD functionality.

<WLD:WRITETEXT>
<TEXTAREA>...<WLD:WRITETEXT>

The WLD:WRITETEXT generates text from the TEXTAREA array.

<XSQL:QUERY>
<XSQL:QUERY>...</XSQL:QUERY>

Oracle XSQL tag

Attribute Description Value
CONNECTION Connection identifier. A string.
MAX-ROWS Specifies the maximum number of rows to return (not including any rows skipped by skip-rows). A string.
ROW-ELEMENT Specifies the XML tag for each row, the default is ROW. A string.
ROWSET-ELEMENT Specifies the XML tag for the row set, the default is ROWSET. A string.
SKIP-ROWS Specifies the number of rows to skip before returning data. A string.
TAG-CASE Controls the case of the XML tags, 'upper' means uppercase and 'lower' specifies lowercase. The default is to use the case of the column names. A string.
XMLNS:XSQL Must be URN:ORACLE-XSQL for CSP support of Oracle A string.
<INPUT TYPE=WLDCHECKBOX>
<INPUT TYPE=WLDCHECKBOX>

This rule implements the mechanisms for emulating WLD's CHECKBOX button interface.

<INPUT SRC TYPE=WLDIMAGE>
<INPUT SRC TYPE=WLDIMAGE>

This rule implements the mechanisms for supporting WLD's NEXTPAGE= and ACTION= within a <input type=image> tag.

Attribute Description Value
Action Function or expression to be executed on submit. Function or expression.
Name Name of image. String.
NextPage Specifies the page to display next. URI.
OnClick A pointer button was clicked. JavaScript code.
<INPUT TYPE=WLDRADIO>
<INPUT TYPE=WLDRADIO>

This rule implements the mechanisms for emulating WLD's RADIO button interface.

Attribute Description Value
Name Name of radio button. String.
Onclick A pointer button was clicked. JavaScript code.
Value Value of radio button. String.
<INPUT TYPE=WLDSUBMIT>
<INPUT TYPE=WLDSUBMIT>

This rule implements the mechanisms for supporting WLD's NEXTPAGE= and ACTION= within a <input type=submit> tag.

Attribute Description Value
Action Function or expression to be executed on submit. Function or expression.
Name Name of form. String.
NextPage Specifies the page to display next. URI.
Onclick A pointer button was clicked. JavaScript code.
FeedbackOpens in a new tab