Upgrade Checklist for Caché 2018.1

Operational Changes

Platform-Specific Items

This section holds items of interest to users of specific platforms.

Class Changes

Debugging Changes

Terminal Changes

The cterm application now accepts terminal input directly as Unicode instead of ANSI characters. This change should not impact terminal usage and behavior, but it is possible that there may be differences in some locales. This change allows Caché to support additional languages.

DeepSee Changes

Language Binding Changes

Security Changes

SQL Changes

System Changes

SMTP Checks Server Identities

The SSLCheckServerIdentity property in %Net.SMTP now defaults to being on. This means that, when connecting to an SSL/TLS secured web server, %Net.SMTP will check that the certificate server name matches the DNS name used to connect to the server and fail if they don't match. This is the behavior specified in RFC 2818 section 3.1. This change is unlikely to cause compatibility issues, but it is possible that when using %Net.SMTP to send messages you might have issues connecting to an SSL/TLS enabled server. If this happens, and you understand the security trade-offs, you can set SSLCheckServerIdentity to 0 to restore the previous behavior.

%Zen.Dialog Cannot be Run by Default

%ZEN.Dialog classes can no longer be run on web applications that do not explicitly allow them. This means that if you have web applications that rely on %ZEN.Dialog classes and that are not Analytics-enabled or Interoperability-enabled, the applications now need to explicitly enable %ZEN.Dialog classes. You can enable %ZEN.Dialog classes by entering:

Set ^SYS("Security","CSP","AllowPrefix",application,"%ZEN.Dialog.")=1

SQL — System ID and IDENTITY Datatypes 2018.1.4 Change Reverted to %Integer

In maintenance release 2018.1.4, the datatype of system-generated ID properties and IDENTITY fields were changed from %Integer to BIGINT. This change in maintenance release 2018.1.5 reverts that change and returns to the previous behavior where the type is %Integer. If your code expects these ID fields or IDENTITY columns to be of type BIGINT, you need to modify your code. This change is only an issue if you are upgrading from 2018.1.4 to 2018.1.5 or later.

CSP — Improved Handling of SameSite HTTP Option

Recent updates to browser security have changed handling of third-party cookies. These updates use the SameSite attribute to reduce the risk of cross-site request forgery (CSRF) attacks, unauthorized access to data, and other possible security issues. Chrome (starting with v.84) enforces stricter rules for SameSite behavior, and these rules can cause issues with existing websites and web applications. These issues may include login problems, the login page being displayed repeatedly, and page elements not displaying properly. In previous versions, Caché did not support modifications to the SameSite attribute; hence web applications running on these versions may have such issues.

This release solves these problems by setting the SameSite attribute for cookies and by allowing you to set change the default setting; however, you may need to modify your code to customize values setting the session cookie scope and the user cookie scope. Additionally, if you are using “SameSite=None”, you must ensure that your web application can support secure HTTPS connections.

Ensemble Adapters — QueueWaitTime Changes

In this release Ensemble changed the method it uses to calculate queue wait time and includes the amount of time the active message is waiting. In some cases this could mean that waiting for a message will exceed the queue wait time, where in previous releases the wait would not have exceeded the limit.

Zen Mojo — Classes That Use Highcharts Libraries Need to Update References

If you are using Zen Mojo classes that use Highcharts 4.0.1 or Highcharts 4.0.4 libraries, you must update your code to use Highcharts 8.0.4.

CSP Gateway Installer — How the Gateway Installer Treats an Existing CSP.ini File

In environments where a third party Web Server is running remotely, the Web Gateway installer tried to modify some settings in CSP.ini which could result in unwanted changes in terms of service accessibility. A review of the configuration after each upgrade was always recommended. In this release the Web Gateway installer will not modify an existing CSP.ini in any way. For details on configuring the web server and Web Gateway, see “Configuring the Web Server and Web Gateway.” This change first appeared in maintenance release 2018.1.4.

CSP Gateway — Gateway and Private Web Server WebSockets Changes

In the maintenance release 2018.1.4, the Web Gateway's implementation of WebSockets with Apache now uses the wakeable pollset feature of the Apache Portable Runtime (APR) library. Because of this dependency, this release of the CSP Gateway will cause problems in two scenarios.

1. On Apache 2.2, WebSockets will no longer work. Any attempt to use WebSockets with Apache 2.2 will result in immediate closure of the connection and an error message in the Event Log saying that WebSockets are not supported in the current build of the CSP Gateway. To avoid this issue, customers should upgrade to Apache 2.4. The reason for removing WebSockets support from Apache 2.2 builds of the CSP Gateway is that some releases of Apache 2.2 are linked to an old version of APR that does not support wakeable pollsets.

