Setting Domain Parameters

Domain parameters govern the behavior of a wide variety of InterSystems NLP operations. The specific parameters are described where applicable. For a full list of available domain parameters, refer to the Appendix “Domain Parameters”.

Note:

In the examples that follow, domain parameters are referenced by their macro equivalent (for example, $$$IKPFULLMATCHONLY), not their parameter name (For example, FullMatchOnly). The recommended programming practice is to use these %IKPublic macros rather than the parameter names.

All domain parameters take a default value. Commonly, InterSystems NLP will give optimal results without specifically setting any domain parameters. InterSystems NLP determines the value for each parameter as follows:

If you have specified a parameter value for the current domain, that value is used. Note that some parameters can only be set before loading data into a domain, while others can be set at any time. You can use the IsEmpty()Opens in a new tab method to determine if any data has been loaded into the current domain.
If you have specified a system-wide parameter value, that value is used as a default for all domains, except for a domain where a domain-specific value has been set.
If you have not specified a value for a parameter at either the domain level or the system level, InterSystems NLP uses its default value for that parameter.

Setting Parameters for the Current Domain

Once you have created a domain, you can set domain parameters for this specific domain using the SetParameter()Opens in a new tab instance method. SetParameter() returns a status indicating whether the parameter specified is valid and was set. GetParameter()Opens in a new tab returns the parameter value and the level at which the parameter was set (DEFAULT, DOMAIN, or SYSTEM). Note that GetParameter() does not check the validity of a parameter name; it returns DEFAULT for any parameter name it cannot identify as being set at the domain or system level.

The following example gets the default for the SortField domain parameter, sets this parameter for the current domain, then gets the value you set and the level at which it was set (DOMAIN):

#include %IKPublic
DomainCreate
  SET domn="paramdomain"
     SET domo=##class(%iKnow.Domain).%New(domn)
     WRITE "Created the ",domn," domain",!
     DO domo.%Save()
DomainParameters
  SET sfval=domo.GetParameter($$$IKPSORTFIELD,.sf)
     WRITE "SortField before SET=",sfval," ",sf,!
  IF sfval=0 {WRITE "changing SortByFrequency to SortBySpread",!
           SET stat=domo.SetParameter($$$IKPSORTFIELD,1) 
           IF stat=0 {WRITE "SetParameter failed"  QUIT} }
  WRITE "SortField after SET=",domo.GetParameter($$$IKPSORTFIELD,.str)," ",str,!!
CleanupForNextTime
  SET stat=##class(%iKnow.Domain).%DeleteId(domo.Id)
  IF stat {WRITE "Deleted the ",domn," domain" }
  ELSE { WRITE "Domain delete error:",stat }

Setting Parameters System-wide

You can set domain parameters for all domains system-wide using the SetSystemParameter()Opens in a new tab method. A parameter set using this method immediately becomes the default parameter value for all existing and subsequently created domains in all namespaces. This system-wide default is overridden for an individual domain using the SetParameter()Opens in a new tab instance method.

Note:

The SortField and Jobs domain parameters are exceptions. Setting these parameters at the system level has no effect on the domain settings.

You can determine if a domain parameter has been established as the system default using the GetSystemParameter()Opens in a new tab method. The initial value for a system-wide parameter is always the null string (no default).

If you wish to remove a system-wide default setting for a domain parameter, use the UnsetSystemParameter()Opens in a new tab method. Once a system-wide parameter setting has been established, you must unset it before you can set it to a new value. UnsetSystemParameter() returns a status of 1 (success) even when there was no parameter default value to unset.

The following example establishes a FullMatchOnly system-wide parameter value. If no system-wide default has been established, the program sets this system-wide parameter. If a system-wide default has been established, the program unsets this system-wide parameter, then sets it.

