Skip to main content
Previous section   

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

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")
Copy code to clipboard

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.

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
Copy code to clipboard
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: ObjectScript uses the native SET command, such as:

Set var=Car.Make
Copy code to clipboard
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. 
Copy code to clipboard

MSM code

Write $Order()   ; this returns "%" 
Write $Order(%)   ; this returns "%USER"  
Write $Order(%USER)    ; this returns "var"
Copy code to clipboard

Caché code

Write $Order(@(""))   ; this returns "%"  
Write $Order(%)   ; this returns "%USER"  
Write $Order(%USER)   ; this returns "var"
Copy code to clipboard
$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: ObjectScript uses the native SET command, such as:

Set var=##class(Car).%New()
Copy code to clipboard
$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: ObjectScript uses the native SET command, such as:

Set var=##class(Car).%Open(OREF)
Copy code to clipboard
$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
Copy code to clipboard

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
Copy code to clipboard

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