2. On Oracle Solaris, if Apache 2.4 was built or configured to link to APR 1.6.3 or earlier, then WebSocket messages cannot be sent or received reliably. This affects the Private Web Server as well, which, as of 2018.1.4, links to APR 1.5.2. This is due to a Solaris-specific bug in the wakeable pollset functions in APR, detailed at https://bz.apache.org/bugzilla/show_bug.cgi?format=multiple&id=61786Opens in a new tab. To avoid this issue, customers on Solaris should upgrade their builds of Apache to a version that is linked to APR 1.6.4 or higher. A quick way to check the version of APR is to view the CSP Gateway Event Log and read the header in one of the entries. For example, the following header snippet indicates APR 1.5.2:

   >>> Time: Tue Jan 28 11:25:44 2020; RT Build: 1801.1631m 
   (solaris/apapi:srv=2.4.20/apr=1.5.2/apu=1.5.4/mpm=worker)
   

   

This change first appeared in maintenance release 2018.1.4.

CSP Gateway — Change to How Web Sockets Use Licenses

There are two ways in which this change to how web sockets use licenses may impact custom code.

1. In some cases, web sockets were not counted correctly for licenses. If your application was approaching the license limit, this change could increase the number of licenses being used.

2. In order to not continue to consume a license after a CSP session times out, for SharedConnection=1 web sockets, if the CSP session times out then the web socket times out and cannot be used. In previous releases, the web socket would continue to be active.

DeepSee — Timing Changes in ResultSet

This changes the way that the %DeepSee.ResultSet operates during concurrent executions to preserve the integrity of results. Applications using the %DeepSee.ResultSet where the optimistic concurrency worked correctly before this fix may start noticing results are not ready when going to read them. If this is occurring, make sure the results are complete by checking for:

ResultSetObj.%GetStatus()=100

before attempting to read results. This change first appeared in maintenance release 2018.1.4.

DeepSee — %dsCellContext in KPI/Plugin Code Changes

This change fixed the cell context passed to a %KPI plugin's %dsCellContext environment variable. Applications that directly apply the contents of %dsCellContext to an MDX query will not see a change in behavior. But applications which parse the contents of %dsCellContext to be used in further action should verify that the custom code still handles the original MDX clauses. This change first appeared in maintenance release 2018.1.4.

Ensemble — HL7 Changes to Events for Unexpected Segment Names

In order to see information about unexpected HL7 Segment names one must now set ^Ens.Debug("TraceCat","parse") to 1 — this replaces possible event log warnings. Message validation can still be used to enforce schema segment names. This change first appeared in maintenance release 2018.1.4.

Object Library — %Net.SSH.Session.Disconnect() Method Should be Called with Error Checking

To avoid a problem the %Net.SSH.Session.Disconnect() method checks to see if the disconnection can be done successfully. If it cannot, it returns the “Session in use” error and does not perform the disconnection. Consequently, if you call Disconnect(), you should handle this possible error in your code.

SQL — IFNULL Function May Require Explicit CAST

A problem has been corrected with the SQL IFNULL function where an argument to IFNULL was not properly converted from Display or Odbc format to logical format if the argument was a host variable. This does create a slight compatibility issue with a statement like:

Select IFNULL(DOB,'null', DOB) from Sample.Person

Where DOB is type DATE.

For this statement, IFNULL assumes all input arguments are of type DATE, but obviously 'null' is a string. Caché does not support an implicit conversion from string to null for this case.

To fix this problem, you should use CAST to convert 'null' to DATE:

Select IFNULL(DOB,cast('null' as DATE), DOB) from Sample.Person

This change first appeared in maintenance release 2018.1.4.

SQL — System ID Datatypes are Now BIGINT

The datatype of system-generated ID properties and fields is now BIGINT, where in previous releases it had been of type INTEGER. This is also true for corresponding reference fields. If your code expects these ID fields to be of type INTEGER, you need to modify your code. This change first appeared in maintenance release 2018.1.4. Note that this change is reverted in 2018.1.5.

Security — LDAP Changes

