Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

Open M Language Compatibility

Caché offers language compatibility modes for:

  • DSM-11

  • Open M [DSM]

  • Open M [DTM]

  • Open M [MSM]

These modes make it possible to port applications from the above installations into Caché by accommodating the syntax of many of the more common M programming language commands and functions into ObjectScript. ObjectScript is a superset of the ISO 11756-1999 standard M programming language. The ISO 11756-1999 standard is identical to the former ANSI-standard M programming language.

This chapter presents the following topics as they relate to compatibility modes:

Displaying and Switching Language Mode

Caché provides the LanguageMode()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class that allows you to display and set the language mode. LanguageMode(n) sets the language to mode n and returns the previous value. LanguageMode() with no argument returns the current value.

Do not modify the current dialect using LanguageMode() when there is already a routine in the partition created under a different dialect.

Note:

You cannot set the language mode from the GUI utilities. You must use the LanguageMode()Opens in a new tab method.

If you follow the procedures outlined in this section to port, manage, and convert DSM mode routines, you do not need to use LanguageMode() method calls to set language mode. If you want to use LanguageMode() to see the current language mode, issue the following command:

  WRITE ##class(%SYSTEM.Process).LanguageMode()

You can also set the language mode by any command that affects loading of a routine. The current dialect will be set to that of the routine. In the case of a DO, the previous dialect is restored upon leaving the routine. This will also happen for ZLOAD or GOTO done within command indirection (XECUTE).

The general-use language modes represented in Caché are as follows.

Caché Language Modes
LanguageMode() Value Language Mode
0 Caché
1 DSM-11
2 DTM
5 DSM
6 DSM-J (Japanese version)
7 DTM-J (Japanese version)
8 MSM

DSM-11 Language Compatibility

Caché operates in DSM mode when working with a DSM-11 routine that has been ported. You need not make extensive changes in order to run DSM-11 routines that have been ported to Caché . This section discusses how various commands and functions operate in DSM-11 mode.

DSM-11 Language mode is set using the LanguageMode(1)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

Note:

Pay particular attention to Lock, ZAllocate, and ZDeallocate.

Using Routine Interlock Devices

Routine interlock devices provide an alternative to the standard M Lock command. Routine interlock devices were developed so DSM-11 applications would not run out of space in the DSM-11 Lock Table.

This functionality is especially designed for DSM-11 compatibility mode, with applications ported from DSM-11. However, it operates in Caché language mode as well.

Opening Special Devices to Lock a Global

Device numbers 20 through 46 and 200 through 223 serve as routine interlock devices. They are pseudodevices that processes use cooperatively, so that they can regulate updates to the same data. The routine interlock device numbers exist on all Open M and Caché systems.

Two or more processes must agree to use one of these device numbers for a particular purpose. One process issues an Open command for that device, and performs any necessary processing on data associated with that device. If a second process tries to open that device, it must wait until the first one closes the device. Consequently, the second process performs no processing until it successfully opens the device or times out. Any number of processes can attempt to open the device; each one waits until the one before it releases the device with a Close command.

In this way, an Open command to a routine interlock device guarantees a process exclusive access to the data associated with the device, as long as all applications:

  • Are consistent in their use of this technique (as with the Lock command)

  • Agree on the data associated with each routine interlock device

After the process issues a Close command to that device number, another process can open the device and have exclusive access to the data.

Issuing I/O Commands for Routine Interlock Devices

Open and Close are the only I/O commands you can issue to routine interlock devices. There are no Read and Write commands, because using a routine interlock device does not involve transferring data in or out of any device or memory area.

Open Command

The Open command opens a routine interlock device and prevents other processes from successfully issuing an Open command to the same device number.

Syntax
Open device[::timeout]
Parameter Description
device A device number, from 20 through 46 or 200 through 223. You must ensure that all routines that use a given device number agree on the meaning of that number. The meaning is usually which global(s) are now considered locked and thus not available to other processes.
timeout A positive integer whose value in seconds is the longest time Caché waits for an Open to finish. If you specify 0, the Open returns control to the process immediately.

Close Command

The Close command closes a routine interlock device and releases it to other processes.

Syntax
Close device

Working with DSM-11 Mode Routines

Keep the following points in mind when working with DSM-11 mode routines on a Caché system:

  • DSM-11 and InterSystems routines can coexist in the same namespace.

  • Caché and DSM-11 mode routines can call one another as desired. Caché adapts to the saved language mode of the executing routine on a per routine basis.

  • DSM-11 mode routines can only be saved as intermediate source code (.INT) routines. They cannot be manipulated at the macro source code (.MAC) level.

  • Caché provides only runtime support for the DSM-11 language. It does not support the DSM-11 development environment, nor does it support calls to the DSM-11 library utilities or MACRO-11 routines.

  • You can only do further development on DSM-11 routines in the Caché development environment.

  • When you load a routine with the Full Screen Editor or the ZLoad command, Caché sets the language mode to match that of the routine.

  • If you change the language mode with the LanguageMode()Opens in a new tab method so that it does not match that of the loaded routine, and then attempt to do a ZInsert, you will get a <LANGUAGE MISMATCH> error message.