#include %IKPublic
SystemwideParameterSet
  /* Initial set */
  SET stat=##class(%iKnow.Domain).SetSystemParameter($$$IKPFULLMATCHONLY,1)
  IF stat=1 { 
    WRITE "FullMatchOnly set system-wide to: "
    WRITE ##class(%iKnow.Domain).GetSystemParameter($$$IKPFULLMATCHONLY),!
    QUIT }
  ELSE {
  /* Unset and Reset */
    SET stat=##class(%iKnow.Domain).UnsetSystemParameter($$$IKPFULLMATCHONLY)
    IF stat=1 {
      SET stat=##class(%iKnow.Domain).SetSystemParameter($$$IKPFULLMATCHONLY,1)
      IF stat=1 {
        WRITE "FullMatchOnly was unset system-wide",!,"then set to: "
        WRITE ##class(%iKnow.Domain).GetSystemParameter($$$IKPFULLMATCHONLY),!!
        GOTO CleanUpForNextTime }
      ELSE {WRITE "System Parameter set error",stat,!}
    }
    ELSE {WRITE "System Parameter set error",stat,!}
  }
CleanUpForNextTime
  SET stat=##class(%iKnow.Domain).UnsetSystemParameter($$$IKPFULLMATCHONLY)
  IF stat '=1 {WRITE "   Unset error status:",stat}

The following example shows that setting a system-wide parameter value immediately sets the parameter value for all domains. After setting a system-wide parameter value, you can override this value for individual domains:

#include %IKPublic
SystemwideParameterUnset
  SET stat=##class(%iKnow.Domain).UnsetSystemParameter($$$IKPFULLMATCHONLY)
  WRITE "System-wide setting FullMatchOnly=",##class(%iKnow.Domain).GetSystemParameter($$$IKPFULLMATCHONLY),!!
Domain1Create
  SET domn1="mysysdomain1"
     SET domo1=##class(%iKnow.Domain).%New(domn1)
     DO domo1.%Save()
     SET dom1Id=domo1.Id
     WRITE "Created the ",domn1," domain ",dom1Id,!
     WRITE "FullMatchOnly=",domo1.GetParameter($$$IKPFULLMATCHONLY,.str)," ",str,!!
SystemwideParameterSet
  SET stat=##class(%iKnow.Domain).SetSystemParameter($$$IKPFULLMATCHONLY,1)
       IF stat=0 {WRITE "SetSystemParameter failed"  QUIT}
  WRITE "Set system-wide FullMatchOnly=",##class(%iKnow.Domain).GetSystemParameter($$$IKPFULLMATCHONLY),!!
Domain2Create
  SET domn2="mysysdomain2"
     SET domo2=##class(%iKnow.Domain).%New(domn2)
     DO domo2.%Save()
     SET dom2Id=domo2.Id
     WRITE "Created the ",domn2," domain ",dom2Id,!
     WRITE "Domain setting FullMatchOnly=",domo2.GetParameter($$$IKPFULLMATCHONLY,.str)," ",str,!!
DomainParameters
  WRITE "New domain ",dom2Id," FullMatchOnly=",domo2.GetParameter($$$IKPFULLMATCHONLY,.str)," ",str,!
  WRITE "Existing domain ",dom1Id," FullMatchOnly=",domo1.GetParameter($$$IKPFULLMATCHONLY,.str)," ",str,!!
OverrideForOneDomain
  SET stat=domo1.SetParameter($$$IKPFULLMATCHONLY,0)
      IF stat=0 {WRITE "SetParameter failed"  QUIT}
  WRITE "Domain override FullMatchOnly=",domo1.GetParameter($$$IKPFULLMATCHONLY,.str)," ",str,!
CleanupForNextTime
  SET stat=##class(%iKnow.Domain).%DeleteId(dom1Id)
  SET stat=##class(%iKnow.Domain).%DeleteId(dom2Id)
  SET stat=##class(%iKnow.Domain).UnsetSystemParameter($$$IKPFULLMATCHONLY)

Assigning to a Domain

Defining a Domain Programmatically