M Language Differences
Only language features that differ between MSM and Native Caché mode are listed.
While MSM will allow varied abbreviations for many of its language features, Caché will only allow the abbreviations stated in the Caché ObjectScript Reference.
Commands
Caché equivalent: CLOSE
Purpose: Closes a device.
Notes: Caché supports MSM-like numeric devices after you define a numeric alias for that device—see OPEN.
Caché equivalent: DO
Purpose: Executes a routine or block of code.
Notes: Square brackets ( [] ) not supported from routines — use vertical bars instead ( || ). And, MSM’s UCI and VOL values must be changed to namespace and system values, respectively. Or, eliminate routine extended references and use namespace routine mapping (Preferred).
Caché equivalent: $ZCHILD, JOB
Purpose: Spawns a new background process.
Notes: In Caché, use $ZCHILD to return the PID of the jobbed process rather than $ZB as done in MSM.
Using the JOB command to specify a new partition size [JOB:(:PartitionSize)] is only supported in Caché for UNIX®—For Windows, use $ZF(-2) to spawn an external Caché job with a new partition. For example, this code runs ^Test in the %SYS namespace with a 1024 KB partition size on Windows NT (assumes default installation directory):
Set x=$zf(-2, "c:\cachesys\bin\cache -s..\mgr -b 1024 -U %SYS ^^Test")
Note these differences between MSM jobs and Caché jobs:
-
When jobbing to Caché (or any DSM-DDP system), you cannot pass parameters. Parameter passing across the network is an MSMV3 circuit option only. You need to set passed values into a global on one of the systems and fetch these values in the JOBed process.
-
When jobbing from MSM to Caché, you can only start jobs with a default database. That is, you cannot specify a namespace in the JOB command in MSM to start the job on cache in. Once started, the job on the Caché system will need to specifically change (ZNAMESPACE) to a namespace to use mapping.
Caché equivalent: NEW
Purpose: Stacks one or more local variables.
Notes: Caché does not allow $TEST or $ZREFERENCE as arguments to the NEW command.
Caché equivalent: OPEN
Purpose: Opens a device.
Notes: Devices in Caché correspond to device name at the OS level (such as /dev/tty3a), unless a numeric alias is specified in the System Configuration utilities for the device. You must use a numeric alias to emulate MSM’s device structure.
Caché equivalent: Not implemented.
Purpose: Causes current transaction to be restarted.
Caché equivalent: TSTART
Purpose: Marks the beginning of a transaction.
Notes: Caché does not support restart variables or transaction parameters.
Caché equivalent: USE
Purpose: Uses a device, and sets $IO to this current device.
Notes: Caché supports MSM-like numeric devices after you define a numeric alias for that device—see OPEN.
Caché equivalent: VIEW
Purpose: Reads and writes blocks to disk, and writes locations in memory.
Notes: VIEW commands must respect Caché disk and memory structures—see documentation for more details.
Caché equivalent: WRITE
Purpose: Sends output to current device.
Notes: Mnemonic spaces may need to be rewritten for Caché.
Caché equivalent: $ZF
Purpose: Calls an external procedure.
Caché equivalent: Not implemented.
Purpose: Flushes all disk blocks out of the internal disk buffer cache.
Caché equivalent: argumentless GOTO
Purpose: Resumes execution of a program after a BREAK command.
Caché equivalent: the %SYSTEM.ProcessOpens in a new tab FixedDate()Opens in a new tab method.
Purpose: Sets date and time for current process.
Notes: Caché’s FixedDate() method only allows a new date value, not time.
Caché equivalent: No direct equivalent.
Purpose: Traces the sequence of program execution within a routine and from routine to routine.
Notes: In Caché, try:
For i=0:1:$stack(-1) Do
. Write !,"Context level:",i,?25,"Context type:",$stack(i)
. Write !,?5,"Current place:",$stack(i,"place")
. Write !,?5,"Current source:",$stack(i,"mcode")
Quit
Caché equivalent: Not implemented.
Purpose: Similar to NEW command, but variable is persistent after subroutine explicitly or implicitly quits.
Caché equivalent: SET
Purpose: Assigns an object reference to a variable.
Notes: ObjectScript uses the native SET command, such as:
Set var=Car.Make
Caché equivalent: the %Library.DeviceOpens in a new tab Broadcast()Opens in a new tab method or the %SYSTEM.ProcessOpens in a new tab Broadcast()Opens in a new tab method.
Purpose: Allows write access to any device, even if in use — broadcasting
Operators
Caché equivalent: $ZHEX
Purpose: Performs numeric conversions from hexadecimal to decimal.
Structured System Variables
Caché equivalent: Not implemented.
Purpose: Provides information on the existence, operational characteristics, and availability of a device.
Functions
Caché equivalent: $ORDER
Purpose: Returns next subscript at the same level of a given variable. Also loops through a list of local variables set in a partition.
Notes: This looping functionality differs on the two platforms. For example, assume we have these variables set:
%=1, %USER="mikel", var=123.
MSM code
Write $Order() ; this returns "%"
Write $Order(%) ; this returns "%USER"
Write $Order(%USER) ; this returns "var"
Caché code
Write $Order(@("")) ; this returns "%"
Write $Order(%) ; this returns "%USER"
Write $Order(%USER) ; this returns "var"
Caché equivalent: $VIEW
Purpose: Returns contents of memory locations.
Caché equivalent: $ASCII
Purpose: Returns the Unicode character code of a specified character.
Caché equivalent: Not available.
Purpose: Returns the starting block number for a routine or global, allocates a disk block, or de-allocates a disk block.
Caché equivalent: $ZBIT<name>
Purpose: A collection of functions that are used to perform logical operations on bitstrings.
Caché equivalent: $ZF
Purpose: Calls an external procedure and returns a value.
Notes: Caché’s $ZF expects function names in double-quotes [$ZF("MyFunction")], while MSM’s $ZCALL does not [$ZCALL(MyFunction)].
Caché equivalent: Not available.
Purpose: Returns a string of characters, given a list of Unicode character codes.
Caché equivalent: $ZCRC
Purpose: Returns a computed checksum or cyclic redundancy check.
Caché equivalent: SET
Purpose: Returns an object reference to a newly instantiated object.
Notes: ObjectScript uses the native SET command, such as:
Set var=##class(Car).%New()
Caché equivalent: $ZDATE
Purpose: Returns an external date value, given a $HOROLOG date.
Notes: Caché will return a <VALUE OUT OF RANGE> error for any $H value below 0 and above 2980013. While MSM will not generate an M error for dates out of range, invalid dates are reported for $H values below 0 and after 94598.
Caché equivalent: No direct equivalent.
Purpose: Returns the actual device name, given the internal device ID.
Notes: For a terminal device, the special variable $ZIO contains the TELNET port number and host IP address, or LAT server name and port name. For more information on using terminal devices, see the Caché I/O Device Guide chapters on I/O Devices and Commands and Terminal I/O.
Caché equivalent: SET
Purpose: Retrieves database object, and returns object reference to the instantiated object.
Notes: ObjectScript uses the native SET command, such as:
Set var=##class(Car).%Open(OREF)
Caché equivalent: $ZDATE, $ZTIME, $ZDATETIME
Purpose: Returns an external date or time value, given a $HOROLOG date.
Notes: Use $ZDATE to convert dates and $ZTIME to convert times, or $ZDATETIME to convert both.
Caché equivalent: Not available.
Purpose: Identifies whether an expression refers to an object, and whether two expressions refer to the same object.
Caché equivalent: Not available.
Purpose: Returns the number of positions of a string that can fit in a field, on an output device.
Caché equivalent: No direct equivalent.
Purpose: Returns the UCI internal number or external name.
Notes: In Caché, use $ZNSPACE or $NAMESPACE to return the current namespace.
Caché equivalent: Not available.
Purpose: Returns a string of errors, if any exist, in the logical structure of the database.
Caché equivalent: Not available.
Purpose: Returns the width that a string occupies when it is displayed on an output device.
Preprocessor Directives
Caché equivalent: No direct equivalent.
Purpose: Turns on the insertion of pre-expansion lines of code that contain macros into the generated code as comments.
Notes: In Caché, you can use #show to enable the inclusion of comments from .INC code in the generated .INT code.
Caché equivalent: Not available.
Purpose: Defines a macro to be used for referencing an array.
Caché equivalent: Not available.
Purpose: Defines a unique local label or variable, and is guaranteed to be unique in a routine as long as the prefix is not used directly.
Caché equivalent: #include
Purpose: Includes source code in a given routine.
Notes: In Caché, #include can only be used to reference .INC code.
Caché equivalent: Not available.
Purpose: Specifies path to library files.
Caché equivalent: Not available.
Purpose: Creates a macro library.
Caché equivalent: No direct equivalent.
Purpose: Stops the inclusion of unprocessed source code lines as comments.
Notes: In Caché, you can use #noshow to exclude comments from .INC code from the generated .INT code.
Caché equivalent: Not available.
Purpose: Prevents generation of an M routine.
Caché equivalent: Not available.
Purpose: Defines the prefix used to identify a macro reference.
Caché equivalent: Not available.
Purpose: Specifies the name of a routine to be generated.
Caché equivalent: #undef
Purpose: Removes a macro definition.
Notes: In Caché, you must change all #undefine statements to #undef.
Caché equivalent: Not available.
Purpose: Updates a macro library.
Caché equivalent: Not available.
Purpose: Executes M code during preprocessing.
Special Variables
Caché equivalent: $DEVICE
Purpose: Indicates whether last I/O operation was successful.
Notes: Caché always returns the NULL string indicating a successful I/O operation You can use the SET command to place a value in $DEVICE. By convention, this value should describe the outcome of an I/O operation as a string in the form: "standard_error,user_error,explanatory_text".
Caché equivalent: $ECODE
Purpose: Returns a list of errors encountered by the application.
Notes: While MSM’s and Caché’s $ECODE are the same conceptually, Caché will use Caché-specific error strings such as: ,ZSYNTAX, ZNOROUTINE, ZDISKHARD,
Caché equivalent: $IO
Purpose: Contains the currently active device.
Notes: While MSM will represent $IO as an internal device number, Caché will use an actual device name, with a device type header. For example, a printer in Caché might look something like this:
|PRN|\\salesserver\printer1
For MSM-like devices, you must create a numeric alias for your device via the System Configuration Wizard.
Caché equivalent: $JOB
Purpose: Contains the job number for the current process.
Notes: Caché’s $JOB values correspond to the process’ PID number at the OS level, while MSM’s $JOB values are MSM-specific numbers.
Caché equivalent: $PRINCIPAL
Purpose: Contains a job’s principal device.
Notes: While MSM will represent $PRINCIPAL as an internal device number, Caché will use an actual device name, with a device type header. For example, a user login in Caché might look something like this:
|TNT|192.9.204.64:1097|316
In this case, |TNT| specifies a TELNET device, 192.9.204.64 represents the TERMINAL server IP, 1097 the virtual port number, and 316 the OS level process ID.
Caché equivalent: No direct equivalent.
Purpose: MSM uses $SYSTEM to return three pieces of information: an M User Group # (43), the Serial # from the MSM license, and a unique # for the current instance of M.
Notes: Caché license information can be accessed through methods of the %SYSTEM.LicenseOpens in a new tab class:
-
KeyMachineID()Opens in a new tab returns the contents of the MachineID field in the active key.
-
KeyOrderNumber()Opens in a new tab returns the active key OrderNumber field.
-
KeyAuthorizationKey()Opens in a new tab returns the AuthorizationKey field in the active key.
-
KeyCustomerName()Opens in a new tab returns the active key CustomerName field.
These methods are implemented in the special $SYSTEM object and can be accessed with the $SYSTEM.License.Method() syntax.
Caché equivalent: Not implemented.
Purpose: Indicates the number of transaction restarts that have occurred since the initiation of the transaction.
Caché equivalent: $ZERROR
Purpose: Contains the text of the error message most recently produced by the application or programmer.
Notes: Caché will report Caché-specific error text that may or may not correspond to MSM’s error text.
Caché equivalent: No direct equivalent.
Purpose: Contains a number that indicates the current nesting level.
Notes: Use $STACK