Converting a Routine from DSM-11 Mode to Caché Mode

At any time, you can edit a DSM-11 routine to conform to Caché and change its language mode to Caché . The Studio editor facilitates the conversion of DSM-11 mode routines to Caché mode.

Routine Manipulation

Saving and Restoring Routines

After you have DSM-11 mode routines on your Caché system, you can use the utilities %RO and %RI or Studio with them. These utilities maintain the DSM-11 mode of the routines, which lets allows you copy routines that you have copied from a DSM-11 host to a Caché host to additional Caché namespaces and/or hosts using the Caché %RO and %RI utilities.

Listing Routines in the Current Namespace

The %RD utility, which lists the routines in the current Caché namespace, includes a column “LANG” in its long form display that reflects the saved language mode of each routine. The “LANG” column is empty for Caché mode routines and contains “DSM11” for DSM-11 mode routines. You can also use the Management Portal to list routines.

%RCOPY and %RCOMPIL

The %RCOPY and %RCOMPIL routine utilities recognize and preserve the language mode of each routine. %RCOPY copies routines and generates backup versions. %RCOMPIL compiles macro source and intermediate code routines.

Use %RCOPY to rename a DSM-11 mode routine without converting it to Caché mode. You can also use the Studio.

Studio and Routine Line Editor

The Studio and the Routine Line Editor (X ^%) recognize and preserve the language mode of each routine, if you SAVE and COMPILE. The Routine Properties dialogue in the Studio displays the language mode of the current routine.

Transferring Globals from DSM-11 Systems

ANSI-Collated Globals

To transfer ANSI-collated globals from a DSM-11 system to a Caché system, first read them from the DSM-11 system using the Studio with the DSM-11 file format.

String-Collated Globals

To transfer string-collated globals from a DSM-11 system to Caché, first read the globals from the DSM-11 system using the DSM-11 %GTO utility. Then, use the %GCREATE utility on the InterSystems host to create each global and give it the pure string collation characteristic. Finally, load the globals in using the %GIGEN utility.

I/O Programming in DSM-11 Compatibility Mode

The following sections discuss input and output programming characteristics of Caché DSM-11 compatibility mode.

Terminal I/O in DSM-11 Compatibility Mode

In Caché, the OPEN command for terminals offers five parameters: margin, protocol, terminators, portstate, baud. In Caché, the USE command for terminals offers only three parameters: margin, protocol, terminators. (For further details, refer to OPEN and USE Commands in the Terminal I/O chapter of the Caché I/O Device Guide.)

By contrast, in DSM-11 the Open and Use commands accommodate eleven parameters. Most of these parameters exist because DSM-11 also serves as its own operating system. In DSM-11 compatibility mode, Caché simulates the DSM-11 syntax, accepting but ignoring parameters that relate to the operating system.

The following two tables describe the Caché DSM-11 compatibility mode interpretation of the eleven DSM-11 Open and Use command parameters.

DSM-11 Compatibility Mode Open/Use Command Parameters
Parameter DSM-11 Meaning DSM-11 Compatibility Mode Interpretation
p1: margin Set right margin for device. Same as DSM-11. Identical to Caché mode margin parameter both in functionality and parameter position.
p2: output ring buffer Set the size of the output ring buffer. Accepted but ignored.
p3: input field length Specify field length. This parameter serves only for DSM-11 backward compatibility. The Read command is now the preferred technique for specifying field length. Accepted but ignored.
p4: input ring buffer Set the size of the input ring buffer Accepted but ignored.
p5: set status Modify device characteristics Bit mask related to InterSystems mode protocol parameter. See next table for details.
p6: clear status Modify device characteristics Bit mask related to Caché mode protocol parameter.
p7: set $X and $Y Change $X and $Y settings for the terminal. See next table for details.
p8: line parameter register Values assigned based on the type of controller. Accepted but ignored.
p9: terminators Establish a set of line terminators for the device. Same as DSM-11. Equivalent to Caché mode terminators parameter in functionality, although it occupies a different parameter position.
p10: set application interrupt key Establish a set of application interrupt keys for the device. Accepted but ignored.
timeout Specify the length of time to suspend execution if the requested device is not free. Same as DSM-11. Identical to Caché mode timeout parameter both in function and in parameter position.

The protocol parameter in Caché mode is a string containing some combination of the following:

  • B (enable Ctrl-C)

  • C (CRT)

  • F (flush)

  • I (image)

  • P (printer)

  • S (secret, no echo)

  • T (terminators).

Similarly, DSM-11 has the set status and clear status parameters, both of which are bit masks.

To turn on a protocol, you must include its bit in the set status parameter. To turn off a protocol, you must include its bit in the clear status parameter. In DSM-11 compatibility mode, Caché accepts but ignores bits that are operating system specific. The following table lists the bits that are supported.

