Caché 2017.2 Upgrade Checklist

Changes to Permissions Required for Studio Access to a Namespace

In this release, Studio must have a login role that allows database access to the default database for the namespace in order to connect to a namespace. If Studio does not have such a role, it will get an error when it attempts to connect to the namespace. In previous releases, Studio access was allowed if the login role had any SQL privilege to the default database for the namespace.

Feature Tracker Enabled by Default for New Installs

Feature Tracker is a software utility in Caché that gathers statistics on software module usage. The statistics track whether or not software modules are present and used in a given Caché instance. Feature Tracker sends this information via https to InterSystems weekly. These statistics help us plan development and support. The information gathered does not include any application data. In previous releases, Feature Tracker was disabled by default. In this release, Feature Tracker is enabled by default for new installs. If you are upgrading an existing installation, the upgrade preserves the existing state of Feature Tracker.

If you wish to disable Feature Tracker, you suspend the task that runs it. For details, see “How to Deactivate Feature Tracker” in the Caché System Administration Guide.

Parallel Dejournaling Changes the Order of Dejournaling

This release includes parallel dejournaling, which makes it possible for up to four jobs to perform the dejournaling. A database is always dejournaled by a single job, so parallel dejournaling does not impact the order in which a single database is dejournaled. But it can change the order in which one database is dejournaled relative to the dejournaling in another database. This is because databases being updated by separate dejournaling jobs are likely to be at slightly different places in the dejournaling sequence; for example, database A may contain updates made on the primary at 11:45:30 when database B is only up to the updates from 11:45:28. For details, see “Configuring Parallel Dejournaling” in the “Mirroring” chapter of the Caché High Availability Guide.

Changes to Journal Buffer Pool Size

In this release, the journal buffer pool size is configurable and the default has been increased to 64MB. In previous releases, the default was 8MB on non-Unicode systems and 16MB on Unicode systems. An increase in this buffer pool size can improve efficiency, but it also increases the amount of data that may be lost if a system crash occurs.

Class Deletions

The following classes were present in the previous version and have been removed in this release:

• %Library.RunJava

Removed Methods

The following methods were present in the previous version and have been removed in this release:

• %DeepSee.UI.Dialog.ShowQuery

  • EncryptQuery

• %DeepSee.Utils

  • %ClearUpdateBuffer

• %Library.IResultSet

  • %ToDynamicArray

  • %ToDynamicObject

  • %ToJSONValue

• %Net.Remote.Utility

  • ClearPassphrase

  • GetPassphrase

  • RecordPassphrase

• %SQL.IResultSet

  • %ToDynamicArray

  • %ToDynamicObject

  • %ToJSONValue

• %SQL.StatementMetadata

  • %ToJSONValue

• Config.Shadows

  • SourceDatabasesClose

  • SourceDatabasesExecute

  • SourceDatabasesFetch

Removed Properties

The following properties were present in the previous version and have been removed in this release:

• %DeepSee.Component.Widget.controlPanel

  • isPdfEnabled

• %DeepSee.Component.Widget.widget

  • isPdfEnabled

Removed Parameters

No parameters have been removed in this release that were present in the previous version.

Removed Indices

No indices have been removed in this release that were present in the previous version.

Modified Methods

The following methods have different signatures in this version of Caché:

• %Atelier.v1.Utils.MetaData

  • old method: Build (pDataBaseName:%String) As (none)

  • new method: Build (pDataBaseName:%String) As %Status

• %CSP.UI.Portal.Dialog.EncAddAdmin

  • old method: SaveData (What, File, Username1, Password1, Username2, Password2, Description) As %String

  • new method: SaveData (What, File, Username1, Password1, Username2, Password2, Description, KeyLen) As %String

• %CSP.UI.Portal.ViewLog

  • old method: DrawLogContent (filename) As %Status

  • new method: DrawLogContent (tmp) As %Status

• %DeepSee.AbstractKPI

  • old method: %GetKPIValue (pKPIName:%String, *pValue:%String, pKPIProperty:%String="", pSeries:%String="", &pFilters:%String, pCellContext:%String="", &pCacheKey:%String, *pPctComplete:%Integer, pParentQueryKey:%String="") As %Status

  • new method: %GetKPIValue (pKPIName:%String, *pValue:%String, pKPIProperty:%String="", pSeries:%String="", &pFilters:%String, pCellContext:%String="", &pCacheKey:%String, *pPctComplete:%Integer, pParentQueryKey:%String="", *pKPIStatus:%Status) As %Status