The fields which govern which LDAP server you connect to for authentication have been moved from the Security.System class to the Security.LDAPConfigs class. If you use the Security.System set of APIs to modify your LDAP settings, you will need to update your code to use the new Security.LDAPConfigs class which contain the same LDAP properties. The set of LDAP properties in the Security.System class have been deprecated, and will no longer affect the operation of the system, and will eventually be removed. If you upgrade an existing system which uses LDAP Authentication, then the properties are automatically moved to the new Security.LDAPConfigs class, and the system will continue to run normally after the upgrade without needing to change anything.

If you are currently using "Allow Operating System LDAP Authorization" for terminal sessions, and turn on "Allow multiple security domains", then you will no longer be automatically authenticated against the LDAP server, since you no longer know which server your operating system process was authenticated against. You will now be prompted for a username and password. The one exception to this is if the environment variable ISC_LDAP_CONFIG is defined to point to an existing LDAP configuration, then that LDAP server will be used for your authorization.

Since the domains database is no longer used, it is removed from the security database. All the methods in Security.Domains have been deprecated, and when called perform no action.

Security — Login Rule Change Audit Event Removed

The %System/%Security/LoginRuleChange audit event has been removed. If you had code which modified this specific event using Security.Events(), it will not longer have any affect on the system, and the Modify() method will return an error. It is unlikely that user code accessed this event.

System — Maximum Frame Depth Reduced on UNIX 32-bit systems

To fix a process termination when a <FRAMESTACK> error was encountered when handling a previous <FRAMESTACK> error, the change reduced the maximum frame depth for Unicode systems. This change is unlikely to cause problems unless your code created conditions that were very close to the previously allowed frame depth. This change only impacts UNIX 32-bit systems.

Language Bindings.ActiveX — Action Required to Fix Lock Problem

If your system has run into the ActiveX Lock problem described in Fix ActiveX locking issueOpens in a new tab in the Caché & Ensemble Maintenance Release Changes and if your system has these locks that have not been freed, you should execute the following kill command in all effected namespaces after installing this change:

kill ^ISC.oddMETA

Installation — Upgrading a Windows System Will Not Re-create USER Namespace if it was Deleted

In previous releases, if you upgraded a Windows system and the USER namespace had been deleted from the instance, the installation would create a new USER namespace. With this change, if the USER namespace has been deleted from the instance, the upgrade installation will not create a new USER namespace.

System — Support Longer Strings in Legacy %ZEN.Auxiliary.jsonProvider

In previous releases, the %ZEN.Auxiliary.jsonProvider would produce a <MAXSTRING> error if the JSON properties were larger than 32K or 3.8M (with long strings enabled). This change supports these longer strings. However, to fix this issue, the returned %ZEN.proxyobject may contain streams. Consequently, you should check the return object for streams before accessing it.

Ensemble Production — Custom Subclasses of EnsLib.HTTP.GenericMessage May Require Changes

EnsLib.HTTP.GenericMessage now explicitly defined XMLNAME parameter as well as XMLTYPE. Any custom sub classes of EnsLib.HTTP.GenericMessage need to account for XMLNAME paramter now being inherited and override as required.

Ensemble Production — New X12 Validation May Impact Previously Ignored Flags

The behavior for existing X12 validation flags in routers is unchanged. However, in the unlikely event that you have specified extra validation flags that were not previously valid, the behavior may change. If you specified a nonexistent validation flag, it would have been ignored, but if the flag now matches a new validation flag, the specified validation will be performed.

For a list of the new validation flags, see “Validation” in Routing X12 Documents in Productions.

Ensemble Production — Changes in Message Bank Storage for HTTP Messages

HTTP, REST and SOAP Generic Messages are now banked as XML Export projection and not as the unique case for Ens.StreamContainer. It is possible to resend Generic messages and Ens.StreamContainer messages from the Message Bank.

Ensemble Production — Ens.Utl.XML.SecuritySignature Changes

Ens.Util.XML.SecuritySignature no longer extends %XML.Security.Signature. Any use of Ens.Util.XML.SecuritySignature other than ValidateSAML() will need to be changed to use %XML.Security.Signature.

Ensemble Production — Developers Using Studio Need Additional Privilege

Developers using Studio may need to be granted execute privilege on stored procedures: Ens_Config.Production_Extent.

Ensemble Production — SOAP Outbound Adapter Changes

The EnsLib SOAP Outbound Adapter clears the HTTPHeaders of the %Client property after each Invoke, InvokeMethod or InvokeWithSOAPBody call. If not using SOAP Wizard generated classes that lead to %Client property being re-initialized before each SOAP call then it may be necessary to set again any http headers that were expected to be maintained in custom code.