DSM-11 Compatibility Mode Set and Clear Status Bits
Bit Value Description
0 (1) 0 - Echo; 1 - No Echo Identical to Caché “S” protocol.
2 (4) 0 - Hardcopy; 1 - CRT Identical to Caché “C” protocol.
6 (64) 0 - Escape Processing Disabled; 1 - Escape Processing Enabled Determines how escape sequences are handled on Read. In Caché mode, an escape sequence always terminates a non image mode Read, and the escape sequence appears as a string in $ZB. In DSM 11 mode, an escape sequence always terminates a normal Read, but the escape sequence is processed only if escape processing is enabled. When escape processing is enabled, the decimal ASCII code of the second character appears in the high byte of $ZB and the decimal ASCII code of the escape character itself appears in the low byte. When escape processing is disabled, the escape character is treated like any terminator and the remaining character(s) of the escape sequence are not processed. They remain in the input buffer where they can be accessed by subsequent Read commands.
7 (128) 0 - Do Not Transmit Cursor Control Sequences; 1 - Transmit Cursor Control Sequences Determines the handling of parameter 7: set $X and $Y. When a parameter 7 value is supplied on Open/Use in DSM-11 language compatibility mode, $X and $Y are updated accordingly and if bit 7 is ON, the appropriate cursor control sequence (VT52 or ANSI, depending on bit 16) is transmitted to the terminal.
14 (16384) 0 - No conversion; 1 - Convert to uppercase Determines whether or not case is converted on input.
16 (65536) 0 - VT52; 1 - ANSI Determines the appropriate cursor control sequence.
19 (524288) 0 - Ignore Delete Character; 1 - Acknowledge Delete Character Determines the effect of pressing the Delete key when there is nothing in the input buffer to delete. If the bit is ON, the delete character is ignored. If the bit is OFF, the Read terminates and the delete character appears as 127 in the low byte of $ZB.
20 (1048576) 0 - Accept non-programmed ctrl keys; 1 - Ignore non-programmed ctrl keys. Determines the effect of pressing non-programmed control keys. When the bit is OFF, all non- programmed control keys are accepted as normal characters. When the bit is ON, non-programmed control keys are ignored. They are not echoed or placed in the input buffer.
23 (8388608) 0 - Disable Pass All; 1 - Enable Pass All Identical to Caché IMAGE mode protocol. When the bit is ON, all control characters pass directly to the program without filtering or interpretation.
25 (33554432) 0 - Enable Type-ahead; 1 - Disable Type-ahead Determines the handling of type- ahead. When bit 25 is ON, type- ahead is disabled. The input buffer is flushed before each Read. When bit 25 is OFF, type-ahead is enabled. The input buffer is not flushed before each Read.
26 (68108864) 0 - Default to Bit 25, Type- ahead control; 1 - Do not flush Type-ahead Buffer. When bit 26 is OFF, no additional type-ahead control beyond that provided by bit 25 is conferred. When bit 26 is on, the type-ahead buffer can never be flushed, unless explicitly directed by bit 25. For example, Read with a prompt does not flush type-ahead.

On Windows, ObjectScript allocates each process an open file quota between database files and files opened with Open. When Open causes too many files to be allocated to Open commands, you receive a <TOOMANYFILES> error message. Caché does not limit the number of open files; the maximum number of open files for each process is a platform-specific setting. Consult the operating system documentation for your system.

Caution:

Open/Use parameters that are unique to DSM-11 compatibility mode are honored at Read/Write time only if the last Open/Use of the device was in DSM-11 mode. The parameters unique to DSM-11 mode are p5/p6 (bits 6,7,19,20,25,26) and p7.

Terminating a READ

If a terminator completes a Read, the special variable $ZB contains the terminator character as a string in Caché mode, while in DSM-11 mode the ASCII decimal value of the terminator is returned in the low byte of $ZB.

If an escape sequence terminates a Read, Caché mode returns the ASCII escape sequence as a string in $ZB, while DSM-11 mode returns an integer with the escape character (27) in the low byte of $ZB and the second character plus 16 then modulo 64 in the high byte.

Magnetic Tape I/O

The I/O commands for magnetic tape are very similar in Caché and DSM-11. Both use the positional parameter style, and the positions and values of the specific parameters in each are quite similar. However, there are some differences in format codes, which account for these unique characteristics of magnetic tape I/O in DSM-11 compatibility mode:

  • Caché does not support the DSM-11 “B” format.

  • DSM-11 offers a “C” format, which specifies continuous (non-pending) I/O. This enables the program to go on and do other things while the tape I/O is in progress. You can check the status of the I/O at any time by issuing the Write *10 command, which updates $ZA. While Caché cannot actually do this on the UNIX® or Windows operating systems, it does accept the “C” format in DSM-11 compatibility mode so that DSM-11 applications encoded with it do not require source changes to run. Instead, Caché performs the following steps:

  • Performs the I/O.

  • Waits for the program to complete and then move on.

  • Updates $ZA with the completion status when the program issues the Write *10.

  • The DSM-11 “T” format specifies tape mark trap inhibiting in DSM-11 compatibility mode.

  • The format string characters used to specify tape density for DSM-11 and Caché relate as follows:

    DSM-11 mode Caché mode Tape Density (BPI)
    3 1 800
    4 2 1600
    5 3 6250

  • In DSM-11 mode, the $ZA and $ZB special variables return magnetic tape operation values that are compatible with DSM-11.

  • In Caché mode, magnetic tape control functions are accomplished by using Write * -n (negative value), while DSM-11 compatibility mode uses Write * n (positive value). The assignments of the absolute values to control functions are the same for both modes, except that DSM-11 offers Write *10, which updates $ZA. This is useful with the DSM-11 “C” format option for checking the status of the asynchronous I/O operation, as discussed above.