• %DeepSee.Component.pivotTable

  • old method: getFilterInfo (fnames, fvalues) As (none)

  • new method: getFilterInfo (fnames, fvalues, flabels) As (none)

• %DeepSee.PMML.Model.AbstractModel

  • old method: %ExecuteModelInternal (pInput:%DeepSee.PMML.ModelInput, *pOutput:%DeepSee.PMML.ModelOutput) As %Status

  • new method: %ExecuteModelInternal (&pInput:%DeepSee.PMML.ModelInput, *pOutput:%DeepSee.PMML.ModelOutput) As %Status

• %DeepSee.PMML.Model.GeneralRegression

  • old method: CalculateXBeta (pObservation:%DeepSee.PMML.ModelInput, *pXBeta, *pBestTarget:%String="", *pBestScore:%Double="", pAddZero:%String="") As %Status

  • new method: CalculateXBeta (&pObservation:%DeepSee.PMML.ModelInput, *pXBeta, *pBestTarget:%String="", *pBestScore:%Double="", pAddZero:%String="") As %Status

• %DeepSee.ResultSet

  • old method: %PrepareObject (pQuery:%DeepSee.Query.query) As %Status

  • new method: %PrepareObject (pQuery:%DeepSee.Query.query, &pVariables) As %Status

• %DeepSee.Utils

  • old method: %GetDimensionMembers (pCubeName:%String, pSpec:%String, pContext:%List, *pMembers, pMaxMembers:%Integer=100, *pMemberClass:%String, &pRelatedFilters, pCalcMode:%Integer=0, pSearchKey:%String="") As %Status

  • new method: %GetDimensionMembers (pCubeName:%String, pSpec:%String, pContext:%String="", *pMembers, pMaxMembers:%Integer=100, *pMemberClass:%String, &pRelatedFilters, pCalcMode:%Integer=0, pSearchKey:%String="") As %Status

• %Exception.SystemException

  • old method: %OnNew (pName:%String="", pCode:%String="", pLocation:%String="", pData:%String="", pInnerException:%Exception.AbstractException=$$$NULLOREF, pStack:%String="") As %Status

  • new method: %OnNew (pName:%String="", pCode:%String="", pLocation:%String="", pData:%String="", pInnerException:%Exception.AbstractException=$$$NULLOREF, pStack:%String) As %Status

• %Library.GlobalEdit

  • old method: GetGlobalSizeBySubscript (Directory:%String, StartNode:%String, EndNode:%String="", &Size:%String=0) As (none)

  • new method: GetGlobalSizeBySubscript (Directory:%String, StartingNode:%String, EndingNode:%String="", &Size:%String=0) As (none)

• %Library.Routine

  • old method: CompileAll (Flags:%String=0, IO:%String=$p, &Count:%Integer, &Errors:%Integer, MultiCompile:%Integer=1, Journal:%Integer=1, KeepSource:%Boolean=1) As %Status

  • new method: CompileAll (Flags:%String=0, IO:%String=$p, &Count:%Integer, &Errors:%Integer, MultiCompile:%Integer, Journal:%Integer, KeepSource:%Boolean=1) As %Status

  • old method: CompileSelected (Mask:%String="*.*", Flags:%String=0, IO:%String=$p, &Count:%Integer, &Errors:%Integer, MultiCompile:%Integer=1, Journal:%Integer=1, KeepSource:%Boolean=1) As %Status

  • new method: CompileSelected (Mask:%String="*.*", Flags:%String=0, IO:%String=$p, &Count:%Integer, &Errors:%Integer, MultiCompile:%Integer, Journal:%Integer, KeepSource:%Boolean=1) As %Status

• %Library.SQLCatalog

  • old method: SQLClassname (qh:%Library.SQLProcContext, table:%String) As %Library.String

  • new method: SQLClassname (qh:%Library.SQLProcContext, table:%String(MAXLEN=257)) As %Library.String

• %SYSTEM.SQL

  • old method: SetSQLStats (flag:%Library.Integer=1) As %Library.Integer

  • new method: SetSQLStats (flag:%Library.Integer=0) As %Library.Integer

