MSM to Caché Conversion Guide
M Language Differences
[Back] 
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Search:    

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
BREAK
Caché equivalent: BREAK, ZBREAK
Purpose: Invokes the debugger.
Notes: Not supported from interactive debugger.
ZGO not supported in Caché — use argumentless GOTO instead.
CLOSE
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.
DO
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).
JOB
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:
NEW
Caché equivalent: NEW
Purpose: Stacks one or more local variables.
Notes: Caché does not allow $TEST or $ZREFERENCE as arguments to the NEW command.
OPEN
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.
TRESTART
Caché equivalent: Not implemented.
Purpose: Causes current transaction to be restarted.
TSTART
Caché equivalent: TSTART
Purpose: Marks the beginning of a transaction.
Notes: Caché does not support restart variables or transaction parameters.
USE
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.
VIEW
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.
WRITE
Caché equivalent: WRITE
Purpose: Sends output to current device.
Notes: Mnemonic spaces may need to be rewritten for Caché.
ZCALL
Caché equivalent: $ZF
Purpose: Calls an external procedure.
ZFLUSH
Caché equivalent: Not implemented.
Purpose: Flushes all disk blocks out of the internal disk buffer cache.
ZGO
Caché equivalent: argumentless GOTO
Purpose: Resumes execution of a program after a BREAK command.
ZHOROLOG
Caché equivalent: the %SYSTEM.Process FixedDate() method.
Purpose: Sets date and time for current process.
Notes: Caché’s FixedDate() method only allows a new date value, not time.
ZMSM
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
ZNEW
Caché equivalent: Not implemented.
Purpose: Similar to NEW command, but variable is persistent after subroutine explicitly or implicitly quits.
ZQUIT
Caché equivalent: ZQUIT
Purpose: Passes control to the next higher error-processing routine that has been specified by $ZTRAP.
Notes: Caché clears entire stack, unless an argument representing the number of error trap levels to quit back is specified.
ZSETOBJ
Caché equivalent: SET
Purpose: Assigns an object reference to a variable.
Notes: Caché ObjectScript uses the native SET command, such as:
Set var=Car.Make
ZUSE
Caché equivalent: the %Library.Device Broadcast() method or the %SYSTEM.Process Broadcast() 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
^$DEVICE
Caché equivalent: Not implemented.
Purpose: Provides information on the existence, operational characteristics, and availability of a device.
Functions
$ORDER
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"
$VIEW
Caché equivalent: $VIEW
Purpose: Returns contents of memory locations.
$ZASCII
Caché equivalent: $ASCII
Purpose: Returns the Unicode character code of a specified character.
$ZBN
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.
$ZBname
Caché equivalent: $ZBIT<name>
Purpose: A collection of functions that are used to perform logical operations on bitstrings.
$ZCALL
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)].
$ZCHAR
Caché equivalent: Not available.
Purpose: Returns a string of characters, given a list of Unicode character codes.
$ZCRC
Caché equivalent: $ZCRC
Purpose: Returns a computed checksum or cyclic redundancy check.
$ZCREATEOBJECT
Caché equivalent: SET
Purpose: Returns an object reference to a newly instantiated object.
Notes: Caché ObjectScript uses the native SET command, such as:
Set var=##class(Car).%New()
$ZDATE
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.
$ZDEVICE
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.
$ZGETOBJECT
Caché equivalent: SET
Purpose: Retrieves database object, and returns object reference to the instantiated object.
Notes: Caché ObjectScript uses the native SET command, such as:
Set var=##class(Car).%Open(OREF)
$ZHL
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.
$ZOBJREFERENCE
Caché equivalent: Not available.
Purpose: Identifies whether an expression refers to an object, and whether two expressions refer to the same object.
$ZOS
Caché equivalent: $ZF(-1), $ZSEARCH, OPEN
Purpose: Invokes commonly used host OS functions from within M.
$ZPOSITION
Caché equivalent: Not available.
Purpose: Returns the number of positions of a string that can fit in a field, on an output device.
$ZUCI
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.
$ZVERIFY
Caché equivalent: Not available.
Purpose: Returns a string of errors, if any exist, in the logical structure of the database.
$ZWIDTH
Caché equivalent: Not available.
Purpose: Returns the width that a string occupies when it is displayed on an output device.
Preprocessor Directives
#comment
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.
#defarray
Caché equivalent: Not available.
Purpose: Defines a macro to be used for referencing an array.
#deflabel
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.
#include
Caché equivalent: #include
Purpose: Includes source code in a given routine.
Notes: In Caché, #include can only be used to reference .INC code.
#library
Caché equivalent: Not available.
Purpose: Specifies path to library files.
#makelib
Caché equivalent: Not available.
Purpose: Creates a macro library.
#nocomment
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.
#noroutine
Caché equivalent: Not available.
Purpose: Prevents generation of an M routine.
#prefix
Caché equivalent: Not available.
Purpose: Defines the prefix used to identify a macro reference.
#routine
Caché equivalent: Not available.
Purpose: Specifies the name of a routine to be generated.
#undefine
Caché equivalent: #undef
Purpose: Removes a macro definition.
Notes: In Caché, you must change all #undefine statements to #undef.
#updlib
Caché equivalent: Not available.
Purpose: Updates a macro library.
#x
Caché equivalent: Not available.
Purpose: Executes M code during preprocessing.
Special Variables
$DEVICE
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".
$ECODE
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,
$IO
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.
$JOB
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.
$PRINCIPAL
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.
$SYSTEM
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.License class:
These methods are implemented in the special $SYSTEM object and can be accessed with the $SYSTEM.License.Method() syntax.
$TRESTART
Caché equivalent: Not implemented.
Purpose: Indicates the number of transaction restarts that have occurred since the initiation of the transaction.
$ZB
Caché equivalent: $ZB, $ZCHILD
Purpose: Returns device-specific information for the current device. When used with the JOB command. MSM’s $ZB returns the jobbed process’ PID. 
Notes: For this functionality in Caché, use $ZCHILD.
$ZC
Caché equivalent: Not implemented.
Purpose: Contains device-specific information for the current device.
Notes: In Caché, $ZC is used to represent both the $ZCHILD special variable and $ZCYC function, depending on context.
$ZERROR
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.
$ZLEVEL
Caché equivalent: No direct equivalent.
Purpose: Contains a number that indicates the current nesting level.
Notes: Use $STACK