Interjob Communications Devices (JOBCOM)

Caché offers devices 224 through 255 for interjob communications in both language modes. For more information on how to use these devices, see the chapter “Interprocess Communication.”

VIEW Command and $VIEW Function

Caché does not support the VIEW command or the $VIEW function in DSM-11 compatibility mode.

ZAllocate and ZDeallocate

The ZAllocate and ZDeallocate commands behave differently in Caché and DSM-11:

  • In the DSM-11 mode, ZAllocate can only be undone by ZDeallocate and LOCK+ can only be undone by Lock. Moreover, any number of ZAllocate commands of a certain location can be undone with a single ZDeallocate.

  • In Caché mode, ZAllocate and ZDeallocate are synonymous with Lock+ and Lock.

The ZaModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class allows you to select which behavior ZAllocate and ZDeallocate enact system-wide: Caché mode or DSM-11 mode.

Determining Which Mode to Use

In DSM-11 compatibility mode, ZAllocate and ZDeallocate by default behave as they do in DSM-11. Because of the difference between these modes, always examine code you are porting from a DSM-11 system to ensure that changes in nesting characteristics of Lock and ZAllocate will not affect the integrity of your application.

Set Mode in ZSTU

If you have ported your ZA and ZD commands to Caché mode, but are still compiling in DSM-11 mode, set ZaMode in your ZSTU startup routine to be certain ZA and ZD will be interpreted in Caché mode.

Extended Functions for DSM-11 Mode

Caché supports the following functions in both language modes:

  • $ZNext

  • $ZOrder

  • $ZPrevious

  • $ZSort

These are deprecated legacy functions in Caché.

Unsupported DSM-11 Functions

Caché does not support the following DSM-11 functions:

  • $ZCall

  • $ZUCI

Caution:

Because the $ZUCI function can be abbreviated as $ZU, you must be sure to remove all references to it from DSM-11 applications that you port to Caché, so that Caché does not treat them as calls to the Caché $ZU(n) ($ZUTIL(n)) functions.

Extended Special Variables for DSM-11 Mode

Caché supports the following special variables in both language modes:

Caché supports these special variables only in DSM-11 mode:

Both $ZA and $ZB return DSM-11 values.

Extended Commands for DSM-11 Compatibility Mode

Caché supports the following DSM-11 command in both language modes:

Caché supports the following commands in DSM-11 compatibility mode:

  • ZPrint

  • ZWrite

  • ZBreak

ZPrint is identical to the Caché mode PRINT command.

ZWrite is identical to the argumentless WRITE command.

In DSM-11 M, the ZBreak ON and ZBreak OFF commands control the processing of argumentless Break commands. The BreakMode()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class simulates this DSM-11 behavior and works in both language modes.

Issuing BreakMode(0) disables the processing of argumentless Break commands (similar to ZBreak OFF). Issuing BreakMode(1) enables the processing of argumentless Break commands (similar to ZBreak ON). Issuing BreakMode() without an argument returns the current state of the switch without changing it.

Error Handling for DSM-11 Compatibility Mode

Error Messages

In DSM-11 mode, the error messages returned by the $ZERROR special variable use the same spelling as their DSM-11 counterparts.

BREAK 2 Error Handling

In DSM-11 mode, Caché supports DSM-11 version 2 error handling. DSM-11 version 2 style error handling provides that whenever an M error occurs the entire frame stack is cleared and a GoTo is executed to the error handling routine.

To preserve this style of error handling, use the BREAK 2 command to enable DSM-11 version 2 error handling. To revert to normal DSM-11 error handling, issue the BREAK -2 command. You can invoke these commands in DSM-11 compatibility mode only.

If a routine that is executing in DSM-11 compatibility mode calls a normal language mode routine, such as a system utility, Caché standard error handling applies throughout the execution of that routine.

$TEXT Comment Lines

Caché supports the double semicolon feature that lets you include specific comment lines in the compiled result. This feature is necessary when the comment line is referenced by the $TEXT function, and the routine is to be distributed without source code. Because DSM-11 has no equivalent feature, $TEXT in DSM-11 mode requires that the source code always be available.

DSM Language Compatibility

Caché operates in DSM mode when working with a DSM routine that has been ported. You need not make extensive changes in order to run DSM routines that have been ported to Caché. This section discusses how various commands and functions operate in DSM mode. DSM Language mode is set using the LanguageMode(5)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

Porting Routines from DSM to Caché