• %ZEN.ComponentEx.svgImageProvider

  • old method: dumpSVGNode (e, svgDoc, src, intro, coda, NSPrefix, maxWidth) As (none)

  • new method: dumpSVGNode (e, svgDoc, src, intro, coda, NSPrefix, maxWidth, maxHeight) As (none)

  • old method: extractXSLFOSource (svg, intro, coda, maxWidth) As (none)

  • new method: extractXSLFOSource (svg, intro, coda, maxWidth, maxHeight) As (none)

• %ZEN.Template.AddInWizard.SOAPWizard

  • old method: GetSRC (filetype:%String, url:%String, sslConfig:%String="", username:%String="", password:%String="") As %String

  • new method: GetSRC (filetype:%String, url:%String, sslConfig:%String="", sslCheckServerId:%Boolean, username:%String="", password:%String="") As %String

  • old method: SaveLast (filetype, url, sslConfig="") As (none)

  • new method: SaveLast (filetype, url, sslConfig="", sslCheckServerId) As (none)

• SYS.Stats.WriteDaemon

  • old method: Sample (DaemonID:%Integer) As SYS.Stats.Resource

  • new method: Sample (DaemonID:%Integer=1) As SYS.Stats.WriteDaemon

Hard Errors in delete() are Reported with %Status Value

In previous releases, if the delete() method in the class compiler encountered a hard error, it would throw the error to the caller. In this release, these errors are handled by the delete() method, which reports the error to the caller with a %Status value.

Change Default to Display Mode in DeepSee Listing Selection

In previous releases, if a DeepSee field was not explicitly declared %EXTERNAL(field) or %INTERNAL(field), DeepSee would display its internal value in the listing output. In this release DeepSee will use its external value. To have the internal value used, you must wrap the field in %INTERNAL().

Do not use JMS Gateway as Message Listener

This release removes the JMSGateway class from the Java Gateway. This class was intended as an example on how to use the JMS listener in Ensemble. If you have used this class to implement a JMS listener, you should replace this with the mechanism demonstrated in the EnsLib.JavaGateway.JMSTest class.

Object Gateway Load^%apiGTW Does Not Make err Variable Public

In previous releases, the call to Load^%apiGTW would deliberately make the variable err public so that it could be used in the Management Portal and other InterSystems APIs. In this release, it does not automatically make it public but instead returns a status value. If your code depended on this previous behavior, you must explicitly define err as a public variable by calling:

Set err=$$Load^%apiGTW 

Replace SysList, SysListUtil, and CacheListRO Classes Used With ODBCx APIs

If you use the SysList, SysListUtil, and CacheListRO Classes directly with the ODBCx APIs, replace them with other classes that provide similar functionality. Although the classes have been deprecated, they have not yet been deleted. If you use these classes but not use them with any other ADO APIs, you can defer replacing them until it is convenient. But if you use them with the ODBCx APIs, you must replace them before using with this release.

%RunJava Utility Class Removed

In this release, the %RunJava utility class has been removed. If you call methods in this class, you must replace them with calls to the utility methods in %Net.Remote.Service.

Limit Number of Subscripts for Indirection

In this release, applications are limited to 254 subscripts for indirection. It is unlikely that there is any existing code doing indirection with more than 254 subscripts. Such code would create nodes that are not easily accessible.

Changes in API to Create QuickStatement

The QuickStatement class syntax has changed and the class was moved from cache-jdbc to cache-db jar. The new syntax is

QuickStatement qs = QuickStatement.createQuickStatement((CacheConnection) connection); 

If you use the previous syntax, “QuickStatement qs = (QuickStatement) rs.getObject("**QuickStatement**");”, you must update your code to the new syntax.

Changes in %Date LogicalToOdbc and LogicalToDisplay

In previous releases if a timestamp value was passed through %Date LogicalToOdbc or LogicalToDisplay, it was not altered. As part of a fix to support dates prior to December 31, 1840, this behavior has changed. In this release if a timestamp value was passed through %Date LogicalToOdbc or LogicalToDisplay, it removes the time portion of the value and returns only the date portion. If your application logic depends on the previous behavior, you may need to modify your code. For example, if you query data in Display or Odbc mode from a table linked to Oracle and use a function like CAST(field AS DATE) or TO_DATE(...), Oracle returns a datetime value. In this release, Caché converts it to a DATE.

Enforce REFERENCES Privileges for Foreign Keys

In previous releases, it was possible to create a foreign key constraint through a DDL statement without holding the REFERENCES privilege for the referenced table. In this release, for a user to define a foreign key constraint that references table T, the user must hold the REFERENCE privilege on table T, or the REFERENCE privilege on the column(s) of table T that are being referenced by the foreign key. If an application creates foreign keys without holding REFERENCES privileges, it will encounter errors.