Caché operates in DSM mode when working with a DSM routine that has been ported. To port routines from DSM to Caché use the DSM %RS utility to save native DSM applications to tape or disk. Then, restore the applications on the Caché system using the Studio editor or the %RI utility.

The %RI utility and the Restore utility with DSM format recognize native DSM %RS files and load (compile and save) them as DSM mode routines.

Keep the following points in mind when working with DSM mode routines on a Caché system:

  • DSM and Caché routines can coexist in namespaces.

  • Caché and DSM routines can call one another as desired. Caché adapts to the saved language mode of the executing routine on a per routine basis.

  • Caché provides only runtime support for the DSM language. It does not support the DSM development environment, nor does it support calls to DSM library utilities or $ZCALLs.

  • When you load a routine with the ZLoad command, Caché sets the language mode to match that of the routine.

  • If you change the language mode with the LanguageMode()Opens in a new tab method so that it does not match that of the loaded routine, and then attempt to do a ZInsert, you will get a <LANGUAGE MISMATCH> error message.

Note:

Currently %RI and ^%rde report <SYNTAX> errors on some DSM language features in a DSM mode routine. This indicates that the syntax is not valid ObjectScript syntax. However, the code will interpret correctly if it is a currently recognized DSM language feature in DSM compatibility mode.

Programming in DSM Language Mode

In Caché, the Close, Open, Use, and Job commands feature position-based parameter values separated by a colon (:) character. For example:

Use terminal:[([margin]:[protocols]:[terminators])]:"mnespace"

By contrast, in DSM the Close, Open, Use, ZUse, and Job commands feature keyword syntax where keywords and not position give meaning to parameter values. For example:

Use terminal:[keylist]:"mnespace"

wherekeylist is one of the following:

keyword [=value](keyword[=value][,...])

In each, the intent is to communicate information about operations to the specified device. For example the programmer may want to convert Read command input characters to uppercase. In Caché native language mode, this is done with the following syntax:

Use 0pen:(:"+U")

and in DSM language mode the following accomplishes the same thing:

Use 0pen:CONVERT

Currently DSM language mode supports certain keywords for terminal type devices. The following keyword is recognized but treated as a no-op for the Open command:

BLOCKSIZE=n

The following keywords are recognized and functional when applied to sequential files (Windows platforms only) by the Open command:

  • DELETE

  • NEWVERSION

  • READONLY

  • RECORDSIZE

The DISCONNECT keyword is recognized and functional when applied to sequential files by the Use command.

The following keywords are recognized and functional when applied to sequential files by the Close command:

  • DELETE

  • NODELETE

  • RENAME

For discussions on how to use the above keywords, see the DSM documentation.

The following exceptions apply to Caché in DSM language mode:

  • When closing a newly created file, DSM will delete the file if nothing has been written to it. However, in Caché the Close command in DSM language mode does not delete the file.

  • The RECORDSIZE keyword specified with the Open command for sequential files currently affects Read operations only.

  • When the RENAME keyword is specified with the Close command and the file to be closed is marked for delete, DSM deletes the file, then generates a %DSM-E-RENAMERR error. However, in Caché the Close command in DSM language mode renames the file and does not delete it.

  • When the RENAME and DELETE keywords are specified with the Close command, DSM deletes the file then generates a %DSM-E-RENAMERR error. However, in Caché the Close command in DSM language mode deletes the file.

The following keywords are recognized and functional for the Use command:

  • CENABLE

  • CLEARSRCR

  • CONVERT

  • CURSOR

  • DEVTYPE=s

  • DOWNSCRO

  • ECHO

  • ERASELIN

  • LINE

  • NOCENABL

  • NOCONVERT

  • NOCURSOR

  • NOECHO

  • NOLINE

  • NOREADPFLU

  • NOTYPE

  • READPFLU

  • TERMINATOR=s

  • TYPE

  • UPSCROLL

  • WIDTH=n

  • X=n

  • Y=n

BREAK 0 must be active to allow CENABLE and NOCENABL to have their intended effect. BREAK 0 is the default in Application Mode. However, BREAK 1 is the default in Programmer mode and is implicitly reasserted at every Programmer Mode prompt. Therefore BREAK 0 must be re-typed at every Programmer Mode prompt to interactively test the CENABLE and NOCENABL keywords.

The CLEARSCR, DOWNSCRO, ERASELIN, UPSCROLL, X=n, and Y=n keywords cause VT100 escape sequences to be written to the specified device and will only work with devices that recognize the sequences. When the specified device is a console window, the system automatically translates the escape sequences into window operations that perform the desired result.

The LINE and NOLINE keywords enable and disable Caché read line recall. Read line recall may initially be disabled by default. Use the LineRecall()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class to enable read line recall by default for your process.

In DSM, the TYPE and NOTYPE keywords have no effect unless the /TYPEAHEAD command line qualifier is in effect for the DSM process.

In DSM for DEC OSF/1 AXP the same is true, but the NOREADPFLU keyword can be used to accomplish dynamically the same thing as the /TYPEAHEAD command qualifier while READPFLU negates the /TYPEAHEAD behavior.

Therefore NOREADPFLU and READPFLU are provided in DSM compatibility mode so that NOREADPFLU can be specified for the principal device at application start up to accomplish the same behavior as the DSM /TYPEAHEAD qualifier.

DSM compatibility mode recognizes the following keywords but treats them as no-ops for Use:

  • ESCAPE (in effect by default)

  • FLUSH

  • NOPACK

  • PACK

DSM language mode also supports several keywords for the Job command. The following keywords are recognized and functional:

  • DATA

  • INPUT

  • OUTPUT

The following keywords are recognized but treated as no-ops for Job:

  • DETACHED (also a no-op on DSM systems)

  • ERROR

  • NAME

  • PRIORITY

  • OPTIONS

DSM compatibility mode currently handles all other standard M commands except the BREAK and VIEW commands, which (according to the standard) take implementer-specific arguments.

Device Control Mnemonic Spaces and Device Control Mnemonics

DSM compatibility mode in Caché provides a migration path for most DSM applications that use mnemonic spaces and device control mnemonics.

For applications that can be migrated, the application code itself need not be changed. In many cases a routine name change is all that is required and in the other cases only routine entry point bridges are required.

Device control mnemonics are keywords that are used with the WRITE / format character and the READ / format character to perform device control. For example, in a X3.64 compliant mnemonic space, the command

Write /CUP(1,1)

performs cursor positioning. In DSM, user defined mnemonic space tables associate the keywords in the mnemonic space with routine entry points that are called at runtime to perform the operation. DSM applications associate a mnemonic space table and the keywords defined by it with a device by specifying the mnemonic space name with an Open or Use command.

Caché does not use a table to map the device control mnemonics in a mnemonic space to M routine entry points. Rather it infers the entry point label name from the control mnemonic (the control mnemonic is converted to uppercase to form the label name) and it uses the current mnemonic space name specified for the device as the entry point routine name.

For example, in the following sequence Caché calls back to the M routine entry point CUP^%X364 as a result of the WRITE / command:

Set DevZero=0
Use DevZero::"^%X364" Write /CUP(1,1)

If your user-defined mnemonic space tables specify case conversion for control mnemonics, you can update your application to run in DSM compatibility mode in Caché .

Further, if all your control mnemonics already match all the label names of their associated ObjectScript routine entry points, then all that is necessary is that all labels be present in a single routine. If any control mnemonic does not match the label name of its associated ObjectScript routine entry point then an entry point “bridge” whose label name does match the control mnemonic can be added. The entry point bridge needs only to call the original target ObjectScript routine entry point passing along any expected parameters.

Of course, you can produce the same effect by changing the label name of the original entry point. Whether bridge entry point labels or original entry point labels, all must be present in a single ObjectScript routine.

In DSM compatibility mode, Caché determines the name of the ObjectScript routine that contains control mnemonic call back labels in one of two ways. When a specified mnemonic space name begins with the “^” character Caché assumes the mnemonic space name is the ObjectScript routine name; otherwise it adds a “^%Z” prefix to the mnemonic space name to form the ObjectScript routine name. This latter case will be the rule unless you update your DSM application code (usually a less desirable option).

The following sequence is an example of the latter case:

Set DevZero=0
Use DevZero::"ZTERM" Write /CUP(1,1)

In this sequence Caché performs a callback to the ObjectScript routine entry point CUP^%ZZTERM as a result of the Write / command.

The names of the ObjectScript routines containing control mnemonic callback entry points can be changed to adhere to this convention.

Other DSM Language Features Implemented in Compatibility Mode

The following DSM Z commands are recognized and functional:

  • ZAllocate

  • ZDeallocate

  • ZInsert

  • ZLoad

  • ZPrint

  • ZRemove

  • ZSave

  • ZTrap (generates an error but DSM style error handling and error messages are not currently implemented)

  • ZWrite (only the argumentless form is implemented)

The DSM ZUse command is recognized but treated as a no-op. Note that ZUse keywords are not currently implemented.

The following DSM Z functions are recognized and functional:

  • $ZDate

  • $ZNext

  • $ZOrder

  • $ZPrevious

  • $ZSearch (works only on Caché for Windows)

  • $ZSort (a subscriptless global $ZSORT argument is not currently implemented)

The following DSM I/O related Z special variables are recognized and functional for terminal devices:

  • $ZA

  • $ZB

  • $ZCONTROLC

  • $ZIO (works only on Caché for Windows)

The following other DSM Z special variables are recognized and functional:

  • $ECODE

  • $ESTACK

  • $ETRAP

  • $QUIT

  • $STACK

  • $ZDEVTYPE

  • $ZERROR (contains error information but DSM-style error handling and error messages are not currently implemented)

  • $ZJOB

  • $ZNAME

  • $ZREFERENCE

  • $ZTRAP

  • $ZVERSION

The following DSM library external functions ($ZCALLs) are recognized and functional.

Mathematical:

  • %ARCCOS

  • %ARCSIN

  • %ARCCTAN

  • %BOOLEAN

  • %COS

  • %EXP

  • %LOG

  • %LOG10

  • %MAX

  • %MIN

  • %POWER

  • %SIN

  • %SQRT

  • %TAN