Change in oref Numbers Ordering

In this release, we have improved the efficiency of processing OREFs. As a consequence, the OREF number assignments, which were previously assigned in the order created are now assigned in an independent way. Consequently, if your code relies on the way in OREF numbers were assigned, you must modify the logic. The previous ordering was an implementation detail and was not a documented feature. For example, if OREF string values are used to index a Caché multidimensional array, the subscript order of the OREF string values will no longer have any relation to the order in which those OREF values were created. If an application is using OREF value order to control order of execution or order of data handling, then that application will need to be modified to use other techniques, like $INCREMENT or $SEQUENCE, to generate the desired ordering.

Similarly, this change affects the order of items in relationships (for example, the order of children within a parent). Note, however, that it is not supported to rely on the order of items in relationships.

Console Log Changes

In some cases, long console log messages that were broken into two messages in previous releases will now be written as a single message. If you have code that parses for specific messages in the console log, you should update it.

SOAP Wizard Includes Option to Generate Shorter Array Names

In previous releases, the default type name for an array item includes both the item name and type name or the key name and type name, even when the names are identical. In this release, by default, if the item name and type name are the same, only one is included in the default array type name. Similarly, if the key name and type name are identical, only one is included in the default array type name. For example, in previous releases, an XML schema (or a WSDL for a web service) might include something like the following:

<element minOccurs="0" name="PropName" type="s01:ArrayOfSimpleObjectSimpleObject" xmlns:s01="mytypes"/>

As of this release, the schema or WSDL will instead include this:

<element minOccurs="0" name="PropName" type="s01:ArrayOfSimpleObject" xmlns:s01="mytypes"/>

In some cases, you can revert to the previous default behavior:

• The AllowRedundantArrayName property of %XML.SchemaOpens in a new tab allows the old form in an XML schema. If true, the previous longer type names are generated.

• The ALLOWREDUNDANTARRAYNAME parameter of a web service class allows the old form of array name in the XML schemas in the WSDL for the web service. If this parameter is true, then the previous longer type names are generated.

• There is no way to restore the previous default of long array names, if you are generating the schema by using the XMLSchema() method of %XML.AdaptorOpens in a new tab. The schema would need to be created using the %XML.SchemaOpens in a new tab class.

Change to Invoking Web Methods Using HTTP Requests

In previous releases you could call a Caché SOAP web service directly without making an HTTP SOAP request. This shortcut avoids using a SOAP client but it bypasses the security available using HTTP SOAP requests. This shortcut is used by the catalog and test pages that Caché generates for a SOAP web service class. InterSystems recommends that you not use this shortcut but always use a SOAP web client to generate an HTTP SOAP request to call Caché SOAP web services. If you have code that uses the %SOAP.WebServiceInvoke class in a URL to invoke a SOAP web service, InterSystems recommends that you replace this with an HTTP SOAP request generated by a SOAP client.

Although it is not recommended, you can continue to use this shortcut mechanism, but you must explicitly enable this access. To use the %SOAP.WebServiceInvoke class and the soap_method query parameter, you must:

• Enable %SOAP.WebServiceInfo and WebServiceInvoke with commands such as:

  set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInfo")=1
  set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInvoke")=1
  

  

  Where webapplicationname is the web application name with a trailing slash, for example, "/csp/mynamespace/".

• Ensure that the user accessing the CSP page has USE permission for the %Development resource.

XSLT2 Transformation Returns Error Status for Fatal Errors

In previous releases, when an XSLT2 transformation encountered a fatal error, it returned $$$OK. In this release, it correctly returns an error status. If your code relies on the default error handling, you may have to modify it to handle this change. If you have overridden the default with custom error handling, the custom error handling will continue to work as it did in previous releases.

Change in XML Output for Property with Element Qualified

In previous releases, if a class with ELEMENTQUALFIED=1 had a property which is a literal datatype with ELEMENTQUALIFIED, the property was not output with a namespace specified. This change corrects this, and, in Caché 2017.2 and later releases, the property is output by XMLExport or %XML.Writer with a namespace qualification.

For example, in previous releases, the XML output for a property would be:

<MyProp xmlns="">0

In Caché 2017.2, the XML output for this property is:

<s01:MyProp xmlns="" xmlns:s01="http://my.namespace.com/test">