Note:

The precision in the numbers returned for these functions may be somewhat different from DSM systems

Text Manipulation:

  • %TRANSLATE

  • %UPCASE

  • %UPCASEQ

Date and Time:

  • %CDATASC

  • %CDATNUM

  • %CTIMASC

  • %CTIMNUM

Miscellaneous:

  • %LPC

VIEW Command and $VIEW Function

Since the VIEW command and $VIEW function require knowledge of the contents of disk or memory structures, which vary from one implementation to another, Caché does not support the VIEW command or the $VIEW function in DSM compatibility mode.

Database Conversion

The utility %dsmcvt converts a DSM database into a Caché database. When run, %dsmcvt prompts you for the directory containing the DSM database to be converted. The database is converted to a Caché database in the current namespace.

DSM-J Language Compatibility

DSM-J language mode is set using the LanguageMode(6)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

Caché using the DSM-J language mode supports the following keywords when applied to sequential files by the Use command:

  • KAN[JIDEVICE]

  • NOKAN[JIDEVICE]

  • KCODE=conversion_specification

  • KON[ESCAPE]=escape_sequence

  • KOFF[ESCAPE]=escape_sequence

  • KPITCH=pitch_value

  • KDIR[INPUT]

  • NOKDIR[INPUT]

  • KIN=switch (switch= “ON” or “OFF”)

For a complete discussion of the above-listed command keywords, see the DSM-J documentation.

DTM Language Compatibility

Caché operates in DTM mode when working with a DTM routine that has been ported. This section discusses which commands and functions operate in DTM mode and notes any variations in how they operate. DTM Language mode is set using the LanguageMode(2)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

Programming in DTM Compatibility Mode

In general, when you are programming in DTM compatibility mode, ObjectScript operates as it would on a native Open M [DTM] system. Routine line structure follows DTM rules, so that your routines can use DTM-specific language elements.

However, there are several points you should especially keep in mind when using DTM mode.

Operators

You can use the DTM-specific operators in DTM compatibility mode. These operators are:

<> The record-forming operator. The record-forming operator creates a string which contains the pieces in between the angle brackets. Example: If $ZPIECE is equal to “^” and you issue Set x = <a,b>, then x equals “a_"^"_b”
.n The field operator. The field operator sets a string equal to the n th piece of another string. Example: If s equals “s12^ab”, then s.2 equals “ab”

JOB Command

In Open M [DTM] compatibility mode, the JOB command operates as does the JOB command on a native Caché system. This means there is a substantial difference in the JOB command parameters: Caché process parameters are supported; DTM process parameters are not supported.

In Caché, the process parameters for JOB can be four positional values. These are:

(default:switch:principal-input:principal-output)
default The default namespace for the jobbed process.
switch An integer bit mask value specifying whether Caché should pass your current symbol table to the new process, and other information.
principal-input The principal input device for the process.
principal-output The principal output device for the process.

Because the parameters are positional, you must specify them in the order shown. If you omit a parameter that precedes a parameter you are including, you must include a colon as a placeholder for it. See the JOB command in the ObjectScript Language Reference for more information.

In DTM, the process parameters can be up to 10 values. Each is in the form:

keyword=value
keyword The name of a specific process parameter.
value The value you want to assign the process parameter.

The keywords you can use are:

lvmem The amount of memory (in bytes) to allocate for the jobbed process’ symbol table.
lvmin The minimum amount of memory (in bytes) to allocate for the symbol table.
lvmax The maximum amount of memory (in bytes) to allocate for the symbol table.
name The name to assign to the job.
node The name of the network node on which the job is to run.
nspace The namespace in which to execute the job.
pdev The principal device of the job.
priority The priority of the job (0 through 9).
strstk The size of the string stack in bytes.
sysstk The size of the system stack in bytes.

Because of the keywords, the parameters are not positional. To specify multiple process parameters, use a colon-separated list in the form:

(keyword=value[:keyword=value]...)

You do not have to specify colons for parameters you do not specify.

I/O Commands

In DTM compatibility mode, the I/O commands (Open, Use, and Close) use DTM argument syntax. In general, use the following guidelines when you are in Caché compatibility mode:

  • You can specify the devices you open, use, and close as positive integer values only. The values must be those assigned to them in the DTM .DEV file. You cannot use a device mnemonic.

  • The parameters you employ with Open and Use are device specific. You specify each parameter in the form keyword=value. To specify some parameters and accept the defaults for others, use a colon to occupy each default position. You can omit colons after the last specified parameter. Leading colons are required. Trailing colons for missing parameters are unnecessary. In this example, Open accepts the default device parameters for the device being opened for all but the fifth parameter:

    Open DEV(::::param5)

  • You can use a timeout with I/O commands. You can specify timeouts as integer values, decimal values, or as expressions that evaluate to integer or decimal values.

  • You cannot use control mnemonics with DTM devices.

  • You cannot use device parameters with the Close command. DTM does not recognize Close device parameters.

View and $View

In DTM compatibility mode, View and $View operate as they do on a DTM system.

DSM-11 Compatibility Mode

When your process is in DTM compatibility mode, you can further set it into DTM’ s DSM-11 compatibility mode. You then are able to load and run DSM-11 routines. Use the ZZCOMPAT command to switch between DSM-11 mode and Open M [DTM] compatibility mode. Use the $ZZCOMPAT special variable to determine the mode in which your process is set.

Structured System Variables

You cannot use structured system variables in Open M [DTM] compatibility mode.

Commands, Functions, and Special Variables

The following sections list the commands, functions, and special variables available in DTM compatibility mode.

Commands

These standard M commands operate identically in Caché mode and DTM compatibility mode:

  • Do

  • Else

  • For

  • Halt

  • If

  • Kill

  • Lock

  • Merge

  • New

  • Print

  • Quit

  • Write

  • Xecute

These standard M commands are not available in DTM compatibility mode:

  • TCommit

  • TRollback

  • TStart

These extended M commands operate identically in Caché mode and DTM compatibility mode:

  • ZInsert

  • ZNSpace

  • ZRemove

  • ZSync

  • ZZDump

The following extended M command is not available in Open M [DTM] compatibility mode:

  • ZTrap

Functions

The following standard M functions operate identically in DTM compatibility and Caché mode:

  • $ASCII

  • $Char

  • $Data

  • $Find

  • $FNumber

  • $Get

  • $Justify

  • $Length

  • $Name

  • $Next

  • $Order

  • $Piece

  • $QLength

  • $QSubscript

  • $Query

  • $Random

  • $Reverse

  • $Select

  • $Translate

The following extended M functions operate identically in DTM compatibility and Caché mode:

  • $ZBitAnd

  • $ZBitCount

  • $ZBitFind

  • $ZBitLen

  • $ZBitNot

  • $ZBitOr

  • $ZBitSet

  • $ZBitStr

  • $ZBitXOr

These extended functions are not available in DTM compatibility mode:

  • $ZBoolean

  • $ZF

  • $ZHex

  • $ZIncr

  • $ZNext

  • $ZSearch

  • $ZSort

  • $ZTime

  • $ZU

The following DTM mode math functions operate identically in Caché mode and DTM compatibility mode:

  • $ZAbs

  • $ZArcCos

  • $ZArcSin

  • $ZArcTan

  • $ZCos

  • $ZCot

  • $ZCSC

  • $ZExp

  • $ZLn

  • $ZLog

  • $ZPower

  • $ZSec

  • $ZSin

  • $ZSqr

  • $ZTan

These set up a general error handler and call %math utility entry points. The general error handler turns any reported error into an <ILLEGAL VALUE> error which is returned to the calling routine.

Special Variables

The following standard M special variables are not available in DTM compatibility mode:

  • $ECODE

  • $ESTACK

  • $ETRAP

  • $QUIT

  • $STACK

The following extended M special variables operate identically in Caché mode and DTM compatibility mode:

Database Conversion

The utility %DTMCVT converts a DTM database into a Caché database. When run, %DTMCVT prompts you for the directory containing the DTM database to be converted. The database is converted to a Caché database in the current namespace.

MSM Language Compatibility

Caché operates in MSM mode when working with a MSM routine that has been ported. This section discusses which commands and functions operate in MSM mode and notes any variations in how they operate. MSM Language mode is set using the LanguageMode(8)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

A language mode can be set individually for each routine and a routine compiled in one language mode can call or be called by a routine compiled in another mode. Thus, for instance, an MSM mode routine could call a DTM mode routine which could in turn call another MSM mode routine.

After an MSM application is compiled in the correct language mode, it can be installed and run on any Caché system, no matter what other applications or language modes are used on that system.

Almost all language mode processing occurs at compile time, not runtime. As a result, using a language mode such as MSM will generally deliver the same high performance as Caché native language mode.

Commands, Functions, and Special Variables

The following sections list the commands, functions, and special variables available in MSM compatibility mode.

Commands

These standard M commands operate identically in Caché mode and MSM compatibility mode:

  • Close

  • Job

  • Open

  • Use

These extended M commands operate identically in Caché mode and MSM compatibility mode:

  • ZAllocate

  • ZBreak

  • ZDeallocate

  • ZPrint

  • ZTrap

  • ZWrite

Functions

These extended M functions operate identically in MSM compatibility mode and Caché mode:

  • $ZNext

  • $ZOrder

  • $ZPrevious

  • $ZSort

These are deprecated legacy functions in Caché.

Special Variables

The following extended M special variables operate identically in Caché mode and MSM compatibility mode:

The $ZC special variable in MSM has a completely different meaning than $ZC (an abbreviation for $ZCHILD) in Caché.

Database Conversion

The utility %MSMCVT converts an MSM database into a Caché database. When run, %MSMCVT prompts you for the directory containing the MSM database to be converted. The database is converted to a Caché database in the current namespace.


Previous sectionCommand-line Routine Debugging
FeedbackOpens in a new tab