Copyright: TECHREF.HLP, documentation for MSM-Workstation 2.0, copyright © 1998 Micronetics Design Corporation   Monday, April 13, 1998 21:19:47%
Citation: Extract from TECHREF.HLP, documentation for MSM-Workstation 2.0, copyright © 1998 Micronetics Design Corporation


Help Contents
Contents

Errors

Macros

Service Routines

Legacy Utilities

Special Functions and Variables

External Call Functions

External Access

Devices

Switches and Settings

GUI Reference


Errors

Format of $ZERROR

MSM Error Codes

MSM Error Numbers

$EC Error Codes

$ZOS Error Codes

%MERR Error Codes


Macros

Overview

Macro Parameter Domains

Macros A-Z

Macros by Function

Macros


Service Routines

Overview

Service Routines A-Z

Service Routines by Function

Service Routines


Legacy Utilities

Legacy Utilities A-Z

Legacy Utilities by Function

Legacy Utilities


Special Functions and Variables

$EREF Special Variable

$PDISPLAY Special Variable

$WFONT Function

$WTFIT Function

$WTWIDTH Function


External Call Functions

External Calls A-Z

External Calls by Function

External Calls


External Access

Workstation as an Automation Controller

Workstation as an Automation Server

Issuing Windows Commands

Calling External Programs with XCalls

DDE Support


Devices

Using Peripheral Devices

Console Windows and MWAPI

Console Window User Interface Elements

Terminal Emulation Features of Console Window Devices


Switches and Settings

Startup switches

System Limits and Settings


GUI Reference

Modules

Windows

Menus

Toolbars

About Controls

Controls A-Z

About Properties and Attributes

Properties A-Z

About Events and Action Logic

Events A-Z

Additional Reference Information

Data Types


Format of $ZERROR

The $ZERROR special variable contains descriptive information about the most recent error. This information is also provided as a piece of the $ECODE special variable when the $ETRAP mechanism of error trapping is used. The format of this descriptive information is as follows.

<Code>Offset^RoutName:Cmnd:Arg:Major:Minor:AddInfo

Code is the error code; Offset is the location (relative line number or label+offset) within the routine; RoutName is the name of the routine; Cmnd is the relative number of the command in the line in error; Arg is the number of the argument within the command; Major and Minor are the MSM error numbers; and AddInfo contains additional information about the error.

The MSM system maintains the Cmd and Arg parameters only when the debugger is active. AddInfo is not maintained for all error types. For example, when a disk error (<DKHER>) occurs, AddInfo contains the block number that received the error.


MSM Error Codes

See also

The following table lists the error codes that are produced by the MSM system and describes how the errors are caused.

MSM Error Codes

Code	Explanation
<ASYNC>	An error occurred during the asynchronous processing of a previous SET or KILL operation on a remote volume group. This error is suppressed unless it is specifically allowed by a mode flag set through the SYSGEN or %MODESET utilities. The type of error is indicated in the additional information field of $ZERROR. This number is formed by major*256*+minor.
<BADCH>	An invalid character was encountered.
<BKERR>	The interpreter encountered a BREAK command while executing a program. The BREAK command is used primarily for program debugging and allows the user to inspect the program, local variables, and global variables at a specified location within the program. Program execution can be resumed using the ZGO command.
<CLOBR>	An attempt was made to overlay the current routine by issuing a ZLOAD, ZREMOVE, or ZINSERT command from within the routine.
<CMMND>	The interpreter encountered an illegal or undefined command.
<DDPER>	A Distributed Data Processing (DDP) error occurred.
<DIVER>	An attempt was made to divide a number by zero.
<DKFUL>	No space is available on the disk within the expansion limits of the current UCI. Information that the system was trying to write to the disk was lost. Database corruption can result.
<DKHER>	The MSM system encountered an unrecoverable error while trying to read from or write to a disk-type device. This is caused by a hardware malfunction or an attempt to reference a block that is outside the physical bounds of the disk.
<DKRES>	An attempt was made to allocate a block in the reserved area at the end of the user's expansion area because the expansion area is nearly full. If the AddInfo field in $ZERROR is 0, the operation was suppressed; if 1, the operation was completed.
<DKSER>	A block read in from the disk was not the type expected by the system or the block's internal structure was invalid. This can occur if the database is corrupted by a hard system failure such as a power failure, or a hardware malfunction such as an unrecoverable disk error on a write operation.
<DPARM>	Invalid use of parameter passing.
<DSCON>	The current device has been disconnected from the system.
<DSTDB>	A network communications link failed during a Distributed Data Processing (DDP) data transfer.
<ECODE>	An attempt was made to set $ECODE to an invalid value, or error processing was initiated by changing $ECODE from null to a valid value.
<EXPER>	An exponentiation error was detected.
<FUNCT>	The interpreter encountered an undefined function or a function that was used improperly.
<INDER>	The interpreter encountered illegal or incorrect use of the indirection operator.
<INHIB>	Access to a database through the network failed because database reads or writes are inhibited on the specified machine.
<INRPT>	The operating system received an interrupt (BREAK) from the terminal while the BREAK function was enabled (a BREAK 1 command was in effect).
<ISYNT>	An attempt was  made to insert an illegal line of text or code into the routine buffer. This can occur if the line of code is too long, the line label is invalid, or if the character separating the line label and the line body is incorrect. When an insert is performed in direct mode, the separator character must be a tab. If ZINSERT is used, the separator character must be one or more spaces or tabs.
<KLJOB>	The job was killed or interrupted by the KILLJOB utility.
<LCNSE>	The attempted operation would exceed the license limit.
<LINER>	A reference was made to a line that does not exist within the body of the routine.
<MAPER>	A disk block that is being freed is already marked free in the corresponding MAP block.
<MERGE>	A MERGE command was issued in which one operand is a descendant of the other operand.
<MINUS>	The interpreter found a negative number or zero when it expected a positive number.
<MODER>	An attempt was made to access the device in a mode that is not consistent with the parameters specified when the device was opened.
<MTERR>	An error occurred during an input or output operation to a magnetic tape device.
<MWAPI>	An error occurred while the M Windowing API was in use.
<MXMEM>	A memory address specified as an argument to the VIEW command or $VIEW function is outside the limits allowed by MSM.
<MXNUM>	The value of a number is greater than the largest number allowed by the system.
<MXSTR>	The value of string exceeds the maximum length allowed by the system. The maximum is 255 characters (or 511 as an option) for global variables, and 4092 characters for local variables.
Code	Explanation
<NAKED>	Access to a global variable using the naked indicator is invalid. This can occur if the naked indicator was not previously set by a global reference or if the previous global reference did not include subscripts.
<NMSPC>	A reference was made to an undefined mnemonicspace.
<NODEV>	The system intercepted an attempt by the program to OPEN a device that has not been defined to the system.
<NOJRN>	An attempt was made to journal a global in single-user mode.
<NOPEN>	The system intercepted an attempt by the program to USE a device that was not previously OPENed by the program.
<NOPGM>	A reference was made to a program that does not exist in the job's routine search path.
<NOSYS>	A reference was made to a non-existent system through Distributed Data Processing (DDP) or to a non-existent volume group through an extended global notation.
<NOUCI>	A reference was made to a non-existent UCI through an extended global notation.
<OBJCT>	An error occurred while an object reference was in use.
<PCERR>	The interpreter found an illegal post-conditional or the post-conditional argument is invalid.
<PGMOV>	There is insufficient memory in a partition to complete the requested operation.
<PLDER>	The routine that is being loaded has down-level p-code or does not have the correct type of p-code for a remote volume group executing a routine.
<PROT>	An attempt was made to access a protected global that the user is not authorized to access. This error also can occur if an attempt is made to save a program with a name that begins with a percent sign (%) in any UCI other than the Manager's UCI.
<SBSCR>	The subscript used in a local or global variable reference is invalid. This can occur if the subscript is null; the subscript contains the ASCII NULL character; the length of a subscript is greater than 255 characters; or the combined length of the global reference (global name, parentheses, subscripts, and commas) is greater than 255.
<SPOOL>	The MSM spooling area is full.
<STKOV>	The system stack overflowed as a result of nested indirection or a program loop, or the system expression stack overflowed while evaluating a complex expression or saving a large routine.
<SYNTX>	The interpreter encountered a syntax error in the line that is being executed.
<SYSTM>	The MSM system encountered an internal error. The exact error message, including major/minor error numbers, should be reported to Micronetics.
<TXPER>	A transaction processing error occurred.
<UNDEF>	The operating system intercepted an attempt to reference a non-existent local, global, or structured system variable or a non-existent object method or property.
<VWERR>	An attempt was made to access a device in shared VIEW buffer mode without ownership of the VIEW device (device 63). This error also occurs if the VIEW device is closed before the device that was opened in shared VIEW buffer mode.
<XCALL>	The function name specified on an external routine reference does not exist, or the parameters specified are invalid.
<ZSAVE>	One of the lines in the routine that is being compiled is too large to fit in the disk buffer. The line should be split into two or more lines to correct the problem.
<ZSVGP>	A ZSAVE command was issued, but the volume group was not enabled for any p-code type.
<Zxxxx>	A ZTRAP command was issued with "xxxx" as the argument.


MSG^%msc


MSM Error Numbers

See also

The following table lists the major and minor error numbers generated by MSM and describes how each error is caused.

MSM Error Numbers

Major	Minor	Explanation
1	-	Command type errors
	0	Unrecognized command
2	-	Argument type errors
	1	Missing parenthesis
	2	Missing or bad colon
	3	Missing or bad equals
	4	Missing or bad local variable
	5	Missing or bad global variable
	6	Missing or bad function
	7	Missing or bad routine name
	8	Missing or bad routine label
	9	Missing or bad routine offset
	10	Indirect argument error
	11	Argument condition error
	12	Bad argument delimiter
	13	Bad command
3	-	Expression type errors
	0	Bad special variable name
	1	Bad system function
	2	Bad local variable
	3	Bad global variable
	4	Bad string constant
	5	Bad numeric constant
	6	Unbalanced parenthesis
	7	Invalid syntax in term
	8	Bad operator
	9	Bad delimiter
4	-	Reference type errors
	0	Undefined local variable
	1	Undefined global variable
	2	Undefined label
	3	Undefined routine
	4	Invalid naked reference
	5	Non-existent device or no memory for window
	6	Unsubscripted local reference required
	7	Variable reference required (no expressions)
	8	ZLOAD usage error during routine execution
	9	Undefined UCI reference
	10	Attempted ZINSERT of an invalid line
	11	Unknown data type
	12	Missing function parameter
	13	Undefined system in cross-system reference
	14	Global access protection violation
	15	Volume group protection violation
	16	XCALL error
	17	Formal list not entered via DO command
	18	QUIT with argument inside FOR scope
	19	QUIT with argument, but routine not extrinsic
	20	Argumentless QUIT, but routine was extrinsic
	21	Extrinsic subroutine ended without Q parm
	22	Label requires a formal list
	23	Actual parms exceed parms in formal list
	24	Formal list parameter is subscripted variable
	25	Duplicate variable name in formal list
	26	Passing value by reference in JOB not allowed
	27	MERGE operand is descendant of other
	28	Nested mnemonic namespace request
	29	Undefined structured system variable
	30	FOR control variable was KILLed
	31	Unsupported OMI feature
	32	Object value is undefined
	33	Undefined object method or property
	34	VIEW restriction violation
	35	MWAPI reference to undefined element
	36	Required MWAPI attribute missing
	37	Mnemonicspace not in mnemonic list
	38	Undefined mnemonicspace
	39	Device does not support mnemonicspace
5	-	Value-type errors
	0	String exceeded maximum length
	1	$SELECT function error
	2	Divide by zero
	3	Negative number
	4	Maximum number
	5	Device not open
	6	Invalid memory address
	7	String value required
	8	Indirection resulted in null value
	9	Indirection included more than name
	10	Selected partition not active ($VIEW)
	11	Invalid VIEW or $VIEW argument
	12	Function parameter out of range
	13	Invalid subscript
	14	Device not open for access type attempted
	15	Invalid character
	16	Not allowed to write block 0
	17	Invalid use of shared mode on VIEW buffer
	18	Raised zero to non-positive power
	19	Raised negative number to non-integer power
	20	Invalid $ZBN usage
	21	Invalid $ECODE value
	22	Invalid $FNUMBER parameter
	23	Invalid $RANDOM parameter
	24	Invalid READ length
	25	Invalid $NAME parameter
	26	QUIT when $TLEVEL >0
	27	Invalid $X or $Y value
	28	Object reference required
	29	MSM spooling error
	30	Attempt to SET an object method
	31	Attempt to SET a read-only object property
	32	Error accessing object
	33	Invalid MWAPI attribute name
	34	Invalid MWAPI attribute value
	35	Invalid MWAPI focus
	36	Invalid MWAPI font parameter
	37	Invalid MWAPI window mode
	38	Invalid nested ESTART
	39	Character must be single byte
6	-	Environmental errors
	0	Break key pressed
	1	Attempt to exceed partition size
	2	HALT command executed
	3	LOCK table full
	4	BREAK command executed
	5	Expression stack overflow
	6	System stack overflow
	7	Old p-code needs to be saved
	8	Circuit error during DDP operation
	9	Reserved for DDP internal use
	10	DDP database access inhibited
	11	Reserved for future use
	12	I/O error on terminal operation
	13	I/O error on magnetic tape operation
	14	P-code too long to fit in one block
	15	ZQUIT error
	16	DDP circuit disabled
	17	ZTRAP command issued
	18	Expression stack overflow on READ command
	19	No p-code type for volume group on ZSAVE
	20	P-code type not available for this system
	21	Number of users exceeds license limit
	22	Asynchronous error on remote volume group
	23	Journal request in single-user mode
	24	Transaction processing error
	25	Routine is too large to load
	26	Host system is out of memory
	27	$ECODE has been SET
	28	Transaction is not restartable
	29	Job killed by KILLJOB
	30	ZSAVE license violation
	31	Socket license violation
	32	Window type is not MTERM
	33	KILL of open MTERM window
	34	ESTOP command executed
	35	TSTART nested too deeply
7	-	Disk-type errors
	0-32	Block type mismatch, number is expected type
	33	Hardware disk I/O error
	34	Database full condition
	35	Block number mismatch
	36	Key/data exceeds maximum length
	37	Cannot open requested database
	38	Block being freed is already free
	39	Invalid block number
	40	Attempt to allocate block in reserved area
	41	Block contains invalid key
	42	Block contains invalid data
	43	KILL found invalid key


MSG^%msc


$EC Error Codes

The following table lists the $ECODE errors generated by MSM and explains how the errors are caused.

$ECODE Errors

Code	Explanation	Equivalent $ZERROR value
M1	Naked indicator undefined	<NAKED>:::4:4
M2	Invalid "P" parameter in $FNUMBER	<SYNTX>:::5:22
M3	$RANDOM seed less than 1	<SYNTX>:::5:23
M4	No true condition in $SELECT	<SYNTX>:::5:1
M5	Line reference less than zero	<SYNTX>:::3:6
M6	Undefined local variable name	<UNDEF>:::4:0
M7	Undefined global variable name	<UNDEF>:::4:1
M8	Undefined subscripted system variable name	<UNDEF>:::4:29
M9	Divide by zero	<DIVER>:::5:2
M11	No parameters passed	<DPARM>:::4:17
M12	Negative offset in line reference	<LINER>:::2:8
M13	Line reference not found	<LINER>:::4:2
M15	Undefined index variable	<UNDEF>:::4:30
M16	QUIT argument not allowed	<DPARM>:::4:18
M17	QUIT argument required	<DPARM>:::4:20
M18	Fixed length READ not greater than zero	<SYNTX>:::5:24
M19	Cannot copy a tree or subtree into itself	<MERGE>:::4:27
M20	Formal argument list required	<DPARM>:::4:22
M26	Non-existent environment	<NOUCI>:::4:9
M27	Transaction is not restartable	<TXPER>:::6:28
M28	Mathematical function, parameter out of range	<DPARM>:::4:23
M35	Device does not support mnemonicspace	<NMSPC>:::4:39
M40	Call-by-reference in JOB actual	<DPARM>:::4:26
M42	Invalid QUIT within a TRANSACTION	<TXPER>:::5:26
M43	Invalid range value ($X,$Y)	<MINUS>:::5:27
M44	Invalid command outside of a TRANSACTION	<TXPER>:::6:24
M46	Invalid MWAPI attribute name	<MWAPI>:::5:33
M47	Invalid MWAPI attribute value	<MWAPI>:::5:34
M48	MWAPI object does not exist	<MWAPI>:::4:35
M49	Invalid MWAPI focus	<MWAPI>:::5:35
M50	Reference to non-MTERM window	<MWAPI>:::6:32
M51	KILL of open MTERM window	<MWAPI>:::6:33
M52	Required MWAPI attribute missing	<MWAPI>:::4:36
M53	Invalid MWAPI font parameter	<MWAPI>:::5:36
M54	Invalid MWAPI window mode	<MWAPI>:::5:37
M55	Invalid nested ESTART	<MWAPI>:::5:38
M58	Too many actual parameters	<DPARM>:::4:23


$ZOS Error Codes

The following table lists error codes that can be returned by the $ZOS function. The most commonly returned error codes in this table also are described with the $ZOS functions.

$ZOS Error Codes

Number	Description
-1	Invalid function
-2	File not found
-3	Path not found or invalid
-4	Too many open files
-5	Access denied
-6	Handle is invalid
-8	Insufficient memory
-11	Format invalid
-12	Access code invalid
-14	Unknown unit
-15	Disk drive invalid
-16	Attempt to remove the current directory
-17	Not same device
-18	No more files
-19	Disk write-protected
-20	Unit unknown
-21	Drive not ready
-23	CRC error
-24	Bad request structure length
-25	Seek error
-26	Unknown media type
-27	Sector not found
-29	Write fault
-30	Read fault
-31	General failure
-32	Sharing violation
-33	Lock violation
-80	File already exists
-82	Cannot make directory


%MERR Error Codes

See also

The following list of error codes that are returned in %MERR provides a description of each code.

Code	Description
BIJCLOSE	The system was unable to close the BIJ file.
BIJNOTOPEN	The system was unable to open the BIJ file.
BIJREAD	The system was unable to read the BIJ file.
BIJROLLB	The system was unable to rollback the BIJ.
BIJROLLF	The system was unable to roll forward the BIJ.
BIJUMNT	The system was unable to unmount the BIJ file.
BLKR	An error occurred while reading a block of data from the database.
BLKW	An error occurred while writing a block of data to the database.
DBMNT	The specified database is already mounted.
DISMNT	The system was unable to dismount the specified volume.
EXPMULT	An attempt to expand a multi-volume volume group was made.
EXPRVG	An attempt to expand a remote volume group was made.
EXPVOL0	An attempt to expand volume group number 0 was made.
HFS	An error occurred while accessing the host file system.
HOSTDBNAME	The system could not determine the host file name of the database.
HOSTMEM	The system was unable to allocate the required host memory.
MAXDB	An attempt was made to mount a database larger than the size permitted by the MSM-Workstation license.
MAXDBNUM	An attempt was made to open more volume groups than the number permitted by the MSM-Workstation license.
MNT	The system was unable to mount the specified volume.
MNTTYPE	The system could not determine how to mount the volume.
MONBND	The moniker specified is already bound.
MONFND	The moniker specified already exists in the moniker table.
MONNOTBND	The moniker specified is not bound.
MONNOTFND	The moniker specified cannot be found in the moniker table.
MONNOTREG	The moniker specified cannot be found in the registry/ini file.
NET	The system has encountered a network error.
NOACTCIR	No active network circuit.
NOVIEW	Execution of the view command is not allowed.
PARMI	The named parameter should be a positive integer, but is not.
PARMM	The named parameter that specifies a moniker has an invalid format.
PARMREQ	The named parameter is required but is missing.
PARMUV	The named parameter that specifies a UCI and VOL has an invalid format.
REGFMT	The MSM profile entry has an invalid format for the current operation.
STARTNET:101	The remote mount failed to locate the specified server.
STARTNET:21	The system failed to start a DDP circuit.
STARTNET:22	The system failed to start DDP.
STARTNET:23	The remote mount encountered a security failure.
STARTNET:3	The remote mount failed because the password was incorrect.
STARTNET:4	The remote mount failed to obtain a server partition.
STARTNET:52	The remote mount failed to access the specified UCI and VG.
TRANOVR	The translation table has overflowed.
UCINOTFND	The system was unable to find the specified UCI.
UVBIND	The system was unable to determine the UCI and VOL to bind to.
VBUSY	The View device is busy.
VGDUPNAM	An attempt was made to mount a volume with the same name as a mounted volume.
VGLBL	The volume group label is invalid.
VGMAX	The maximum number of volumes allowed has been exceeded.
VGMNTD	The specified volume group is already mounted.
VGNAME	The volume group name is invalid.
VGNOSLOT	No slot could be found for the volume in the volume group table.
VGNOTFND	The system was unable to find the specified volume group.
VGNOTMNTD	The specified volume group is not mounted.
VGNOTVOL0	An attempt was made to mount a volume other than volume 0 of a volume group.
VOLMAGIC	The specified volume magic number is inconsistent.
VOLMAP	The specified volume map is inconsistent.
VOLNAM	The specified volume name is inconsistent.
VOLNOTBP	The specified volume is not eligible for bullet-proofing.
VOLNUM	The specified volume number is inconsistent.


MSG^%msc


Macros - Overview
Overview

What are macros?

A macro is one of the many tools that are used in software development. Basically, a macro is an instruction to a pre-processor to replace some source code text with other text. The definition of a macro describes how text is to be replaced. Macros may take parameters, which are details filled in to the "blanks" left open in the definition of the macro.

The purpose of macros is generally to use a simple meaningful name for a constant value, a complex expression, or a piece of code that is repeated often.  Macros may also be used to assure that a single copy of a definition or source code section is maintained; to exploit the high efficiency that results from in-line expansion; or to offer a consistent interface to entities that have to be referenced in different fashions on different platforms.

Built-in macros are provided by MSM-Workstation to facilitate building GUI applications.  Customized macros may be defined in window and module CommonCode, as well as in M sources.

The built-in macros are available for use within window action logic, and a subset of them can be used in module action logic. To use them within your own source objects, add the following line to the top of your source:

#include ^%BLDT("AL")

Remember that some of the macros can only be used within specific action logic sections. They will not work when used within your own sources.

Processing

In the context of MSM-Workstation, the macros all have names that start with %% (two percent-signs).

Macros are processed in one of the first stages of compilation. Subsequent compilation steps do not "see" the original macros, but rather a modified version of the original source code in which all text-replacement instructions from macros have been applied. For more information about the preprocessor that performs this replacement, see the MSM Language Reference Manual.

Although it is often said that a macro "does something", in fact, a macro never "does anything". It merely causes code to be generated that performs the action in question.


Macro Parameter Domains

Macros are the primary means for run-time manipulations of windows, controls, and their properties.  For this reason macros frequently require a parameter that identifies an object or a property.  The following domains describe the format of such parameters.

See Also:

Object

ObjectProperty

ObjComponent


Object

Examples

Object ::=	[[WindowName].][ControlName] | [WindowName].Type.ItemID

WindowName ::=	literal | literal[Instance] | @variable

Instance ::=	intexpr

ControlName ::=	literal | @variable

Type ::=	T | TB | M

ItemID ::=	literal | @variable

This can specify a window, a control, or both. The syntax treats the omission of either the window or the control as an indication that the current window or control is to be used. The current window or control is defined as the owner of the action logic being executed. This is not necessarily the same as the window or control with focus. It may not be the same as the window or control which raised the current event, for example in the case when the %%Perform macro has been used.

Where a window-name is followed by an instance-number in square-brackets, this identifies the window-instance. The window with that instance-number must previously have been created with %%DoWin or %%OpenWin .

Object names are case-sensitive.

When the object includes the 'Type' attribute you are referring to a toolbar, toolbar button, menu choice, or the menu bar. The following table lists the values for Type:

Type	Refers to
T	Toolbar. The ItemID is the name that you associated with the toolbar in the toolbar definition dialog.
TB	Toolbar button. The ItemID is the Application ID that you have associated with the toolbar button in the definition dialog for this button. If there is more than one menu choice with this Application ID then when you get a property it will refer to the first menu choice it finds and when you set a property it will set the property on all of the matching buttons on this window.
M	Menu choice or menu bar. The ItemID is the Application ID you have associated with a menu choice. If the ItemID is null then it refers to the menu bar on the window. If there is more than one menu choice with this Application ID then a property-get will access the first match, and a property-set will apply to all matching menu choices on the window.


Object	Refers to
.	The current window, whether or not there is a current control
Button1	The control Button1 on the current window
Win1.	The window Win1
Child[2]	Instance 2 of the window Child
Win1.Button1	The control Button1 on window Win1
@whichctl	The control named in the variable whichctl, on the current window
@whichwin.	The window named in the variable whichwin
@whichwin.@whichctl	The control named in the variable whichctl, on the window named in the variable whichwin
Win1.@whichctl	The control named in the variable whichctl, on window Win1
@whichwin.Button1	The control Button1 on the window named in the variable whichwin
<null>	When allowed, the current control if there is one, otherwise the current window
.M.Menuitem	The menu choice/s with Application ID equal to Menuitem on the current window
Win1.M.	The menubar on the window Win1
Win1.T.@whichtbar	The toolbar named in the variable whichtbar on window Win1
.TB.Buttonname	The toolbar button/s with Application ID equal to Buttonname on the current window


ObjectProperty

ObjectProperty ::=	[ Object . ] [ PropertyName ]

PropertyName ::=	literal

This specifies a property associated with an object. Not all of the properties that can be manipulated at design-time using the Property Bar are accessible during run-time.

If the PropertyName is not specified, the default depends on the type of object as specified in Default Properties.

Property names are case-sensitive. MWAPI attribute-names, which are entirely upper-case, may be specified instead of property names


ObjComponent

ObjComponent ::=	Object | Object . E . Event | Object . C. Choice

Event ::= 	literal

Choice ::= 	literal

This is a variant of Object. It can also specify a window, a control, or both. In addition, it may also be used to indicate an event or choice.

Event is the name of an event applying to the object (control or window).

Choice is the internal identifier of a choice applying to the specified object (control).


Macros A-Z

Macro	Description
%%Black	A colorvalue
%%Blue	A colorvalue
%%Cancel	Exit and destroy or hide a window, optionally setting a return code and parameter array.
%%Clipboard	The contents of the Windows clipboard, if text.
%%CloseWin	Destroys a window.
%%CurrCtl	The name of the current control.
%%CurrWin	The runtime identifier of the current window.
%%CurrWinName	The build-time name of the current window.
%%Cyan	A colorvalue
%%DarkGray	A colorvalue
#%Declare	Create private local variables for a window.
%%Disable	Disable a window or control.
%%DisplayBackColor	Default background color for all windows.
%%Do	Invoke a window or module, passing it parameters and settings.
%%DoWin	Invoke a window, passing it parameters and settings.
%%Enable	Set the Active property of a window, a control, or a component (i.e. event or choice).
%%EnableMenu	Enable or disable choices on the menu structure of the current window.
%%Ev	Control-specific event parameters for an ActiveX control's custom events.
%%EvChoice	The choice associated with the current event.
%%EvControl	The control associated with the current event.
%%EvElement	The element associated with the current event.
%%EvKey	The keys that were depressed at the most recent event.
%%EvNext	The control that will next receive focus after the current event.
%%EvPrior	The control that had focus prior to the current event.
%%EvPtrButton	The mouse button that generated the current event.
%%EvPtrPos	The position of the mouse pointer.
%%EvPtrState	The mouse buttons that were pressed when the current event occurred.
%%EvSequence	The sequence number of the current event.
%%EvType	The type of the current event.
%%EvWindow	The run-time name of the window associated with the current event.
%%Focus	Get the name of the window and control having focus.
%%FocusCtl	Get the name of the control having focus.
%%FocusWin	Get the name of the window having focus.
%%Get	Get the value of the property of an object into a variable.
%%GetChoice	Get the choices that are available using a control such as a list or radio button set.
%%GetSel	Get the selection(s) made using a control that presents a list of alternatives such as a list or radio button set.
%%GetVar	Retrieve the value displayed in a control on the current window by referring to its local variable.
%%Gray	A colorvalue
%%Green	A colorvalue
%%Hide	Make a window or control invisible.
%%I	Returns an object reference for the current ActiveX control .
%%IOVar	Used to pass parameters to and from windows and modules.
%%IsOK	Indicate success during action logic.
%%IsOLEserver	Determine at startup whether an executable is an interactive application or a server.
%%KillCtl	Remove a component.
%%KillWin	Remove a window.
%%Magenta	A colorvalue
%%MarkMenu	Shows or hides the mneu marker-symbol defined at design-time for a menu item on the current window.
%%MDIArrangeIcons	Arrange the icons of the MDI child windows.
%%MDICascade	Cascade the MDI child windows.
%%MDIExtendMenu	Specify the menu to be used for enumerating the MDI child windows.
%%MDITileH	Tile the MDI child windows horizontally.
%%MDITileV	Tile the MDI child windows vertically.
%%MergeCtl	Add components to a window from an array.
%%MergeWin	Create a new window from an array.
%%MoveBehind	Move a window or control behind a specified window or control in the Z-order, or behind all others.
%%MoveFront	Move the window or control  to the front of the Z-order.
%%NotOK	Indicate failure during action logic.
%%OK	Check  success during action logic.
%%OpenWin	Load a window into memory.
%%Perform	Perform action logic associated with an object's event.
%%PopMenu	Displays a pop-up menu belonging to the current window and waits for user interaction.
%%Prop	Return the value of the property of an object.
%%Red	A colorvalue
%%Reset	Reset the value of a property of an object.
%%ResetChoice	Reset the choices of a control.
%%ResetSel	Reset the selections on a control.
%%ResetVar	Update  the value displayed in a control on the current window by referring to its local variable.
%%RetCancel	Return value indicating a window was canceled.
%%RetCode	Return code from a window.
%%RetNormal	Return value indicating a window terminated normally.
%%Return	Exit and close a window, optionally setting a return code and parameters array.
%%Set	Set the value of the property of an object.
%%SetChoice	Set the choices presented by a control such as a list or radio button set.
%%SetFocus	Set focus to a window or control.
%%SetSel	Set the selections value of the property of a control.
%%SetVar	Update the value displayed in a control on the curent window by referring its local variable.
%%Show	Make a window or control visible.
%%SqlConnect	Establish an MSM-SQL connection for use by SQL Data Controls
%%SqlDisconnect	Release an MSM-SQL connection
%%Trigger	Trigger  a low-level event, using the MWAPI command ETRIGGER.
%%White	A colorvalue
%%Yellow	A colorvalue


Macros by Function

Macros for Property Manipulation

Macros for Modules

Macros for Windows

Macros for MDI

Macros for Controls

Macros for Choices

Macros for Menus

Macros for Events

Macros for Colors

Macros for MSM-SQL

Macros for MWAPI


Macros for Property Manipulation

Macro	Description
%%Get	Get the value of the property of an object into a variable.
%%GetVar	Retrieve the value displayed in a control on the current window by referring to its local variable.
%%Prop	Return the value of the property of an object.
%%Reset	Reset the value of a property of an object.
%%ResetVar	Update the value displayed in a control on the current window by referring its local variable.
%%Set	Set the value of the property of an object.
%%SetVar	Update the value displayed in a control on the current window by referring its local variable.


Macros for Modules

Macro	Description
%%Do	Invoke a window or module, passing it parameters and settings.
%%IsOLEserver	Determine at startup whether an executable is an interactive application or a server.


Macros for Windows

Macro	Description
%%Cancel	Exit and destroy a window, optionally setting a return code and parameter array.
%%CloseWin	Destroys a window.
%%CurrWin	The runtime identifier of the current window.
%%CurrWinName	The build-time name of the current window.
%%Declare	Create private local variables for a window.
%%Disable	Disable a window or control.
%%DisplayBackColor	Default background color for all windows.
%%Do	Invoke a window or module, passing it parameters and settings.
%%DoWin	Invoke a window, passing it parameters and settings.
%%Enable	Set the Active property of a window, a control, or a component (i.e. event or choice).
%%Focus	Get the name of the window and control having focus.
%%FocusWin	Get the name of the window having focus.
%%Hide	Make a window or control invisible.
%%IOVar	Used to pass parameters to and from windows and modules.
%%IsOK	Indicate success during action logic.
%%MoveBehind	Move a window or control  behind a specified window or control in the Z-order, or behind all others.
%%MoveFront	Move a window or control to the front of the Z-order.
%%NotOK	Indicate failure during action logic.
%%OK	Check  success during action logic.
%%OpenWin	Load a window into memory.
%%RetCancel	Return value indicating a window was cancelled.
%%RetCode	Return code from a window.
%%RetNormal	Return value indicating a window terminated normally.
%%Return	Exit and close a window, optionally set a return code and parameters array.
%%SetFocus	Set focus to a window or control.
%%Show	Make a window or control visible.


Macros for MDI

Macro	Description
%%MDIArrangeIcons	Arrange the icons of the MDI child windows.
%%MDICascade	Cascade the MDI child windows.
%%MDIExtendMenu	Specify the menu to be used for enumerating the MDI child windows.
%%MDITileH	Tile the MDI child windows horizontally.
%%MDITileV	Tile the MDI child windows vertically.


Macros for Controls

Macro	Description
%%Clipboard	The contents of the Windows clipboard, if text.
%%CurrCtl	The name of the current control.
%%Disable	Disable a window or control.
%%Enable	Set the Active property of a window, a control, or a component (i.e. event or choice).
%%Focus	Get the name of the window and control having focus.
%%FocusCtl	Get the name of the control having focus.
%%Hide	Make a window or control invisible.
%%I	Returns an object-reference to the current ActiveX control.
%%MoveBehind	Move a window or control  behind a specified window or control in the Z-order, or behind all others.
%%MoveFront	Move a  window or control to the front of the Z-order.
%%SetFocus	Set focus to a window or control.
%%Show	Make a window or control visible.


Macros for Choices

Macro	Description
%%GetChoice	Get the choices that are available using a control such as a list or radio button set.
%%GetSel	Get the selection(s) made using a control which presents a list of alternatives such as a list or radio button set.
%%ResetChoice	Reset the choices of a control.
%%ResetSel	Reset the selections on a control.
%%SetChoice	Set the choices presented by a control such as a list or radio button set.
%%SetSel	Set the selections value of the property of a control.


Macros for Menus

Macro	Description
%%EnableMenu	Enables or diasbles choices on the menu structure of the current window.
%%MarkMenu	Shows or hides the menu marker-symbol defined at design-time for a menu item on the current window.
%%PopMenu	Displays a pop-up menu belonging to the current window and waits for user interaction.


Macros for Events

Macro	Description
%%Ev	Control-specific event parameters for an ActiveX control's custom events.
%%EvChoice	The current choice associated with the current event.
%%EvControl	The control associated with the current event.
%%EvElement	The element associated with the current event.
%%EvKey	The keys that were depressed at the most recent event.
%%EvNext	The control that will next receive focus after the current event.
%%EvPrior	The control that had focus prior to the current event.
%%EvPtrButton	The mouse button that generated the current event.
%%EvPtrPos	The position of the mouse pointer.
%%EvPtrState	The mouse buttons that were pressed when the current event occurred
%%EvSequence	The sequence number of the current event.
%%EvType	The type of the current event.
%%EvWindow	The run-time name of the window associated with the current event.
%%Perform	Perform action logic associated with an object's event.
%%Trigger	Trigger a low-level event, using the MWAPI command ETRIGGER.


Macros for Colors

Macro	Description
%%Black	A colorvalue
%%Blue	A colorvalue
%%Cyan	A colorvalue
%%DarkGray	A colorvalue
%%Gray	A colorvalue
%%Green	A colorvalue
%%Magenta	A colorvalue
%%Red	A colorvalue
%%White	A colorvalue
%%Yellow	A colorvalue


Macros for MSM-SQL

Macro	Description
%%SqlConnect	Establish an MSM-SQL connection for use by SQL Data controls.
%%SqlDisconnect	Release an MSM-SQL connection.


Macros for MWAPI

Macro	Description
%%KillCtl	Remove a component.
%%KillWin	Remove a window.
%%MergeCtl	Add components to a window from an array.
%%MergeWin	Create a new window from an array.


Macros - Macros
Macros

%%Black

%%Blue

%%Cancel

%%Clipboard

%%CloseWin

%%CurrCtl

%%CurrWin

%%CurrWinName

%%Cyan

%%DarkGray

#%Declare

%%Disable

%%DisplayBackColor

%%Do

%%DoWin

%%Enable

%%EnableMenu

%%Ev

%%EvChoice

%%EvControl

%%EvElement

%%EvKey

%%EvNext

%%EvPrior

%%EvPtrButton

%%EvPtrPos

%%EvPtrState

%%EvSequence

%%EvType

%%EvWindow

%%Focus

%%FocusCtl

%%FocusWin

%%Get

%%GetChoice

%%GetSel

%%GetVar

%%Gray

%%Green

%%Hide

%%I

%%IOVar

%%IsOK

%%IsOLEserver

%%KillCtl

%%KillWin

%%Magenta

%%MarkMenu

%%MDIArrangeIcons

%%MDICascade

%%MDIExtendMenu

%%MDITileH

%%MDITileV

%%MergeCtl

%%MergeWin

%%MoveBehind

%%MoveFront

%%NotOK

%%OK

%%OpenWin

%%Perform

%%PopMenu

%%Prop

%%Red

%%Reset

%%ResetChoice

%%ResetSel

%%ResetVar

%%RetCancel

%%RetCode

%%RetNormal

%%Return

%%Set

%%SetChoice

%%SetFocus

%%SetSel

%%SetVar

%%Show

%%SqlConnect

%%SqlDisconnect

%%Trigger

%%White

%%Yellow


%%Black

Examples	See also

Basic colors are available through macros.


The following examples assume that myColor is set to the color of interest.  For instance, if using black:

S myColor=%%Black

Define the default background color for new components in the current window to be myColor. (by default, components inherit their background color from the window; when a component defines its own settings, this definition will not affect the component in question):

%%Set(..BackColor,myColor)

Define the default foreground color (color of texts) for all new components in the current window to be myColor (by default, components inherit their foreground color from the window; when a component defines its own settings, this definition will not affect the component in question):

%%Set(..ForeColor,myColor)

Define the color of the background of the area in the current window that is reserved for displaying any Multiple Document Interface (MDI) child windows to be myColor:

%%Set(..AreaColor,myColor)

Define the background color of the current window to be myColor:

%%Set(..Color,myColor)

Define the background color for value of the current component to be myColor:

%%Set(BackColor,myColor)

Define the foreground color (color of texts) for the value of the current component to be myColor:

%%Set(%%CurrCtl.ForeColor,myColor)

Define the background color for the label (title) of the current component to be myColor:

%%Set(%%CurrCtl.TBackColor,myColor)

Define the foreground color (color of texts) for the label (title) of current component to be myColor:

%%Set(%%CurrCtl.TForeColor,myColor)


%%Blue	%%Cyan	%%DarkGray	%%Gray
%%Green	%%Magenta	%%Red	%%White
%%Yellow


%%Blue

Examples	See also

Basic colors are made available through macros.


%%Black	%%Cyan	%%DarkGray	%%Gray
%%Green	%%Magenta	%%Red	%%White
%%Yellow


%%Cancel

Examples	See also

Exit and destroy or hide a window, optionally setting a return code and parameter array.

Syntax

%%Cancel ( [ ReturnCode ] [ , [ Parameters ] [ , Hide ] ] )

Definition

Parameter	Description
ReturnCode	A value indicating how the window was exited. The default is %%RetCancel. The value of ReturnCode can be accessed using %%RetCode.
Parameters	Expression, or M local variable name.
Hide	An expression which, if true, causes the window to be hidden but not destroyed. Default is false.
%%Cancel is typically used to return from a window started with %%Do or %%DoWin. The window is closed and destroyed. A ReturnCode is passed back to the issuer of the %%Do or %%DoWin, where it can be inspected using %%RetCode. The default value for ReturnCode is %%RetCancel, which is the only indication that a %%Cancel has been performed rather than a %%Return. This value may be overridden.

If Parameters names a local variable, it will be MERGEd into any variable specified as the parameter Parameters in the corresponding macro %%DoWin or %%OpenWin. If Parameters is an expression, its result will be SET into that variable. Using this mechanism, it is possible to return values to the calling environment with ease.

If Hide is true, the window is hidden but not destroyed. This allows faster future reuse through bypassing the need for subsequent creation. %%CloseWin should be used at the point where the window is no longer required.

For closing the current window, use %%Cancel and %%Return.

Use %%CloseWin to close other windows, such as non-modal ones that were opened using %%OpenWin, or modal ones that used the option Hide when a %%Cancel or %%Return was executed.

%%KillWin should only be used for MWAPI windows that were created directly at runtime, e.g. by directly merging structures into ^$Window, or by using %%MergeWin.


Without parameters, the macro causes the removal of the current window, and causes no special parameters to be returned. The exit-status in %%RetCode will be %%RetCancel:

%%Cancel

When the second parameter is present, the contents of the array named in this parameter will be merged into the parameter-array that was specified when the window was invoked:

%%Cancel(,temp)


%%KillWin	%%Return


%%Clipboard

Examples

The contents of the Windows clipboard, if text.

Syntax

%%Clipboard

Definition

%%Clipboard may be used to set text to the Windows clipboard or retrieve text it.


Reverse any string found on the Windows clipboard:

S %%Clipboard=$REV(%%Clipboard)


%%CloseWin

Examples	See also

Destroys a window.

Syntax

%%CloseWin ( WinName )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a window. In either case the window name may optionally include an instance-suffix in square-brackets. If this is absent, instance 0 is implied.
%%CloseWin performs any Destroy action logic, first for all components and then for the window, and then destroys the window. It should be used when a window created by %%OpenWin is no longer required, allowing the Destroy events to close data controls and perform other necessary cleanup.

Use %%CloseWin to close other windows, such as non-modal ones that were opened using %%OpenWin, or modal ones that used the option Hide when a %%Cancel or %%Return was executed.

For closing the current window, use %%Cancel and %%Return.

%%KillWin should only be used for MWAPI windows that were created directly at runtime, e.g. by directly merging structures into ^$Window, or by using %%MergeWin.


Close the window called "Test":

%%CloseWin(Test)

Close the window identified by the value of local variable which:

%%CloseWin(@which)


%%OpenWin


%%CurrCtl

Examples	See also

The name of the current control.

Syntax

%%CurrCtl

Definition

The macros %%CurrWin and %%CurrCtl are used to identify the window and component for which action logic is being executed.

%%CurrCtl is replaced by an expression that returns the name of the component in question.

Note: The control that currently has focus is not necessarily the same as the "current control". Typically the two are the same, but not always. For instance, while an object is being created, it is the "current" object, but it doesn't have focus.

The defaulting capabilities in many macro parameters reduce the need to refer explicitly to the current control.


Define the value of the current control using a macro:

%%Set(@%%CurrWin.@%%CurrCtl.Value,"Cherry Tree")

Define the value of the current control using a macro, exploiting defaults:

%%Set(Value,"Cherry Tree")

Define the value of the current control using the MWAPI directly:

S ^$W(%%CurrWin,"G",%%CurrCtl,"VALUE")="Cherry Tree"


%%CurrWin	%%Focus	%%FocusCtl	%%FocusWin
%%SetFocus


%%CurrWin

Examples	See also

The runtime identifier of the current window.

Syntax

%%CurrWin

Definition

The macros %%CurrWin and %%CurrCtl are used to identify the window and component for which action logic is being executed.

%%CurrWin is replaced by an expression that returns the runtime identifier of the window in question.

The defaulting capabilities in many macro parameters reduce the need to refer explicitly to the current control.


Set the title of a window to a specific value using a macro:

%%Set(@%%CurrWin..Title,"Text")

Set the title of a window to a specific value using a macro, exploiting defaults:

%%Set(..Title,"Text")

Set the title of a window to a specific value using the MWAPI directly:

S ^$W(%%CurrWin,"TITLE")="Text"


%%CurrCtl	%%CurrWinName	%%Focus	%%FocusCtl
%%FocusWin	%%SetFocus


%%CurrWinName

See also

The build-time name of the current window.

Syntax

%%CurrWinName

Definition

%%CurrWinName is replaced by an expression that returns the build-time name of the window in question.


%%CurrWin


%%Cyan

Examples	See also

The color "cyan" is better known as "light blue".

Basic colors are made available through macros.


%%Black	%%Blue	%%DarkGray	%%Gray
%%Green	%%Magenta	%%Red	%%White
%%Yellow


%%DarkGray

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%Gray
%%Green	%%Magenta	%%Red	%%White
%%Yellow


#%Declare

Examples

Create private local variables for a window.

Syntax

#%Declare VariableName[,InitialValue]

Definition

Nominates a local variable to provide instance-specific private storage for a window. Can only be used in the CommonCode section of a window.

MSM-Workstation allows you to associate an M local variable with certain types of control, such as the TextBox. This is done by setting the VarName property at design-time, or using the field on the definition dialog. So long as the VarPermanent property is set to No (the Permanent checkbox on the dialog should be clear), then this variable is private to each instance of the window. You can work with the variable directly, but if you use %%SetVar and %%GetVar you set and fetch the value of the control as well.

Such variables are particularly important when developing MDI applications, where multiple instances of the same window can be open concurrently. Sometimes such an instance-variable is needed that does not relate to any control. Use this macro at the top of the CommonCode section for a window. The alternative #%-macro syntax is recommended instead of the %%-syntax, because it makes code clearer to read.

Data in these variables including at subscripted levels, will all be kept private to each instance of the window.

Management of these variables relies on MSM-Workstation detecting when you enter or leave the window context. So it is essential that you don't set ^$DI($PD,"FOCUS") directly. If you need to transfer focus under program control, use only the %%SetFocus macro.


The CommonCode section of a MDI Child window contains:

#%Declare	MyVar

#%Declare	Flag,1

#%Declare	Created,$P($H,",",2)

Each instance of the window will have private M locals MyVar,Flag and Created. MyVar will be initialized to "", Flag to 1, and Created will contain the time when the window instance was created.


%%Disable

Examples	See also

Disable a window or control.

Syntax

%%Disable ( ObjComponent )

Definition

Parameter	Description
ObjComponent	The window or control to be disabled. Default is the current control if any, otherwise the current window. May also specify the event or choice to be disabled.
%%Disable is used to deactivate a window or control, preventing it from receiving focus and user input. Using the extended form of ObjComponent it can also disable a specified event, or in the case of a control with choices, a specific choice.

This command is equivalent to the following.

%%Enable(ObjComponent,0)


Deactivate the control called "Button1" on the window called "Win1":

%%Disable(Win1.Button1)

Block the high-level event Choose on the current window or component:

%%Disable(.E.Choose)

Disable the choice with the internal identifier "1" on the control called "Radio1"

%%Disable(Radio1:C.1)


%%Enable	%%EnableMenu


%%DisplayBackColor

Examples

Default background color for all windows.

Syntax

%%DisplayBackColor

Definition

This macro is replaced by an expression that returns the value for the default background color for all windows.

Note: While it is possible to specify specific colors for all parts and attributes of windows, it is typically not a good idea to use this capability.  The operating environment typically allows the end-users to define their color preferences, and end-users experience software that does not follow their established preferences as "hostile". Using the defaults that are established by the end-users typically increases the acceptance level of the software as a whole.  As a result, anticipated manipulation of this property is only in the context of "Preference Setting" dialog windows.


Copy the value of the background color (red, green and blue components) into local variable bgnd:

S bgnd=%%DisplayBackColor


%%Do

Examples	See also

Invoke a window or module, passing it parameters and settings.

Syntax

%%Do ( Name [ , Parameters [ , Settings ] ] )

Definition

Parameter	Description
Name	A string literal (without quotes) representing the name of a window or module, or an at-sign followed by the name of a local variable (@name) where the value of that variable matches the name of a window or module.
Parameters	Either an expression or a period, followed by the name of an M local variable (similar to an array passed "by reference" to a subroutine or function). When the name of an array is specified, this array can contain both input and output variables stored in named subnodes. Within the called window the array is accessed using %%IOVar. Any structure may be manipulated in this array.
Settings	An expression or array containing properties and settings which will override property settings already in the window. This is the only way to alter at run-time certain MWAPI attributes which cannot be changed once a window has been created.
Settings

Settings may be formatted according to one of these alternatives:

Format	Description
Parent	If Settings is an expression not containing a "=", it indicates the name of the window that is to be parent of the new window.
Property List	Settings may specify multiple properties using the format:      Property=Value|Property=Value|...
Array	Settings may be a period, followed by the name of an M local variable (similar to an array passed "by reference" to a subroutine or function). When this is the case, the parameter is assumed to be an array containing the specifications. The subscripts are names of properties, the values of the array elements are the corresponding property values. When this format is being used, properties of components can be defined as well as properties the window. If properties of components are to be specified, the value of the first subscript in the array must be the constant "C", the second subscript must be the name of the component, and the third subscript must be the name of the MWAPI attribute that corresponds to the property (reminder: names of properties look like "DefaultButton"; names of MWAPI attributes look like "DEFBUTTON"). Within the called window the array may be accessed using %%Settings, although this is not normally necessary.
When the parameter Settings corresponds to either of the first two formats, an array that corresponds to the third format will be constructed.

Note: The only Workstation property names recognized within Settings are PosRecall, SizeRecall, PosJustifyV and PosJustifyH. Other than these, valid MWAPI attribute names should be used, with values in the corresponding format. For example, use the DEFBUTTON attribute name rather than the DefaultButton property name.

%%Do looks for a module named Name, and if one is not found it then looks for a window named Name. In this way a window may evolve into a module without the invocation of the window needing to change.

When a window is invoked, the window is created if necessary and made visible; focus is set to the starting control if any. Events are processed until action logic executes a %%Return or %%Cancel.

When a module is called using %%Do its Enter action logic is performed. When the Enter logic quits the Exit action logic is performed, unless %%NotOK has been executed.


Invoke the module or window named in the local variable Name.  In this case, the third parameter specifies that the current window is the parent of the invoked window:

%%Do(@Name,,%%CurrWin)

Create a parameter to be input into a window in array element P("Pattern") (presumably a pattern to be matched by candidate file names).  Call a window named "GetFile" (presumably to ask for the name of a file).  Do something if a value (presumably a file name) was returned in array element P("File"):

S P("Pattern")="*.TXT"

%%Do(GetFile,.P)

I $D(P("File")) Do ...

Invoke a window called "Palette", send and return parameters in the array P().  In this case, the third parameter specifies that the current window is the parent of the invoked window:

%%Do(Palette,.P,%%CurrWin)


%%Cancel	%%DoWin	%%OpenWin	%%Return


%%DoWin

Examples	See also

Invoke a window, passing it parameters and settings.

Syntax

%%DoWin ( WinName [ , Parameters [ , Settings ] ] )

Definition

Parameter	Description
Name	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names a window. In either case the window name may optionally include an instance-suffix in square-brackets. If this is absent, instance 0 is implied.
Parameters	Either an expression or a period, followed by the name of an M local variable (similar to an array passed "by reference" to a subroutine or function). When the name of an array is specified, this array can contain both input and output variables stored in named subnodes. Within the called window the array is accessed using %%IOVar. Any structure may be manipulated in this array.
Settings	An expression or array containing properties and settings which will override property settings already in the window. This is the only way to alter at run-time certain MWAPI attributes which cannot be changed once a window has been created.
Settings

Settings may be formatted according to one of these alternatives:

Format	Description
Parent	If Settings is an expression not containing a "=", it indicates the name of the parent of the window
Property List	Settings may specify multiple properties using the format:      Property=Value|Property=Value|...
Array	Settings may be a period, followed by the name of an M local variable (similar to an array passed "by reference" to a subroutine or function). When this is the case, the parameter is assumed to be an array containing the specifications. The subscripts are names of properties, the values of the array elements are the corresponding property values. When this format is being used, properties of components can be defined as well as properties the window. If properties of components are to be specified, the value of the first subscript in the array must be the constant "C", the second subscript must be the name of the component, and the third subscript must be the name of the MWAPI attribute that corresponds to the property (reminder: names of properties look like "DefaultButton"; names of MWAPI attributes look like "DEFBUTTON"). Within the called window the array may be accessed using %%Settings, although this is not normally necessary.
When the parameter Settings corresponds to either of the first two formats, an array that corresponds to the third format will be constructed.

Note: The only Workstation property names recognized within Settings are PosRecall, SizeRecall, PosJustifyV and PosJustifyH. Other than these, valid MWAPI attribute names should be used, with values in the corresponding format. For example, use the DEFBUTTON attribute name rather than the DefaultButton property name.

%%DoWin creates the window if necessary, makes it visible, sets the focus to the starting control, if any, and executes the window by calling its compiled window program.

When %%DoWin (or %%Do) is used to start a window as a result of an event (for example, user selection of a menu choice), the new window is required to be application-modal. This setting is established automatically. The exception is the initial window typically started by %%Do or %%DoWin in application Enter logic. That window's modality is as defined by its Modal property.

The window need not have first been loaded or opened - %%DoWin includes %%OpenWin. If a window is preloaded invisible using %%OpenWin, or remains in existence but hidden after a previous call, the initial delay of %%DoWin can be reduced. However, if the existing window's modality is not correct it will be destroyed and recreated, at the cost of any anticipated performance benefit.


Invoke the window called "WinName".  In this case, the third parameter specifies that the current window is the parent of the invoked window:

%%DoWin(WinName,,%%CurrWin)

Invoke the window called "Edit", send and return parameters in the array P(), use indicated settings for the window properties:

%%DoWin(Edit,.P,"PARENT=%%CurrWin|COLOR=%%Cyan|PosRecall=0|PosJustifyH=C|PosJustifyV=C")

Invoke the window called "Edit", send and return parameters in the array P(), use Indicated settings from the array Settings. In addition to the previous example, several attributes of a component are defined in this case:

K Settings

S Settings("PARENT")=%%CurrWin

S Settings("COLOR")=%%Cyan

S Settings("POS")="5,20"

S Settings("C","TextBox1","VALUE")="Sample value"

S Settings("C","TextBox1","FCOLOR")=%%Red

%%DoWin(Edit,.P,.Settings)

Invoke the window identified by variable EDIT, use the array P() for parameters, get settings out of the array PROP():

%%DoWin(@EDIT,.P,.PROP)


%%Cancel	%%Do	%%OpenWin	%%Return


%%Enable

Examples	See also

Set the Active property of a window, a control, or a component (i.e. event or choice).

Syntax

%%Enable ( ObjComponent [ , Value ] )

Definition

Parameter	Description
ObjComponent	The window or control to be enabled. Default is the current control if any, otherwise the current window. May also specify the event or choice to be enabled.
Value	An expression that evaluates to true to enable, false to disable. The default is true.
The %%Enable macro is used to activate a window or control, enabling it to receive focus and user input. Using the extended form of ObjComponent it can also enable a specified event, or in the case of a control with choices, a specified choice.


Activate the control called "Button1" on the window called "Win1":

%%Enable(Win1.Button1)

Activate the current control:

%%Enable

Enable control called "CName" on the current window:

%%Enable(CName)

Enable the window called "Wname":

%%Enable(WName.)

Enable the high-level event  on the control called "Picture":

%%Enable(Picture.E.Enter)

Enable or disable the choice with the internal identification "1" on the control called "Radio1", depending on whether or not variable firstone has a true value (true is enable and false is disable):

%%Enable(Radio1.C.1,firstone)


%%Disable	%%EnableMenu


%%EnableMenu

Examples	See also

Enable or disable choices on the menu structure of the current window.

Syntax

%%EnableMenu ( AppId [ , Value ] )

Definition

Parameter	Description
AppId	The Application identification of the menu choice to be enabled. If there is more than one menu choice matching the identification, all are affected. If AppId takes the form @var then the matching occurs at run-time. Otherwise it occurs at compile-time, when multiple-matches give rise to a warning and non-match causes a compilation error. The default value is the menu choice whose action logic this macro is placed in.
Value	An expression that evaluates to true to enable, false to disable. The default is true.
%%EnableMenu is used to activate or disable choices on the menu structure of the current window, allowing them to be selected or graying them out.

This command is equivalent to the following %%Set macro.

%%Set(.M.AppID.Active,yn)


Activate the menu choice with application identification "Edit:Cut" on the current window:

%%EnableMenu(Edit:Cut)

Enable or disable the menu choice with the application identification matching the value of variable which, depending on whether or not variable yn has a true value (true means enable, false means disable):

%%EnableMenu(@which,yn)


%%MarkMenu	%%PopMenu	%%Set


%%Ev

Examples	See also

Control-specific event parameters for an ActiveX control's custom events.

Syntax

%%Ev ( Parameter )

Definition

Parameter	Description
Parameter	The name of the event parameter, without quotes.
When a custom event occurs for an ActiveX control, the control may provide event-specific information as parameters. Where these parameters are of a type compatible with MSM-Workstation, they are made available to action logic in an array accessed using the %%Ev macro. Subscripts correspond to the parameter names given by the control.

Use the macro to obtain parameter values. Where the control accepts return values in a parameter, assign the desired value using the macro. In the case of some controls' parameters, KILLing the parameter may act as a signal to the control.

Under some conditions, MSM-Workstation is unable to process a custom event synchronously. When this happens, processing is deferred and alterations to parameters cannot be communicated back to the control.

Note: This macro is only available within action logic for custom events of ActiveX controls.


Retrieve the value of the Dimension parameter for the current ActiveX control custom event:

S dim=%%Ev(Dimension)

Return a random integer between 0 an 99 in the Seed parameter for the current ActiveX control custom event:

S %%Ev(Seed)=$R(100)


%%I


%%EvChoice

Examples	See also

The choice associated with the current event.

Definition

During action logic initiated by a low-level select or deselect event, this macro returns the internal identifier of the associated choice.  It is equivalent to ^$Event("CHOICE").

Note: in the context of a select event, this choice is the newly selected item; in the context of a deselect event, this choice is the item that was previously selected and is now de-selected.


Assume that this example has to do with a list that contains names of colors, and that, when a color is selected, a sample window is popped up with an application specific demonstration for that color.

For a "select" event, appropriate code would be:

Set window="Demo"_%%EvChoice %%OpenWin(@window)

and the counterpart for "deselect" would be:

Set window="Demo"_%%EvChoice %%CloseWin(@window)


%%EvControl	%%EvElement	%%EvKey	%%EvNext
%%EvPrior	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvControl

Examples	See also

The control associated with the current event.

Definition

The name of the control which caused the current event.  It is equivalent to $PIECE(^$Event("ELEMENT"),",",2).

Within the event's action logic this will be the same as %%CurrCtl.


Fetch the value of the component for which the current event was triggered:

S value=%%Prop(@%%EvControl.Value)

Change the color of the foreground (text) in the event's control to red:

%%Set(@%%EvControl.ForeColor,%%Red)


%%EvChoice	%%EvElement	%%EvKey	%%EvNext
%%EvPrior	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvElement

See also

The element associated with the current event.

Definition

Identifies the type and name of the element associated with the most recent event. It is equivalent to ^$Event("ELEMENT").

An element, in this context, is a comma-delimited pair of a type and a name. Valid types are "G" (gadget), "M" (menu), "TB" (toolbar) and "T" (timer).


%%EvChoice	%%EvControl	%%EvKey	%%EvNext
%%EvPrior	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvKey

Examples	See also

The keys that were depressed at the most recent event.

Definition

During action logic initiated by the low-level events char, keyDown and keyUp, returns the keycode for the keys associated with the event.  It is equivalent to ^$Event("KEY").

When keys are struck on the keyboard while focus is on an object capable of causing these events, multiple events are triggered. For each key, there is at least a keyDown and a keyUp. When the combination of the key and the modifier keys represents a valid character, there will also be a char event.

In the context of the events keyDown and keyUp, the value in %%EvKey will be the descriptive text, e.g. "SHIFT+A", or "A", or "ESC". In the context of the char event , the value reported will be string-value that represents the character in question, e.g. "A", "a" or $Char(27) in the same cases as above.

The special function keys are:

ESC	F1	F2	F3	F4
F5	F6	F7	F8	F9
F10	F12	BACKSPC	SCRLLCK	PAUSE
TAB	ENTER	INS	HOME	PAGEUP
PAGEDOWN	END	DEL	UP	LEFT
RIGHT	DOWN	NUMLOCK	NUMDIV	NUMMULT
NUMMINUS	NUMPLUS	NUM0	NUM1	NUM2
NUM3	NUM4	NUM5	NUM6	NUM7
NUM8	NUM9	NUMENTER	NUMDEC.
The Print Screen key is reported as "Z44". Its "key down" event is intercepted by Windows, and only a keyUp will be "seen" by MSM-Workstation.

The modifier keys are: "ALT", "CTRL", "SHIFT".

Note: When one of the components of a window is a "default button", pressing Enter will not cause a "character oriented" event. Instead, focus moves to the default button, which is then pushed. Appropriate events occur. Similarly, the ESC key navigates to the cancel button and presses it, if one is defined.


Recognize the "enter" key in the context of one of the events keyDown or keyUp:

If %%EvKey="ENTER" Do ...

Recognize the "enter" key in the context of a char event:

If %%EvKey=$Char(13) Do ...


%%EvChoice	%%EvControl	%%EvElement	%%EvNext
%%EvPrior	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvNext

Examples	See also

The control that will next receive focus after the current event.

Definition

During action logic initiated by a low-level change or lostFocus event, identifies the window and control to which focus is moving.  It is equivalent to ^$Event("NEXTFOCUS").

Typically, one doesn't worry too much about the sequence in which the end-user traverses the various components in a window. When a control should not be "reachable", it will typically be "greyed out", and when accessing controls involves executing action logic, code should be executed to check whether all required fields have an appropriate value, and use relevant default values for those fields that have not been defined yet.

This macro may be useful in those occasions where it does matter in which order the various components are traversed.


Assume that the window represents a chess-board, and that the squares on the chess-board are represented by controls with names like "c11", "c12", through "c88".

S from=%%EvControl,to=$P(%%EvNext,",",2)

S hor=$E(to,2)-$E(from,2)

S ver=$E(to,3)-$E(from,3)

I ".ab.ba."[$TR("."_hor_ver_".","12-","ab")

would validate that the move being requested is a valid one for a knight in the game of chess.


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvPrior	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvPrior

Examples	See also

The control that had focus prior to the current event.

Definition

During action logic initiated by a low-level gotFocus event, identifies the window and control from which focus moved. It is equivalent to ^$Event("PRIORFOCUS").

Typically, one doesn't worry too much about the sequence in which the end-user traverses the various components in a window. When a control should not be "reachable", it will typically be "greyed out", and when accessing controls involves executing action logic, code should be executed to check whether all required fields have an appropriate value, and use relevant default values for those fields that have not been defined yet.

This macro may be useful in those occasions where it does matter in which order the various components are traversed.


Assume that the window represents a chess-board, and that the squares on the chess-board are represented by controls with names like "c11", "c12", through "c88".

S to=%%EvControl,from=$P(%%EvPrior,",",2)

S hor=$e(to,2)-$e(from,2)

S ver=$e(to,3)-$e(from,3)

I ".ab.ba."[$tr("."_hor_ver_".","12-","ab")

would validate that the move taken was a valid one for a knight in the game of chess.


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPtrButton	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvPtrButton

Examples	See also

The mouse button that generated the current event.

Definition

During action logic initiated by low-level click, dblClick, ptrDown, ptrDrag or ptrUp events, returns the buttoncode causing the event.  It is equivalent to ^$Event("PBUTTON").

PB1 is the primary button, normally the left one. PB3 is the secondary, normally the right. The modifiers ALT, CTRL and SHIFT may be prefixed on these values.


Assume that the code in the following examples occurs in the action logic for the event ptrUp.

Catch the relevant parameter of the event:

S button=%%EvPtrButton

In case the left-button was pressed and released, do xxx:

I button="PB1" D xxx Q

In case the right-button was pressed and released, pop up the menu for the current object :

I button="PB3" %%PopMenu(MenuForDemo) Q


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrPos	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvPtrPos

Examples	See also

The position of the mouse pointer.

Definition

During action logic initiated by low-level click, dblClick, ptrDown, ptrDrag, ptrMove or ptrUp events, returns the position of the pointer (the mouse) when the event occurred.  It is equivalent to ^$Event("PPOS").

If the event is related to a gadget (component or control), the position is relative to the origin of that entity. If the event is related to a window, the position is relative to the current viewport of that window.

In any event, the value returned in this context is presented in the units that are specified by the property called Units for the entity in question.


Assume that the current control is a Generic, and that the images drawn on the control represent selectable entities. Further assume that each selectable entity is a rectangle of 24 by 32 units, with 10 entities on each row.

The following sequence of commands in the action logic for the event ptrUp determines the internal sequence number of the entity under the mouse when the button was released:

S p=%%EvPtrPos,x=$Pp(p,",",1)\24,y=$P(p,",",2)\32

S i=y*10+x

D I^%msgbox("You selected item number "_i_".")


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrButton	%%EvPtrState
%%EvSequence	%%EvType	%%EvWindow


%%EvPtrState

See also

The mouse buttons that were pressed when the current event occurred.

Definition

During action logic initiated by low-level click, dblClick, ptrDown, ptrDrag, ptrMove or ptrUp events, returns a list of the pointer (mouse) buttons that were depressed when the event occurred.  Each list entry is a buttoncode.  It is equivalent to ^$Event("PSTATE").

Each list entry is a buttoncode. PB1 is the primary button, normally the left one. PB3 is the secondary, normally the right. The modifiers ALT, CTRL and SHIFT may be prefixed on these values.

Assume that a series of mouse events occurs. The table below describes the various values (each mouse-down event adds a button code to the list in %%EvPtrState, each mouse-up event removes one):

Event	Value of %%EvPtrButton	Value of %%EvPtrState
mouseDown	"PB1"	"PB1"
mouseUp	"PB1"
mouseDown	"PB3"	"PB3"
mouseUp	"PB3"
mouseDown	"PB1"	"PB1"
mouseDown	"PB3"	"PB1,PB3"
mouseUp	"PB1"	"PB3"
mouseUp	"PB3"
mouseDown	"PB1"	"PB1"
mouseDown	"PB3"	"PB1,PB3"
mouseUp	"PB3"	"PB1"
mouseUp	"PB1"


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrButton	%%EvPtrPos
%%EvSequence	%%EvType	%%EvWindow


%%EvSequence

Examples	See also

The sequence number of the current event.

Definition

For all events, returns the sequence number of the event.  It is equivalent to ^$Event("SEQUENCE").

The sequence number assigned to an event is generally of little interest, since events are always processed in the correct sequence. On occasion, one might wish to record some or all of the events, and keep track of the sequence in which they occurred.


Assume that an application wants to keep track of certain events. In the CommonCode section, a subroutine is included:

log(event,text) ;

    S ^log($j,%%EvSequence)=event_": "_text

    Q

and several pieces of action logic start with:

    S remind=...

    Do log(%%EvType,remind)


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrButton	%%EvPtrPos
%%EvPtrState	%%EvType	%%EvWindow


%%EvType

Examples	See also

The type of the current event.

Definition

Returns the MWAPI type of the current event.  It is equivalent to ^$Event("TYPE").

Possible types are:

CHANGE	CHAR	CLICK	CLOSE
DBLCLICK	DESELECT	FOCUS	GOBOTTOM
GODOWN	GODOWNBIG	GOTOP	GOUP
GOUPBIG	HELP	KEYDOWN	KEYUP
LINKACTION	LINKCLOSE	LINKEXECUTE	LINKNOTIFY
LINKOPEN	LINKPOKE	LINKREQUEST	LINKUPDATE
MAX	MIN	MOVE	PDOWN
PDRAG	PMOVE	PUP	RESIZE
RESTORE	SELECT	TIMER	UNFOCUS.


This could be used in the action logic for the high level event Choose to find out whether the low level event was a select or a deselect:

I %%EvType="DESELECT"


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrButton	%%EvPtrPos
%%EvPtrState	%%EvSequence	%%EvWindow


%%EvWindow

Examples	See also

The run-time name of the window associated with the current event.

Definition

Returns the name of the window associated with the current event.  It is equivalent to ^$Event("WINDOW").

Within the event's action logic this will be the same as %%CurrWin.


Fetch the header-title of the window for which the current event was triggered:

S value=%%Prop(@%%EvWindow..Title)

Change the color of the background in the current window to white:

%%Set(@%%EvWindow..BackColor,%%White)


%%EvChoice	%%EvControl	%%EvElement	%%EvKey
%%EvNext	%%EvPrior	%%EvPtrButton	%%EvPtrPos
%%EvPtrState	%%EvSequence	%%EvType


%%Focus

See also

Get the name of the window and control having focus.

Definition

Returns the run-time name of the MSM-Workstation window and the name of the control within that window that currently have focus. The two components are separated by a comma.

Do not use this macro on the left-hand-side of an assignment. To move the focus under program control, use %%SetFocus.

Note: The window and control that currently have focus is not necessarily the same as the "current window" and "current control". Typically the two pairs are the same, but not always. For instance, while an object is being created, it is the "current" object, but it doesn't have focus.


%%CurrCtl	%%CurrWin	%%FocusCtl	%%FocusWin
%%SetFocus


%%FocusCtl

See also

Get the name of the control having focus.

Definition

Returns the name of the MSM-Workstation control that currently has focus.

 Do not use this macro on the left-hand-side of an assignment. To move the focus under program control, use %%SetFocus.

Note: The control that currently has focus is not necessarily the same as the "current control". Typically the two are the same, but not always. For instance, while an object is being created, it is the "current" object, but it doesn't have focus.


%%CurrCtl	%%CurrWin	%%Focus	%%FocusWin
%%SetFocus


%%FocusWin

See also

Get the name of the window having  focus.

Definition

Returns the run-time name of the MSM-Workstation window that currently has focus.

 Do not use this macro on the left-hand-side of an assignment. To move the focus under program control, use %%SetFocus.

Note: The window that currently has focus is not necessarily the same as the "current window". Typically the two are the same, but not always. For instance, while a window is being created, it is the "current" window, but it doesn't have focus.


%%CurrCtl	%%CurrWin	%%Focus	%%FocusCtl
%%SetFocus


%%Get

Examples	See also

Get the value of the property of an object into a variable.

Syntax

%%Get ( ObjectProperty [ , Variable ] )

Definition

Parameter	Description
ObjectProperty	An object and property specification. The normal defaulting rules for ObjectProperty can simplify the use of this macro. If the property is not identified, the macro gets the Default Property for the object type.
Variable	A local or global variable, may be subscripted. Default is the first 8 characters of the property name.
%%Get retrieves the value of the Property of a control, window, menu choice, menubar, toolbar, or toolbar button (parameter ObjectProperty) and places that value into a variable (parameter Variable).

For some combinations, such as Value for a List or LongList, results appear in an array descending from Variable.

If the value of a property needs to be used in an expression, %%Prop should be used to reference that value.

Note that when manipulating the value of certain properties using the Property Bar symbolic names such as "Yes" and "No" are used. However when manipulating the value using macros the underlying values must be used. These are given on the message-line when the corresponding value is selected on the Property Bar dropdown; in the case of "Yes" and "No" they are 1 and 0.

If you %%Get the CHOICE attribute on a toolbar, menubar or menu choice, behavior as follows. On a toolbar it will return the MWAPI structure for the toolbar buttons. On the menubar it will return the MWAPI structure for the items on the main menubar, which are the top level items listed from left to right. For a menu choice item it will return the MWAPI structure of the submenu of this choice, so if you have an "Edit" menu it will give you the list of items that appear on the "Edit" menu.

If the property name is omitted, the Default Property for the object type is accessed.


Set local variable ACT to the value 1 if the control called "List1" on the current window is active, otherwise set the local variable ACT to the value 0:

%%Get(List1.Active,ACT)

Get the default property of the control called "Drinks" and place it in local variable DR. If the control called "Drinks" is a list accepting multiple values, the array DR() will be filled with the current selections:

%%Get(Drinks.,DR)

Set local variable BC to the value for the background color of the window called "MyWin" :

%%Get(MyWin..Color,BC)

Set local variable ACT to the value 1 if the menu choice with the application ID of "MenuChoice" is active and 0 otherwise:

%%Get(.M.MenuChoice.Active,ACT)

Set local variable VIS with the value 1 if the menubar on the current window is visible and 0 otherwise:

%%Get(.M..Visible,VIS)

Set the local variable VIS with the value 1 if the toolbar called "Tbar" on the window called "MyWin" is visible and 0 otherwise:

%%Get(MyWin.T.Tbar.Visible,VIS)

Set the local variable ACT with the value 1 if the toolbar button with application ID equal to the value of the variable var is active and 0 otherwise:

%%Get(.TB.@var.Active,ACT)

This will merge in the MWAPI structure for the submenu of the menu choice with application ID "MenuChoice":

%%Get(.M.MenuChoice.CHOICE,CH)


%%GetChoice	%%GetSel	%%Prop	%%Reset
%%ResetChoice	%%ResetSel	%%Set	%%SetChoice
%%SetSel


%%GetChoice

Examples	See also

Get the choices that are available using a control such as a list or radio button set.

Syntax

%%GetChoice ( Object , Variable [ , SubscriptType [ , DataType ] ] )

Definition

Parameter	Description
Object	The control whose choice information is to be fetched. Default is the current control. The control should be a type that displays choices.
Variable	The name of the variable that will receive choices.
SubscriptType	One or more letters identifying the contents of the subscripts in Variable. Valid letters: A (application identifiers), I (internal identifiers), T (titles). Multiple letters indicate multiple subscripts. Default is I.
DataType	A single letter identifying the data stored in Variable at a subscripted node, one of: A, I, T (as above) or N (nothing, empty string). Default is T.
%%GetChoice retrieves the list of possible choices for a component of a window, and stores the values in this list into an array (parameter Variable). Since the definition of the possible choices is typically established by the programmer, either explicitly in the definition of the component, or under program control when the control is created or manipulated, it is rarely necessary to use this macro.


Get the choices for control named "Drinks" and place it in local array DR(Text,AppId)="" :

%%GetChoice(Drinks,DR,TA,N)


%%Get	%%GetSel	%%Prop	%%Reset
%%ResetChoice	%%ResetSel	%%Set	%%SetChoice
%%SetSel


%%GetSel

Examples	See also

Get the selection(s) made using a control which presents a list of alternatives such as a list or radio button set.

Syntax

%%GetSel ( [ Object ] , Variable [ , SubscriptType [ , DataType ] ] )

Definition

Parameter	Description
Object	The control whose selections are to be fetched. Default is the current control. The control should be a type that has a list of choices (a list type, radio button, or table).
Variable	The name of the variable containing the choices.
SubscriptType	One or more letters identifying the contents of the subscripts in Variable. Valid letters: A (application identifiers), I (internal identifiers), T (titles). Multiple letters indicate multiple subscripts. Default is I.
DataType	A single letter identifying the data stored in Variable at a subscripted node, one of: A, I, T (as above) or N (nothing, empty string). Default is T.
The %%GetSel macro retrieves the value of the selections of control specified by Object and places them into the array specified by Variable.

Internal identifiers, titles, and application identifications may be used to return different structures. For instance, the titles associated with the selection may be returned so they are immediately available. Also, multiple selections with identical titles can be distinguished by identifier.

This is very frequently used to retrieve user selections.

The output array may immediately be used to set the choices or selections of another control.


Fill the local array ACT(Id) with the Title-values for the current selections on the control called "List1":

%%GetSel(List1,ACT)

Fill the local array NAMES(Title,Aid)="" with selections from the control called "Name" :

%%GetSel(Name,NAMES,TA,N)


%%Get	%%GetChoice	%%Prop	%%Reset
%%ResetChoice	%%ResetSel	%%Set	%%SetChoice
%%SetSel


%%GetVar

Examples	See also

Retrieve the value displayed in a control on the current window by referring to its local variable.

Syntax

%%GetVar ( TiedVariable )

Definition

Parameter	Description
TiedVariable	A local variable tied to a control on the current window.
The %%GetVar macro is used to refer to controls by means of local variables associated with the control via the VarName property. The name specified in TiedVariable is used to look up the control to which it refers on the current window. Then the Value of that control is retrieved and set into TiedVariable. If the display format and/or validation defined for the associated control maintain a distinction between the internal and external form of the control's value, the local variable specified by TiedVariable contains the internal form, and TiedVariable("X") the external.

This macro is rarely needed because the TiedVariable is automatically updated when the control is changed and exited. Occasionally though, the new value is wanted earlier than the automatic refresh provides for.


On the current window, find the control associated with variable TESTNO, retrieve its value and place that value into variable TESTNO:

%%GetVar(TESTNO)


%%ResetVar	%%SetVar


%%Gray

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Green	%%Magenta	%%Red	%%White
%%Yellow


%%Green

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Gray	%%Magenta	%%Red	%%White
%%Yellow


%%Hide

Examples	See also

Make a window or control invisible.

Syntax

%%Hide ( Object )

Definition

Parameter	Description
Object	The control or window to be hidden. Default is the current object.
%%Hide is used to make a window or control invisible.


Make the control called "Button1" on the window called "Win1" invisible:

%%Hide(Win1.Button1)

Make the window called "Win1" invisible:

%%Hide(Win1.)

Make the current window invisible:

%%Hide(.)

Make the current window or control invisible:

%%Hide


%%Show


%%I

Examples	See also

Returns an object-reference to the current ActiveX control. Only available within the control's action logic.


Assume that the current control is the Tree View control from Microsoft Visual Basic 5.0TM

Copy a "handle" to the object into a local object variable, which can then be used outside the control's action logic:

ZSET tree=%%I

Set the value for property Indentation of the current obect (this property is the indentation step size in pixels):

S %%I.Indentation=20

Define an object-valued property value.  The value obtained through this macro is an object-reference itself:

ZSET tree.ImageList=%%I

Define a local variable to hold a handle to another object "pointed to" by the tree object.  The Add method adds a node to the tree and returns a handle to the object that represents the new node:

ZSET Lev1=%%I.Nodes.Add(,1,,"Top-Level")


%%I


%%IOVar

Examples	See also

Used to pass parameters to and from windows and modules.

Definition

Parameters may be passed when a window is invoked. This macro is replaced by the name of the local array through which these parameters are available to action logic within the window.

The macros that are used to invoke a window and specify the actual parameters are %%DoWin and %%OpenWin.


Invoke a window called "SomeWindow", passing the array param as the actual parameter list:

N param

S param(1)=27

S param("Name")="Doe, John"

%%DoWin(SomeWindow,.param)

Within the window, the parameters can be referenced as %%IOVar(1) and %%IOVar("Name") respectively.


%%Cancel	%%Do	%%DoWin	%%OpenWin


%%IsOK

Examples	See also

Indicate success during action logic.

Definition

After using the %%Perform macro it may be necessary to clear the %%NotOK signal returned, so that the calling action logic can in turn report success to its own caller. %%IsOK does this.

To check the signal status, examine %%OK. If its value is false, the performed action executed %%NotOK before quitting.


In the action logic of a GUI window for the low-level event close, report success when all necessary saving operations have been completed:

I allsaved %%IsOK Q

In the action logic of a GUI Text control for the low-level event lostFocus, report success when two values compare in the required manner:

I MyVar<Yours %%IsOK Q


%%Cancel	%%NotOk	%%OK	%%RetCancel
%%RetCode	%%RetNormal	%%Return


%%IsOLEserver

Determine at startup whether an executable is an interactive application or a server.

Definition

This macro is only used in the Enter logic of an Application module which is used to generate an EXE as a "dual-mode executable".

Such an EXE may be run as either an interactive application or an Automation server, and the current mode must be detectable.  The macro %%IsOLEserver is provided, allowing the application action logic to differentiate as necessary.  It returns TRUE when the EXE is running as an Automation Server. This macro can be ignored in the most common situation, in which an application is either one thing or the other, but not both.


%%KillCtl

Examples	See also

Remove a component.

Syntax

%%KillCtl ( [ WinName . ] CtlName )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the run-time name of a window. Default is the current window.
CtlName	A string literal (without quotes) representing the name of a control, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a control.
%%KillCtl should only be used for window components that were created by directly merging structures into ^$Window, or by using %%MergeCtl. Use on a control specified at design-time is not recommended.


Kill a control called "Button" in a window called "Test":

%%KillCtl(Test.Button)


%%KillWin	%%MergeCtl	%%MergeWin


%%KillWin

Examples	See also

Remove a window.

Syntax

%%KillWin ( WinName )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a window in ^$Window.
%%KillWin should only be used for MWAPI windows that were created directly at runtime, e.g. by directly merging structures into ^$Window, or by using %%MergeWin.

Use %%CloseWin to close other windows, such as non-modal ones that were opened using %%OpenWin, or modal ones that used the option Hide when a %%Cancel or %%Return was executed.

For closing the current window, use %%Cancel and %%Return.


Kill a window called "Test":

%%KillWin(Test)


%%KillCtl	%%MergeCtl	%%MergeWin


%%Magenta

Examples	See also

The color "magenta" is also known as "purple".

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Gray	%%Green	%%Red	%%White
%%Yellow


%%MarkMenu

Examples	See also

Shows or hides the menu marker-symbol defined at design-time for a menu item on the current window.

Syntax

%%MarkMenu ( AppId [ , Value ] )

Definition

Parameter	Description
AppId	The Application identification of the menu choice to be marked. If there is more than one menu choice matching the identification, all are affected. If AppId takes the form @var then the matching occurs at run-time. Otherwise it occurs at compile-time, when multiple-matches give rise to a warning and non-match causes a compilation error. The default value is the menu choice whose action logic this macro is placed in.
Value	An expression that evaluates to true to mark, false to remove the marker. The default is true.


Mark the menu choice with application identification "Edit:Cut" on the current window:

%%MarkMenu(Edit:Cut)

Mark or unmark the menu choice with the application identification matching the value of variable which, depending on whether or not variable yn has a true value (mark if true, unmark if false):

%%MarkMenu(@which,yn)

When placed in the action logic of a menu choice for which you have specified a marking symbol then clicking on this menu choice will cause the mark symbol to be toggled on and off:

%%MarkMenu(,(%%Prop(Marker)=""))


%%EnableMenu	%%PopMenu


%%MDIArrangeIcons

Examples	See also

Arrange the icons of the MDI child windows.

Syntax

%%MDIArrangeIcons [ ( WinName ) ]

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of an MDI parent window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names an MDI parent window. If not specified the default is the current window, or if this is an MDI child window then the associated MDI parent window.
%%MDIArrangeIcons will arrange the iconized MDI child windows in a particular MDI parent window so that they are lined up across the bottom of the MDI parent window.


Arrange the icons of the MDI children in the current window, or if the current window is an MDI child it will use the associated MDI parent window. This can be placed in the action logic for the MDI parent or for the MDI children:

%%MDIArrangeIcons

Arrange the icons of the MDI children in the MDI parent window called "Win1":

%%MDIArrangeIcons(Win1)


%%MDICascade	%%MDITileH	%%MDITileV


%%MDICascade

Examples	See also

Cascade the MDI child windows.

Syntax

%%MDICascade [ ( WinName [ , SkipDisabled ] ) ]

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of an MDI parent window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names an MDI parent window. If not specified the default is the current window, or if this is an MDI child window then the associated MDI parent window.
SkipDisabled	An expression that evaluates to true or false. If true then MDI child windows that are disabled are not cascaded, if false then all MDI child windows are cascaded. The default is false.
%%MDICascade will arrange all MDI child windows in a particular MDI parent so that they are all open, the same size and offset from each other in a cascade pattern.


Cascade all the MDI child windows in the current window, or if the current window is an MDI child then the associated MDI parent window. This can be placed in the action logic for the MDI parent or for the MDI children:

%%MDICascade

Cascade all the MDI child windows in the MDI parent window called "Win1":

%%MDICascade(Win1)

Cascade all the Active MDI child windows in the current window (or its parent). MDI child windows that are disabled will not be affected:

%%MDICascade(,1)


%%MDIArrangeIcons	%%MDITileH	%%MDITileV


%%MDIExtendMenu

Examples	See also

Specify the menu to be used for enumerating the MDI child windows.

Syntax

%%MDIExtendMenu [ ( Object ) ]

Definition

Parameter	Description
Object	The menu choice that you wish to extend. This defaults to the menu whose action logic the macro is placed in. If this macro is not placed in a menu action logic and no Object is specified a compile error occurs.
The specified menu is extended with a list of all the MDI child windows under this MDI parent window. Selecting an MDI child window on this extended menu activates the child and it receives the focus.


Extend the current menu with the list of MDI child windows. Put this command in the action logic for the menu that you want to extend. So if you have a top level menu called 'Window' that you wish to extend, put this command in the action logic for the menu item 'Window':

%%MDIExtendMenu

Extend the menu with an application ID of "Edit" on the current window with the list of MDI child windows:

%%MDIExtendMenu(.M.Edit)


%%MDIArrangeIcons	%%MDICascade	%%MDITileH
%%MDITileV


%%MDITileH

Examples	See also

Tile the MDI child windows horizontally.

Syntax

%%MDITileH [ ( WinName [ , SkipDisabled ] ) ]

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of an MDI parent window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names an MDI parent window. If not specified the default is the current window, or if this is an MDI child window then the associated MDI parent window.
SkipDisabled	An expression that evaluates to true or false. If true then MDI child windows that are disabled are not tiled, if false then all MDI child windows are tiled. The default is false.
%%MDITileH will arrange all MDI child windows in a particular MDI parent so that they are all open, the same size and tiled horizontally. This results in their horizontal width being the width of the MDI parent client space and the windows appearing one below another so they do not overlap.


Tile horizontally all the MDI child windows in the current window, or if the current window is an MDI child then the associated MDI parent window. This can be placed in the action logic for the MDI parent or one of the MDI child windows:

%%MDITileH

Tile horizontally all the MDI child windows in the MDI parent window called "Win1":

%%MDITileH(Win1)

Tile horizontally all the Active MDI child windows in the current window (or its parent).  MDI child windows that are disabled will not be affected.

%%MDITileH(,1)


%%MDIArrangeIcons	%%MDICascade	%%MDITileV


%%MDITileV

Examples	See also

Tile the MDI child windows vertically.

Syntax

%%MDITileV [ ( WinName [ , SkipDisabled ] ) ]

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of an MDI parent window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names an MDI parent window. If not specified the default is the current window, or if this is an MDI child window then the associated MDI parent window.
SkipDisabled	An expression that evaluates to true or false. If true then MDI child windows that are disabled are not tiled, if false then all MDI child windows are tiled. The default is false.
%%MDITileV will arrange all MDI child windows in a particular MDI parent so that they are all open, the same size and tiled vertically. This results in their vertical height being the height of the MDI parent client space and the windows appearing one to the right of another so they do not overlap.


Tile vertically all the MDI child windows in the current window, or if the current window is an MDI child then the associated MDI parent window. This can be placed in the action logic for the MDI parent or the MDI children:

%%MDITileV

Tile vertically all the MDI child windows in the MDI parent window called "Win1":

%%MDITileV(Win1)

Tile vertically all the Active MDI child windows in the current window (or its parent). MDI child windows that are disabled will not be affected:

%%MDITileV(,1)


%%MDIArrangeIcons	%%MDICascade	%%MDITileH


%%MergeCtl

Examples	See also

Add components to a window from an array.

Syntax

%%MergeCtl ( [ WinName . ] CtlName , Variable )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a window. Default is the current window.
CtlName	A string literal (without quotes) representing the name of a control, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a control.
Variable	The name of a local or global array containing a definition of the control in  MWAPI format.
%%MergeCtl applies an MWAPI gadget definition to the window using the specified control name. It can be used to create new controls, or to apply sets of MWAPI attributes to existing controls. The most common use is in submitting DRAW-commands to a Generic control.


Create a control called "Button" in a window called "Test" from an MWAPI definition in array CTL:

%%MergeCtl(Test.Button,CTL)


%%KillCtl	%%KillWin	%%MergeWin


%%MergeWin

Examples	See also

Create a new window from an array.

Syntax

%%MergeWin ( WinName , Variable )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the name of a window in ^$Window. If missing, the default is the current window.
Variable	The name of a local or global array containing a definition of the window in MWAPI format.
%%MergeWin applies an MWAPI window definition to the specified node of ^$Window.


Create a window called "Test" from the definition stored in the subtree descending from global variable ^MYWIN(1):

%%MergeWin(Test,^MYWIN(1))


%%KillCtl	%%KillWin	%%MergeCtl


%%MoveBehind

Examples	See also

Move a window or control  behind a specified window or control in the Z-order, or behind all others.

Syntax

%%MoveBehind ( Object1 [ , Object2 ] )

Definition

Parameter	Description
Object1	A string literal (without quotes) representing the name of the window or control whose Z-order you wish to move. Default is the current control or window.
Object2	If present, the name of the window or control that you wish to move Object1 behind in the Z-order. If not present, Object1 is moved as far back as possible.
This command manipulates the Z-order of a control or window so it can be placed in front or behind the other controls or windows in this application.

When a window is created the Z-order of its controls is determined by the order their names collate in. A control called 'A' will appear in front of a control called 'Z'. This fact can be used to establish the Z-order of the controls as design time.


Move Window1 behind all other windows in this application. This example assumes it is on control action logic, hence the dot after the window name:

%%MoveBehind(Window1.)

Move the control Button1 behind the control ListBox1 on the current window:

%%MoveBehind(Button1,ListBox1)


%%MoveFront


%%MoveFront

Examples	See also

Move a window or control to the front of the Z-order.

Syntax

%%MoveFront ( Object )

Definition

Parameter	Description
Object1	A string literal (without quotes) representing the name of the window or control that you wish to move to the front of the Z-order. Default is the current control or window.
This command manipulates the Z-order of a control or window so it can be placed in front of other controls or windows in this application.

When a window is created, the Z-order of its controls is determined by the order their names collate in. A control called 'A' will appear in front of a control called 'Z'. This fact can be used to establish the Z-order of the controls as design time.


Moves the control Button1 on Window1 to the front of the Z-order so that is appears in front of any other controls on Window1:

%%MoveFront(Window1.Button1)


%%MoveBehind


%%NotOK

Examples	See also

Indicate failure during action logic.

Definition

In general, this macro is used to skip subsequent action logic that would normally be performed to complete the handling of the current.

The precise effects of this macro vary, according to the action logic in which it is placed. For example, use in the logic for the low-level close event on a window will prevent execution of the system-supplied %%Return that would otherwise close the window.

The Role of %%NotOK

The following table summarizes the effect of executing %%NotOK during action logic.

Event	Effect
Any event	Prevents any chained event from occurring, so suppressing the action logic on that event.
Window Create	Prevents any Control Create events from occurring. If the Window Create arose from a %%Do, %%DoWin or %%OpenWin call needing to create the window (which is normally the case) %%NotOK leads to the window not being created and the call returning immediately.
Control Create	Prevents Control Create events for any following controls (in collating sequence of control name). If the Control Create arose from a Window Create (which is normally the case) the %%NotOK is applied to the Window Create too. For the meaning of this, see the Window Create entry in this table.
Window Destroy	Prevents the kill of the window. Prevents Control Destroy events from occurring. If the Window Destroy arose from a non-hiding %%Return or %%Cancel (which is normally the case) the %%Return or %%Cancel operation still completes. The logic that signaled %%NotOK should probably %%Hide the window itself.
lostFocus (Window or Control)	Kills ^$EVENT("OK"). When the action logic quits this sets the focus back to the control or window that caused the lostFocus (i.e. the MWAPI UNFOCUS) event, suppressing any gotFocus (i.e. MWAPI FOCUS) that might accompany the lostFocus, discarding deferred events and reversing visible changes as far as possible.
change, Modified	As for Control lostFocus. In addition, the MWAPI attribute CHANGED is not automatically cleared in the way that occurs when a change event completes normally. The effect of this is that a subsequent user attempt to unfocus from the control will give rise to another change event.
close	Prevents execution of the default %%Return macro supplied by the compiler


%%Cancel	%%IsOK	%%OK	%%RetCancel
%%RetCode	%%RetNormal	%%Return


In the close logic of a window, prevent execution of the the default %%Return:

I 'allsaved %%NotOK Q

In the lostFocus logic of a Text control, prevent execution of any code in the action logic for the Exit, and for any matching gotFocus and associated events, and return the focus to the control:

I MyVar<Yours %%NotOK Q


%%OK

Examples	See also

Check success during action logic.

Definition

Accesses the outcome signaled by %Perform %%Perform. Typically, it will have a true value, the exception being when the performed action used %%NotOK.


Perform the action called "MoveNext" on the SQL Data control named "DataMain" to move the data pointer to the next record. Pop up an messagebox to report whether or not the operation was successful:

%%Perform(DataMain.MoveNext)

D I^%msgbox($S(%%OK:"OK",1:"Problem"))


%%Cancel	%%IsOk	%%NotOk	%%RetCancel
%%RetCode	%%RetNormal	%%Return


%%OpenWin

Examples	See also

Load a window into memory.

Syntax

%%OpenWin ( WinName [ , Parameters [ , Settings ] ] )

Definition

Parameter	Description
WinName	A string literal (without quotes) representing the name of a window, or an at-sign followed by the name of a local variable (@name) where the value of that variable names a window. In either case the window name may optionally include an instance-suffix in square-brackets. If this is absent, instance 0 is implied.
Parameters	Either an expression or a period, followed by the name of an M local variable (similar to an array passed "by reference" to a subroutine or function). When the name of an array is specified, this array can contain both input and output variables stored in named subnodes. Within the called window the array is accessed using %%IOVar. Any structure may be manipulated in this array. When invoking a window through the %%OpenWin macro (rather than through %%Do or %%DoWin), the array's contents are presented only to the  Create sections of window and control action logic.
Settings	An expression or array containing properties and settings which will override property settings already in the window. This is the only way to alter at run-time certain MWAPI attributes which cannot be changed once a window has been created. Format alternatives are listed under %%DoWin. %%OpenWin creates the window, applying any values in Parameters during the load. It then performs any window and control Create logic. Settings may be used to set MWAPI attribute VISIBLE=0 if it is desired to load the window without displaying.
%%OpenWin does not set focus onto the window. It returns to the caller immediately after the creation has completed. Once a window has been created with %%OpenWin, subsequent use of %%OpenWin on the same window has no effect until the window is removed using %%CloseWin.

When opening MDI child windows, an instance-suffix is generally specified. The caller is responsible for assigning non-negative integer instance-numbers to permit creation of new instances of a window.


Open the window called "Main" with the current window as its parent. Perform the Create logic for that window and all its controls and then proceed with the command following %%OpenWin:

%%OpenWin(Main,,%%CurrWin)

Open a new instance of the window called "MDIChild":

S index=$G(index)+1

%%OpenWin(MDIChild[index])

%%SetFocus(MDIChild[index].)


%%CloseWin	%%DoWin


%%Perform

Examples	See also

Perform action logic associated with an object's event.

Syntax

%%Perform ( [ Object . ] Action [ , Parameters ])

Definition

Parameter	Description
Object	The window or control whose action logic is to be performed.
Action	The name of an action logic section associated with the control or window. This parameter is case-sensitive
Parameters	If the section takes parameters, these may be passed in this position. See the high level event MoveTo for an example of parameters being used.
%%Perform causes immediate execution of the action logic. This is different from placing an event on a queue, which may be done using %%Trigger


Perform the action called "MoveNext" on the control named "DataMain" to move the data pointer to the next record:

%%Perform(DataMain.MoveNext)


%%Trigger


%%PopMenu

Examples	See also

Displays a pop-up menu belonging to the current window and waits for user interaction.

Syntax

%%PopMenu ( Menu [ , PosX [ , PosY [ , PosU [ , DefaultItem ] ] ] ] )

Definition

Parameter	Description
Menu	The Application identification of the menu to be displayed. If AppId takes the form @var then the matching occurs at run-time. Otherwise it occurs at compile-time, and if there is more than one menu match a compile error will be reported. Must identify a menu on the current window.
PosX	A positive numeric value, indicating the position of the left edge of the menu. Must be specified if PosY is specified.
PosY	A positive numeric value, indicating the position of the top edge of the menu. Must be specified if PosX is specified.
PosU	Units used for PosX and PosY. Defaults to the value of the Units property for the window on which the menu is defined. Must not be specified if PosX and PosY are omitted.
DefaultItem	The application ID of the menu item to display in bold. Typically used to indicate a default menu item, or the action that would be performed on a double click. Note that it is the programmer's responsibility to cause such default processing, for example by coding the dblClick event for the appropriate object.
Typically, this macro would be invoked in the context of processing an event that signals that a menu is needed (usually a key-up or a mouse-button-up event).

The window owning the menu must have focus when the macro executes, otherwise an error occurs. This precludes its use during lostFocus or change events, or corresponding high-level events, when focus is in a special state pending the outcome of the event.

When the positioning parameters are omitted during use of the macro in a pointer event, the menu will appear at the position associated with the event.

Any action logic associated with the menu will be executed before the menu appears.

When %%PopMenu is reached during execution of action logic, any action logic associated with the menu is executed. The menu then appears and no further M code is executed until an item is selected or the menu is dismissed without selection. At this point, any remaining action logic following the %%PopMenu is completed. If the pop-menu was dismissed by selection of an item, that item's action logic is generally the next to be executed. An example of an exception would be a timer that expired in the intervening period.


Assume this code is in the action logic for the ptrUp event, to catch the button parameter of the event:

S button=%%EvPtrButton

In case where the left-button is pressed and released, do xxx:

I button="PB1" D  Q

. xxx

In the case where the right-button is pressed and released, pop up the menu for the current object. Display the popup menu with the menu item with application ID 'test' in bold:

I button="PB3" D  Q

. %%PopMenu(MenuForDemo,,,,test)

. Q

Indirection can be used with this macro, for example this will popup the same menu as the previous example with the same item in bold:

S menu="MenuForDemo",default="test"

%%PopMenu(@menu,,,,@default)


%%EnableMenu	%%MarkMenu


%%Prop

Examples	See also

Return the value of the property of an object.

Syntax

%%Prop ( ObjectProperty )

Definition

Parameter	Description
ObjectProperty	An object and property specification. The normal defaulting rules for ObjectProperty can simplify the use of this macro. If the property is not identified, the macro gets the Default Property for the object type.
%%Prop can be thought of like an M extrinsic function, returning the value of the Property of the Object.

The specified Property cannot be multiple-valued.

For fetching a property into a variable, consider using the %%Get command.

Note that when manipulating the value of certain properties using the Property Bar, symbolic names such as "Yes" and "No" are used. However when manipulating the value using macros, the underlying internal values must be used. These are given on the status-bar message when using the Value dropdown on the Property Bar. In the case of "Yes" and "No" the internal values are 1 and 0 respectively.


The IF command succeeds if the control called "List1" on the current window is active:

I %%Prop(List1.Active) ...

Quit if the text control called "Note" is empty:

Q:%%Prop(Note.)=""

Set the background color of the current control equal to the surface color of the current window:

%%Set(BackColor,%%Prop(..Color))

Toggle the Active state of the menu item(s) with application ID "MenuChoice":

%%Set(.M.MenuChoice.Active,'%%Prop(.M.MenuChoice.Active))

The IF command succeeds if the toolbar called "Toolbar1" on the window "Win1" is visible:

I %%Prop(Win1.T.Toolbar1.Visible) …


%%ResetChoice	%%GetSel	%%SetSel	%%ResetSel
%%Get	%%Set	%%GetChoice	%%Reset
%%SetChoice


%%Red

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Gray	%%Green	%%Magenta	%%White
%%Yellow


%%Reset

Examples	See also

Reset the value of a property of an object.

Syntax

%%Reset ( ObjectProperty )

Definition

Parameter	Description
ObjectProperty	Identifies the object and property to be reset.
%%Reset causes deletion of the property of the indicated object, effectively setting it equal to its default value. The exact effect depends on the standard behavior for the property's underlying MWAPI attribute.

The normal defaulting rules for ObjectProperty can be used to simplify the use of this macro. If the property is not identified, the macro applies to the Default Property for the object type.


Set the color of the current window to the default (inherited) color:

%%Reset(Color)

Clear the value of the current control:

%%Reset

Reset the Active state of the toolbar button with application ID "Button1" on the current window:

%%Reset(.TB.Button1.Active)

Delete the submenu of the menu choice item(s) with application ID "Edit" on the window "Win1":

%%Reset(Win1.M.Edit.CHOICE)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%ResetChoice	%%ResetSel	%%Set	%%SetChoice
%%SetSel


%%ResetChoice

Examples	See also

Reset the choices of a control.

Syntax

%%ResetChoice ( Object , Variable [ , SubscriptType [ , DataType ] ] )

Definition

Parameter	Description
Object	The control whose selections are to be reset. If missing, default to the current control. The control should be a type that displays a list of choices.
Variable	The name of the variable containing the choices.
SubscriptType	One or more letters (default is I) identifying the contents of the subscripts in Variable. Valid letters: A (application identifiers), I (internal identifiers), T (titles) , N (nothing). N-type is useful where the subscript contents are not relevant to the control. Multiple letters indicate multiple subscripts.
DataType	A single letter (default is T) identifying the data stored in Variable at a subscripted node, one of: A (application identifiers), I (internal identifiers), T (titles), N (nothing). N-type is useful where the data is null, or does not need to be loaded into the control.
%%ResetChoice is used to reset the choices in a control that can present a list of alternatives. It uses an array of choices with the default structure Variable(Id)=Title. Choices can also be identified by application identifications (AppIDs).

Previously set choices are cleared by %%ResetChoice. To add possible choices to a list of existing possibilities, use %%SetChoice.

If neither SubscriptType nor DataType include I, integer IDs are assigned, starting from 1 and traversing Variable in $QUERY-order.


Use local array DR(Id)=Title to build the choices in the control called "Drinks":

%%ResetChoice(Drinks,DR)

Use local array DR(Title)=AppID to build the choices in the control called "Drinks". Note that this will build an M-style alphabetical list:

%%ResetChoice(Drinks,DR,T,A)

For a Windows-style alphabetical list, where upper- and lower-case characters collate adjacent, use a local array DR($ZUCASE(Title),Title)=AppID:

%%ResetChoice(Drinks,DR,NT,A)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%Reset	%%ResetSel	%%Set	%%SetChoice
%%SetSel


%%ResetSel

Examples	See also

Reset the selections on a control.

Syntax

%%ResetSel ( Object , Variable [ , SubscriptType ] )

Definition

Parameter	Description
Object	The control whose selections are to be reset. If missing, default to the current control. The control should be a type that displays a list of choices.
Variable	The name of the variable containing the choices.
SubscriptType	A single letter identifying the type of subscript in Variable, one of: A (application identifiers), I (internal identifiers), T (titles). Default is I.
%%ResetSel causes the current selections in a control to be set from the list of already-set choices. It is commonly used to set the default selections in a control.

Pre-existing selections are first cleared. To add to existing selections without first clearing, use %%SetSel.

Since the selections must be made from pre-existing choices, only a single subscript is supported. However, that subscript need not be an internal identifier.


On the control called "Drinks", select the choices whose title-values match subscripts in the local array DEFAULTS():

%%ResetSel(Drinks,DEFAULTS,T)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%Reset	%%ResetChoice	%%Set	%%SetChoice
%%SetSel


%%ResetVar

Examples	See also

Update the value displayed in a control on the current window by referring to its local variable.

Syntax

%%ResetVar ( TiedVariable )

Definition

Parameter	Description
TiedVariable	A local variable tied to a control on the current window.
%%ResetVar is used to refer to controls by means of local variables associated with the control via the property VarName. The name specified in the parameter TiedVariable is used to look up the control to which it refers on the current window, and the Property Value of that control is reset, causing the display to be updated. The new value is loaded into the variable.

This macro is equivalent to the following sequence, where var is the variable for control:

%%Reset(control.Value)

KILL var

%%GetVar(var)


Kill the property Value of the control associated with local variable TESTNO, then load the resulting value into pre-killed local variable TESTNO:

%%ResetVar(TESTNO)

The value which results from killing the property depends on the behavior of the control. It is usually the empty string.


%%GetVar	%%SetVar


%%RetCancel

Examples	See also

Return value indicating a window was canceled.

Definition

The value found in %%RetCode when a window was closed using a default %%Cancel %%DoWin.


Invoke a window, and pop up a message when the return code indicates that the invoked window was canceled:

%%DoWin(Window,.Params)

I %%RetCode=%%RetCancel D I^%msgbox("Canceled.") Q


%%Cancel	%%IsOK	%%NotOK	%%OK
%%RetCode	%%RetNormal	%%Return


%%RetCode

Examples	See also

Return code from a window.

Definition

The return code supplied by the %%Return or %%Cancel that was used to end a %%DoWin.

Typical values are %%RetNormal and %%RetCancel.


Invoke a window called "Window", and continue processing normally if the window invocation yields a "normal" return code. Otherwise, pop up a window showing the code:

%%DoWin(Window,.params)

I %%RetCode=%%RetNormal Q

D I^%msgbox("Return code is "_%%RetCode)


%%Cancel	%%IsOK	%%NotOK	%%OK
%%RetCancel	%%RetNormal	%%Return


%%RetNormal

Examples	See also

Return value indicating a window terminated normally.

Definition

The value found in %%RetCode when a window was closed using a default %%Return %%Return.


Invoke a window called "Window", and continue processing normally if the window invocation yields a "normal" return code. Otherwise, pop up a window showing the code:

%%DoWin(Window,.params)

I %%RetCode=%%RetNormal Q

D I^%msgbox("Return code is "_%%RetCode)


%%Cancel	%%IsOK	%%NotOK	%%OK
%%RetCancel	%%RetCode	%%Return


%%Return

Examples	See also

Exit and close a window, optionally setting a return code and parameters array.

Syntax

%%Return ( [ ReturnCode ] [ , [ Parameters ] [ , Hide ] ] )

Definition

Parameter	Description
ReturnCode	A value indicating how the window was exited. Default is %%RetNormal. The value is placed in %%RetCode.
Parameters	Expression, or M local variable name.
Hide	An expression which if true causes the window to be hidden but not destroyed. Default is false.
%%Return is typically used to return from a window started with %%Do or %%DoWin. The window is closed and destroyed. A ReturnCode is passed back to the issuer of the %%Do or %%DoWin, where it can be inspected using %%RetCode. The default value for ReturnCode is %%RetNormal %%RetCancel, which is the only indication that a %%Return has been performed rather than a %%Cancel. This value may be overridden.

If Parameters names a local variable, it will be MERGEd into any variable specified as the parameter Parameters in the corresponding macro %%DoWin or %%OpenWin. If Parameters is an expression, its result will be SET into that variable. Using this mechanism, it is possible to return values to the calling environment with ease.

If Hide is true, the window is hidden but not destroyed. This allows faster future reuse through bypassing the need for subsequent creation. %%CloseWin should be used at the point where the window is no longer required.

For closing the current window, use %%Cancel and %%Return.

Use %%CloseWin to close other windows, such as non-modal ones that were opened using %%OpenWin, or modal ones that used the option Hide when a %%Cancel or %%Return was executed.

%%KillWin should only be used for MWAPI windows that were created directly at runtime, e.g. by directly merging structures into ^$Window, or by using %%MergeWin.


Without parameters, the macro causes the removal of a window, and causes no special parameters to be returned. The exit-status in %%RetCode will be %%RetNormal %%RetCancel:

%%Return

When the second parameter is present, the contents of the array named in this parameter will be merged into the parameter-array that was specified when the window was invoked. The third parameter indicates that the window will be hidden but not destroyed:

%%Return(0,temp,1)

The exit-status in %%RetCode will be set to the application-specific value 123:

%%Return(123)


%%Cancel	%%Do	%%DoWin


%%Set

Examples	See also

Set the value of the property of an object.

Syntax

%%Set ( ObjectProperty , [ Argument ] )

Definition

Parameter	Description
ObjectProperty	An object and property specification. The normal defaulting rules for ObjectProperty can simplify the use of this macro. If the property is not identified, the macro sets the Default Property for the object type.
Argument	If Property is not multiple-valued, an expression yielding the value to assign to the property. Otherwise, a local or global variable name (may be subscripted), which has the values as immediate descendants. Default is the variable with its name corresponding to the first 8 characters of the property name.
%%Set sets the value of the property of the indicated object using the Argument.

Note that when manipulating the value of certain properties using the Property Bar, symbolic names such as "Yes" and "No" are used. However when manipulating the value using macros, the underlying internal values must be used. These are given on the status-bar message when using the Value dropdown on the Property Bar. In the case of "Yes" and "No" the internal values are 1 and 0 respectively..


Set the color of the window called "Order" to red in any action logic:

%%Set(Order..Color,%%Red)

Set green foreground color for current object (window or control):

%%Set(ForeColor,%%Green)

Set current window title to the string constant "Hello, World" in any action logic:

%%Set(..Title,"Hello, World")

Set the value of the (non-list) control called "TestNo" in the current window from the global reference ^RSLT(PID,1), where local variable PID must have a non-empty value:

%%Set(TestNo.,^RSLT(PID,1))

Hide the control named in local variable Ctl if time is not before midday, else make it visible:

%%Set(@Ctl.Visible,$P($H,",",2)<43200)

Assuming current control is a list, set all the values of subscript x in Order("Food",x) as selected choices of the list. The values must match internal identifiers of existing choices:

%%Set(,Order("Food"))

Disable the menu choice item(s) with an application ID of "MenuChoice" on the current window:

%%Set(.M.MenuChoice.Active,0)

Hide the toolbar that is named in the local variable var on window "Win1":

%%Set(Win1.T.@var.,0)

Using the MWAPI structure in "array", create a submenu under the menu choice item(s) with an application ID of "MenuChoice" on the current window:

%%Set(.M.MenuChoice.CHOICE,array)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%Reset	%%ResetChoice	%%ResetSel	%%SetChoice
%%SetSel


%%SetChoice

Examples	See also

Set the choices presented by a control such as a list or radio button set.

Syntax

%%SetChoice ( Object , Variable [ , SubscriptType [ , DataType ] ] )

Definition

Parameter	Description
Object	The control whose choices are to be set. Default is the current control. The control should be a type that displays a list of choices.
Variable	The name of the variable containing the choices.
SubscriptType	One or more letters (default is I) identifying the contents of the subscripts in Variable. Valid letters: A (application identifiers), I (internal identifiers), T (titles) , N (nothing). N-type is useful where the subscript contents are not relevant to the control. Multiple letters indicate multiple subscripts. For instance, TA indicates subscripts (title,appid).
DataType	A single letter (default is T) identifying the data stored in Variable at a subscripted node, one of: A (application identifiers), I (internal identifiers), T (titles), N (nothing). N-type is useful where the data is null, or does not need to be loaded into the control.
%%SetChoice is used to set the choices in a control that can present a list of alternatives. It uses an array of choices with the default structure Variable(Id)=Title. Choices can also be identified by application identifications (AIDs).

This is frequently used to set choices in a control.

Previously set choices are not cleared by %%SetChoice. To clear all choices prior to setting new ones use %%ResetChoice. If SubscriptType or DataType include I, existing choices with matching internal identifiers (IDs) are replaced. Otherwise the choices are appended to the existing list by traversing Variable in $QUERY-order. Integer IDs are assigned, starting after the integer value of the ID of the last pre-existing choice. Take care when mixing numeric and non-numeric IDs.


Use local array DR(id)=Title to add choices to the control called "Drinks":

%%SetChoice(Drinks,DR)

Use local array DR(Title)=AID to add choices to the control called "Drinks". Note that they will be added in M collating sequence, giving an M-style alphabetical list by title:

%%SetChoice(Drinks,DR,T,A)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%Reset	%%ResetChoice	%%ResetSel	%%Set
%%SetSel


%%SetFocus

Examples	See also

Set focus to a window or control.

Syntax

%%SetFocus ( Object )

Definition

Parameter	Description
Object	The window or control to receive focus. If none is specified, the current object will be used by default.
%%SetFocus is used to control the focus, which indicates where user input is expected.

When the control is a TabbedGroup, optionally follow the control name with an expression in square-brackets, identifying the desired tab-number. This is an alternative to changing the Page property using %%Set.

Note that if Object is not specified, focus is set to the current object. This highlights the difference between the "current object" and the "object with focus". Typically these two are the same, but not always. For instance, during Create code for an object the object is the "current" object, but it doesn't have focus.

The macro %%SetFocus sets ^$DIsplay($PDisplay,"FOCUS")=target, and it also performs other tasks listed below. Direct setting ^$Display is strongly discouraged.  If used, features like TabbedGroups, Validation and Display logic, and tied variables are likely to misbehave.

Use of %%SetFocus should be avoided during window Create.

It is not generally possible to transfer the focus to a nominated object during a lostFocus or change event, or corresponding high-level events. These events occur when the user chooses to place the focus elsewhere, perhaps using a mouse-click. If the action logic signals %%NotOK, the focus-change is refused. Otherwise the focus moves to the user's chosen location.

Explanation of %%SetFocus

The %%SetFocus macro performs the following steps:

1.	If focus is already on the specified object (i.e. window, or window and control) do nothing further.

2.	If the target is a control on a TabbedGroup, switch to the correct page.

3.	Attempt to set the focus as requested. This may cause an error, for example when the destination control is not active and visible, which transfers control to the current error handler.

4.	If focus is leaving a control that has a local variable assigned to it, update the variable from the control.

5.	If focus is leaving a control perform an Exit event for that control.

6.	If focus is moving off a window (i.e. the destination object is not on the currently-focused window) perform an Exit event for the window.

7.	If focus is moving onto a user-created MWAPI window not defined within MSM-Workstation do nothing more.

8.	If focus is moving onto a different window (i.e. the destination window is not on the currently-focused window) perform an Enter event for the new window.

9.	If focus is being set onto a control, perform the Enter event for that control.


Set the focus to the control called "TestNo" on the window called "Lab":

%%SetFocus(Lab.TestNo)

Set the focus to the control called "OK" on the current window:

%%SetFocus(OK)

Set the focus to the window identified by the local variable where:

%%SetFocus(@where.)

Set the focus to TabbedGroup called "TG1" on the window called "Win1" and select the third tab:

%%SetFocus(Win1.TG1[3])


%%CurrCtl	%%CurrWin	%%Focus	%%FocusCtl
%%FocusWin


%%SetSel

Examples	See also

Set the selections value of the property of a control.

Syntax

%%SetSel ( Object , Variable [ , SubscriptType ] )

Definition

Parameter	Description
Object	The control whose choices are to be set. Default is the current control. The control should be a type that displays a list of choices.
Variable	The name of the variable containing the selections.
SubscriptType	A single letter (default is I) identifying the contents of the subscript in Variable, one of: A (application identifiers), I (internal identifiers), T (titles). Default is I.
%%SetSel sets the current selection in a control from the list of already-set choices. It is primarily useful to set the default selection in a control.

Where the control type is capable of supporting multiple selection, any existing selection is augmented. The definition of the control must permit the number of selections that will result. Pre-existing selections are not first cleared; to do this use %%ResetSel.

Where the control type is not capable of supporting multiple selection, this macro replaces any existing selection. If Variable contains more than one item, only the first is used.

Since the selections must be made from pre-existing choices, only a single subscript is supported. However, that subscript need not be an internal identifier.

If Variable has data but no descendants, the data is treated as if it were a single subscript.


On the multi-select List control called "Drinks", augment any existing selection to include the choices whose title-values match subscripts in the local array DEFAULTS():

%%SetSel(Drinks,DEFAULTS,T)


%%Get	%%GetChoice	%%GetSel	%%Prop
%%Reset	%%ResetChoice	%%ResetSel	%%Set
%%SetChoice


%%SetVar

Examples	See also

Update the value displayed in a control on the current window by referring its local variable.

Syntax

%%SetVar ( TiedVariable [ , Value ] )

Definition

Parameter	Description
TiedVariable	A local variable tied to a control on the current window.
Value	An optional expression yielding a value to assign to the variable.
%%SetVar is used to refer to controls by means of local variables associated with the control via the VarName property. If a Value parameter is specified, the TiedVariable is set to Value; otherwise the value already in TiedVariable is used. The name of the variable specified by TiedVariable is used to look up the control to which it refers on the current window, and the property Value of that control is set, causing the display to be updated.

If the control has display-formatting properties defined, Value is treated as the internal form.


Set the control associated with local variable TESTNO to the value held by variable TESTNO:

%%SetVar(TESTNO)

Set local variable MAX to the value 10, then set the value of the control associated with local variable MAX to the same value:

%%SetVar(MAX,10)


%%GetVar	%%ResetVar


%%Show

Examples	See also

Make a window or control visible.

Syntax

%%Show ( Object [ , Visible ] )

Definition

Parameter	Description
Object	The control or window to be made visible. Defaults to the current object
Visible	An expression that evaluates to true or false.
%%Show is used to make a window or control visible; or to hide a window or control by setting the parameter Visible to 0.


Make the control called "Button1" on the window called "Win1" visible:

%%Show(Win1.Button1)

Make the window called "Win1" visible:

%%Show(Win1.)

Make current object (window or control) visible:

 %%Show


%%Hide


%%SqlConnect

Examples	See also

Establish an MSM-SQL connection for use by SQL Data controls.

Syntax

%%SqlConnect ( UserName  , Password  [ , [ Connection ] [ , Keep ] ] )

Definition

Parameter	Description
UserName	A string literal (without quotes) representing the MSM-SQL username to connect as, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the username.
Password	A string literal (without quotes) representing the MSM-SQL password for Username, or an at-sign followed by the name of a local variable (@name) where the value of that variable gives the password.
Connection	A string literal (without quotes) naming the connection. This connection will be used by SQL Data controls whose Connection property matches this. If omitted, the default connection is opened for use by controls with no Connection property specified.
Keep	An expression evaluating true or false. If true, the connection is not automatically closed during destroy-processing for the window in whose action logic the macro occurs. Instead, the programmer will use %%SqlDisconnect when necessary. Default is false.
%%SqlConnect can be used to open a run-time connection to MSM-SQL for use by SQL Data controls on windows.

It is only available within action logic belonging to windows that contain at least one SQL Data control.

While it remains open, the connection can be used by SQL Data controls on any window.


Connect to the MSM-SQL system in the current database using the username and password set in the variables user and pwd:

%%SqlConnect(@user,@pwd)

Connect to the MSM-SQL system in the current database using the username DBA and password SHARK:

%%SqlConnect(DBA,SHARK)

Create two connections to MSM-SQL. One is used by SQL Data controls whose Connection property equals "Special", the other is used by those with an empty Connection property. The first connection will not be closed when the current window is destroyed:

%%SqlConnect(DBA,SHARK,Special,1)

%%SqlConnect(ME,MYPWD)


%%SqlDisconnect


%%SqlDisconnect

Examples	See also

Release an MSM-SQL connection.

Syntax

%%SqlDisconnect ( [ Connection ]  )

Definition

Parameter	Description
Connection	A string literal (without quotes) naming the connection to be closed. If omitted, the default connection is closed.
%%SqlDisconnect is typically used to close a connection previously opened using %%SqlConnect with the Keep parameter true.

It is only available within action logic belonging to windows that contain at least one SQL Data control.


Close the connection named Special:

%%SqlDisconnect(Special)

Close the default connection:

%%SqlDisconnect


%%SqlConnect


%%Trigger

Trigger a low-level event, using the MWAPI command ETRIGGER.

Syntax

Examples	See also

%%Trigger ( [ Object.] Event [ , Information ] )

Definition

Parameter	Description
Object	The control or window on which the event is to be triggered. If missing, default to the current object.
Event	A low-level event name, or its corresponding MWAPI name.
Information	A local or global reference containing additional information to be supplied when the event occurs. This corresponds to the optional second argument of the command ETRIGGER.
%%Trigger is used to place a low-level event onto the end of the event queue. It corresponds to the MWAPI command ETRIGGER. It should not be confused with %%Perform which immediately executes the action logic associated with an event.

Triggering an event has no effect upon the corresponding object. For example, triggering a RESTORE event on a minimized window does not restore it.

The parameter Event cannot be a variable, and if the specified event does not apply to the object, or the object does not exist, a run-time MWAPI error occurs.


Trigger a SELECT event for the control called "Button1" on the window called "Win1":

%%Trigger(Win1.Button1.SELECT)

Trigger a keyUp (MWAPI event KEYUP) for the control named in variable gad on the current window, passing the local array info to the event:

%%Trigger(@gad.keyUp,info)

Trigger a restore (MWAPI event RESTORE) for the current window:

%%Trigger(..restore)


%%Perform


%%White

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Gray	%%Green	%%Magenta	%%Red
%%Yellow


%%Yellow

Examples	See also

Basic colors are made available through macros.


%%Black	%%Blue	%%Cyan	%%DarkGray
%%Gray	%%Green	%%Magenta	%%Red
%%White


Service Routines - Overview
Overview

Any application that you produce for redistribution can access a set of service routines.  Source code has been removed from these routines, and comments are used to document entry points.

See Also:

Routine Names

Entry Points

Return Codes

Input vs. Output Parameters

Value vs. Reference Parameters

Service Routine Conventions

Registry Information


Routine Names

Micronetics reserves routine names that begin with %m for this purpose, and you cannot create routines with names of this form. For example, an application that mounts a local or remote database uses an entry point in %msv.

The following routines are used:

Routine	Entry point functionality
%mdfile	Allows access to the common file open/save dialogs provided by the operating system.
%mdlcnse	Allows the developer to retrieve license and version information at run-time, and to display the License Information window.
%mdserv	Displays a dialog for entry of server connection information.
%mmprof	Provides read/write access to the registry for data pertaining to the application for all users on this machine (under HKEY_LOCAL_MACHINE).
%mprof	Provides read/write access to the registry for data pertaining to the application for the current user (under HKEY_CURRENT_USER).
%mreg	Provides read only access to the whole of the registry.
%msc	Accesses common and miscellaneous functions provided by MSM-Workstation and by Windows.
%msgbox	Provides access to Windows message-box services.
%msrpath	Allows routine search paths to be established and viewed.
%msu	Contains UCI management services.
%msv	Contains entry points for database maintenance tasks.


Entry Points

An entry point consists of a tag and routine reference, and parameters. The tag name is a mnemonic that serves as a reminder of the entry point's functionality.

Entry points are classified into public and private categories. Public entry points can be called by any application program and are identified by a tag consisting of all uppercase characters. Private entry points should be called only by Micronetics system utilities and are not to be called from application programs. Private entry points have a tag that consists of either mixed or lowercase characters.

Public entry points are documented in detail in this document.  They are also self-documenting to some extent, because they  include comment text within the routines themselves, even when the M code is hidden.

For example, the routine %msgbox may be loaded into the routine editor as follows.  In the System Browser, go to the MGR,MDS node of the tree, under the <System> node. Expand this node, and click on the Routines branch. After the list loads, double-click on %msgbox. You will see something like the following:

%msgbox	;rwm; System MSGBOX interface [ 02/24/1998  5:59 PM ]

;;GENERATED 06Mar98 1:40pm #43,4444444 from %msgbox v2

;; User entry points all take parameters:

;;

;; Text      in	Text for help

;; Title     in	Title for window.  Optional, default is app name.

;; HelpFile  in	Path to help file.  Optional.

;; HelpIndx  in	Context id from help map.  Optional.

;; Parent    in	Name of parent window in ^$W.  Optional, defaults to current focus. Pass null or nonexistent for no parent

;;

E(Text,Title,HelpFile,HelpIndx,Parent)	;; Error box with OK button

<pcode here>

. . .

I(Text,Title,HelpFile,HelpIndx,Parent)	;; Info box with OK button

<pcode here>

. . .


Return Codes

Except for the simplest entry points, the following conventions allow you to determine easily if an action is successful.

Each entry point, if called extrinsically via the $$ syntax, returns a value that indicates success or failure. A return value of zero indicates success, non-zero (usually -1) indicates failure. After a call that returns a non-zero value, you can examine a Micronetics-reserved variable name, %MERR, for information about the error. This information can be decoded using the entry-point MSG^%msc.

Most public entry points can also be called as procedures, as an alternative to using the $$ extrinsic syntax.  In this case no indication of an error is returned, other than the value of %MERR.  For instance, these are equivalent (and impolite):

S return=$$E^%msgbox("Wrong!")

D E^%msgbox("Wrong!")

When a called entry point does a simple job, return values are returned as the result of a $$ invocation. When this occurs, the return values are clearly indicated. Generally, a pass-by-reference output parameter mechanism is used to return values from service routines.


Input vs. Output Parameters

Parameters that are passed to entry points are classified as one of three types: input, output, or input/output.

An input parameter is used to supply a value that should not be changed by the entry point being called. The parameter should be passed by-value if possible. For a parameter in which an array of input values is passed by-reference, the entry point guarantees not to alter the contents of the variable that is passed to it.

An output parameter is used to return a value. In the entry point framework, the value returned from an extrinsic call generally is a success indicator: zero for success and non-zero for failure. Entry points that return values set the value of a variable that is passed to the entry point by-reference. By convention, these parameters are uppercase.

An input-output parameter classification is used to supply values to the entry point and also is used to retrieve values.  By convention, these parameters are uppercase.


Value vs. Reference Parameters

The formal parameter names as used in the routine source code are listed in the Syntax descriptions below.  By convention, formal parameters which expect arguments passed by-value have mixed-case formal parameter names. This includes all unsubscripted input parameters.

Formal parameter names which are all uppercase indicate that the arguments expected may be (and usually are) passed by-reference.  This includes all output parameters and input-output parameters, as well as arrays of input parameters.

Many entry points use a technique that involves passing parameters in named array subscripts.  Parameters passed in this way must be passed by-reference, and can be used for input or output.

For example, to specify a database host-file name to MOUNT^%msv, place it in IN("DBNAME") and then pass IN by-reference to the entry point:

S return=$$MOUNT^%msv(.IN)

Note the essential period (.) preceding the local variable name IN.


Service Routine Conventions

Standard Names

The following parameter names have standardized meanings in this documentation.

Name	Description
uci	A UCI name or number
uciname	A UCI name
ucinum	A UCI number
vg	A volume group name or number
vgname	A volume group name
vgnum	A volume group number
uv	uci,vg (for example, "1,0" or "MGR,SYS") or just uci (for example, "1" or "MGR")
uvname	uciname,vgname
uvnum	ucinum,vgnum
uvint	vgnum*32+ucinum
Case

The case of parameters also carries meaning, as described in the following table.

Parameter Case	Meaning
UPPERCASE	Passed by-reference (may be input or output).
MixedCase	Passed by-value (necessarily input only).
Summary

In the parameter tables for each entry point below:

•	Mixed-case parameters are passed by-value.

•	Uppercase parameters are (usually) passed by-reference.

•	All parameters are input parameters, that is, passed by-value, unless indicated otherwise by the Type column (which is omitted if all parameters are passed by-value).

•	The phrase "Returns success or failure" indicates that the entry point is intended to be called as an extrinsic function (although this is not necessary; such entry points can also be called as procedures).  If called as a function, the return value is zero for success, non-zero for failure. Details of failure are found in %MERR.


Registry Information

The %mprof, %mmprof, and %mreg routines provide access to the system registry. Information can be stored in a structured format in either the system registry (Microsoft Windows 95 and Windows NT) or the APPNAME.INI file (Microsoft Windows 3.1x ).

Each routine provides access to a different section of the registry and so is used for different purposes:

Routine	Type of Information
%mprof	Defaults for this user. For example the window size and positions, the font type, which language to use, etc. This information is stored on a per user basis so if another user logs onto this machine they can create their own defaults without disturbing the first users settings.
%mmprof	Information about the application that applies to any user. For example system wide defaults such as the directory the application is in, the initial window size to use before the user sets their own size, the name of a server if all users need to connect to the same server, etc.
%mreg	Read-only access to the whole registry. Using this you can find out what program is associated with an extension, which settings the user has defined in Control Panel, which ActiveX controls are currently installed, etc. For detailed information on the registry see the documentation provided by Microsoft or the vendor of the software whose registry entries you wish to view.
When calling entry points in %mreg you must specify the full reference to a valid key name. The possible values of the first piece of the key you pass to it can be any of the following:

HKEY_CLASSES_ROOT

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

HKEY_PERFORMANCE_DATA

HKEY_CURRENT_CONFIG

HKEY_DYN_DATA.

Both the %mprof and %mmprof entry points restrict you to a particular section of the registry, namely anything under:

Routine	Section of Registry
%mprof	HKEY_CURRENT_USER\Software\<VarName>\<AppName>
%mmprof	HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>
In which <VarName> is the identifier of the value-added-reseller and <AppName> is the identifier of the application. Both <VarName> and <AppName> can be specified when the executable is created (under the Make EXE Options dialog). Under this level you can create nested subsections using the '\' character in the name. Each level may have multiple entries with data. An entry with a single sub-section called "Subsection" could be:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Subsection

Entry1=Data1

Entry2=Data2

Under Windows 3.1x, these registration entries are placed in a file named APPNAME.INI with the standard INI file format. The file may be located in either the system or the installation directory, as specified when the executable is created.  A Subsection appears in square brackets and is followed by items of format Entry = Data.  The above example would produce a file APPNAME.INI with

[Subsection]

Entry1=Data1

Entry2=Data2

The following section names are used by Micronetics' utilities and should be avoided by applications when using %mprof:

Databases

Directory

WindowSettings

Future use of section names by Micronetics' utilities will be confined to names beginning with the percent (%) character. All such names should not be used by an application's own %mprof and %mmprof calls.

Note that the Windows registry is case-preserving rather than case-sensitive. That is, the case of text used as keys or data is recorded and retrieved, but case is not required to match when looking up keys or entries. It is not possible to store two entries at a level which differ only in the case of their text, nor to create two sub-keys of the same node if their names differ only in case.


Service Routines A-Z

Entry Point	Description
APPEXE^%msc	Return the path to the application's .EXE file.
APPNAME^%msc	Retrieve the application name.
ARI^%msgbox	Display an Abort/Retry/Ignore message box.
BIJFMT^%msv	Create and format a new BIJ file.
BIJSIZE^%msv	Determine recommended size for a BIJ file.
CHGKEY^%msc	Change the string generated by a function key.
CHKUCI^%msu	Check if UCI valid.
CHKUCIVG^%msu	Determine UCI,VG names and numbers.
CHKUV^%msu	Check if UCI,VG name valid.
CHNGUCI^%msu	Change current UCI,VG.
CREATE^%msv	Create a new database.
CURNTUCI^%msu	Determine current UCI,VG.
DELENTRY^%mprof	Delete registry entry for the current user.
DELENTRY^%mmprof	Delete registry entry for the local machine.
DELSECT^%mprof	Delete registry section for the current user.
DELSECT^%mmprof	Delete registry section for the local machine.
DESTROY^%mdlcnse	Remove a license information window.
DISTRAN^%msv	Disable global translation.
DRVSPC^%msc	Determine the free space on a drive.
E^%msgbox	Display an Error message box.
ENTRAN^%msv	Enable global translation.
EXISTUCI^%msu	Determine if UCI,VG currently available.
EXPAND^%msv	Expand a mounted database.
FREESP^%msv	Return free space in a VG.
FSPC^%msv	Determine free space in a VG.
GETENTRY^%mprof	Retrieve one or more registry entries for the current user.
GETENTRY^%mmprof	Retrieve one or more registry entries for the local machine.
GETENTRY^%mreg	Retrieve one or more registry entries from anywhere in the registry.
GETNAMES^%mprof	Retrieve registry entry names in a section for the current user.
GETNAMES^%mmprof	Retrieve registry entry names in a section for the local machine.
GETNAMES^%mreg	Retrieve registry entry names in a section from anywhere in the registry.
GETSECT^%mprof	Retrieve all registry entries in a section for the current user.
GETSECT^%mmprof	Retrieve all registry entries in a section for the local machine.
GETSECT^%mreg	Retrieve all registry entries in a section from anywhere in the registry.
HOSTNAME^%msv	Determine host file name of a database from the VG.
HOSTVOL^%msv	Determine VG of a database from the filename.
I^%msgbox	Display an Info message box.
INDEX^%msv	Determine VG index from VG name.
INFO^%mdlcnse	Retrieve license and version information.
LIST^%msrpath	Retrieve current routine search path.
LIST^%msu	Retrieve list of UCIs in a VG.
LIST^%msv	Retrieve list of mounted VG names and numbers.
LISTU^%msv	Retrieve list of mounted VGs, UCIs, and monikers.
LMOUNT^%msv	Mount a local VG.
LOADXC^%msc	Load an Xcall package.
MMOUNT^%msv	Mount an in-memory VG.
MONIKER^%msu	Determine monikers associated with a UCI,VG.
MOUNT^%msv	Mount a local or remote VG.
MSG^%msc	Return text for message or error code
NAME^%msv	Determine VG name from VG index.
OK^%msgbox	Display an OK message box.
OPEN^%mdfile	Display the Open File dialog box.
OPEN^%msc	Open a host file.
PATH^%msrpath	Set routine search path.
PDEV^%msc	Reset the principal device.
QQ^%msc	Double quotes in a string.
RC^%msgbox	Display a Retry/Cancel message box.
RESET^%msrpath	Set traditional routine path environment.
RMOUNT^%msv	Mount a remote VG.
RO^%msv	Determine if VG is read-only.
SAVE^%mdfile	Display the Save File dialog box.
SELECT^%mdserv	Display Select Server dialog.
SETENTRY^%mprof	Set a registry entry for the current user.
SETENTRY^%mmprof	Set a registry entry for the local machine.
SETSECT^%mprof	Set multiple registry entries for the current user.
SETSECT^%mmprof	Set multiple registry entries for the local machine.
SHOW^%mdlcnse	Display the License Information window.
SHOWOK^%mdlcnse	Display the License Information window with OK button.
SRCHPAT^%msc	Convert search pattern to M pattern.
TSPC^%msv	Determine total space in a VG.
TYPE^%msv	Return type of a database.
UCINAME^%msu	Determine UCI,VG names from internal number.
UCINUM^%msu	Determine internal number for a UCI,VG.
UNMOUNT^%msv	Unmount a VG.
UNMOUNTM^%msv	Unmount a VG specified by moniker.
VALUE^%mprof	Return value of a registry entry for the current user.
VALUE^%mmprof	Return value of a registry entry for the local machine.
VALUE^%mreg	Return value of a registry entry from anywhere in the registry.
VARNAME^%msc	Determine value-added reseller name.
VT100^%msc	Reset F1-F5 for VT100/200.
VT420^%msc	Reset F1-F5 for VT420.
W^%msgbox	Display a Warning message box.
YN^%msgbox	Display a Yes/No message box.
YNC^%msgbox	Display a Yes/No/Cancel message box.


Service Routines by Function

Host Files

License Information

Message Box

Miscellaneous

Registry

Routine Paths

Server Dialogs

UCIs and Monikers

Volume Groups


Host Files

Entry Point	Description
OPEN^%mdfile	Display the Open File dialog box.
SAVE^%mdfile	Display the Save File dialog box.


License Information

Entry Point	Description
DESTROY^%mdlcnse	Remove a license information window.
INFO^%mdlcnse	Retrieve license and version information.
SHOW^%mdlcnse	Display the License Information window.
SHOWOK^%mdlcnse	Display the License Information window with OK button.


Message Box

Entry Point	Description
ARI^%msgbox	Display an Abort/Retry/Ignore message box.
E^%msgbox	Display an Error message box.
I^%msgbox	Display an Info message box.
OK^%msgbox	Display an OK message box.
RC^%msgbox	Display a Retry/Cancel message box.
W^%msgbox	Display a Warning message box.
YN^%msgbox	Display a Yes/No message box.
YNC^%msgbox	Display a Yes/No/Cancel message box.


Service Routines - Service Routines by Function - Miscellaneous
Miscellaneous

Entry Point	Description
APPEXE^%msc	Return the path to the application's .EXE file.
APPNAME^%msc	Retrieve the application name.
CHGKEY^%msc	Change the string generated by a function key.
DRVSPC^%msc	Determine the free space on a drive.
LOADXC^%msc	Load an Xcall package.
MSG^%msc	Return text for message or error code
OPEN^%msc	Open a host file.
PDEV^%msc	Reset the principal device.
QQ^%msc	Double quotes in a string.
SRCHPAT^%msc	Convert search pattern to M pattern.
VARNAME^%msc	Determine value-added reseller name.
VT100^%msc	Reset F1-F5 for VT100/200.
VT420^%msc	Reset F1-F5 for VT420.


Registry

Entry Point	Description
DELENTRY^%mprof	Delete registry entry for the current user.
DELENTRY^%mmprof	Delete a registry entry for the local machine.
DELSECT^%mprof	Delete registry section for the current user.
DELSECT^%mmprof	Delete registry section for the local machine.
GETENTRY^%mprof	Retrieve one or more registry entries for the current user.
GETENTRY^%mmprof	Retrieve one or more registry entries for the local machine.
GETENTRY^%mreg	Retrieve one or more registry entries from anywhere in the registry.
GETNAMES^%mprof	Retrieve registry entry names in a section for the current user.
GETNAMES^%mmprof	Retrieve registry entry names in a section for the local machine.
GETNAMES^%mreg	Retrieve registry entry names from anywhere in the registry.
GETSECT^%mprof	Retrieve all registry entries in a section for the current user.
GETSECT^%mmprof	Retrieve all registry entries in a section for the local machine.
GETSECT^%mreg	Retrieve all registry entries in a section from anywhere in the registry.
SETENTRY^%mprof	Set a registry entry for the current user.
SETENTRY^%mmprof	Set a registry entry for the local machine.
SETSECT^%mprof	Set multiple registry entries for the current user.
SETSECT^%mmprof	Set multiple registry entries for the local machine.
VALUE^%mprof	Return value of a registry entry for the current user.
VALUE^%mmprof	Return value of a registry entry for the local machine.
VALUE^%mreg	Return value of a registry entry from anywhere in the registry.


Routine Paths

Entry Point	Description
LIST^%msrpath	Retrieve current routine search path.
PATH^%msrpath	Set routine search path.
RESET^%msrpath	Set traditional routine path environment.


Server Dialogs

Entry Point	Description
SELECT^%mdserv	Display Select Server dialog.


UCIs and Monikers

Entry Point	Description
CHKUCI^%msu	Check if UCI valid.
CHKUCIVG^%msu	Determine UCI,VG names and numbers.
CHKUV^%msu	Check if UCI,VG name valid.
CHNGUCI^%msu	Change current UCI,VG.
CURNTUCI^%msu	Determine current UCI,VG.
EXISTUCI^%msu	Determine if UCI,VG currently available.
LIST^%msu	Retrieve list of UCIs in a VG.
MONIKER^%msu	Determine monikers associated with a UCI,VG.
UCINAME^%msu	Determine UCI,VG names from internal number.
UCINUM^%msu	Determine internal number for a UCI,VG.


Volume Groups

Entry Point	Description
BIJFMT^%msv	Create and format a new BIJ file.
BIJSIZE^%msv	Determine recommended size for a BIJ file.
CREATE^%msv	Create a new database.
DISTRAN^%msv	Disable global translation.
ENTRAN^%msv	Enable global translation.
EXPAND^%msv	Expand a mounted database.
FREESP^%msv	Return free space in a VG.
FSPC^%msv	Determine free space in a VG.
HOSTNAME^%msv	Determine host file name of a database from the VG.
HOSTVOL^%msv	Determine VG of a database from the filename.
INDEX^%msv	Determine VG index from VG name.
LIST^%msv	Retrieve list of mounted VG names and numbers.
LISTU^%msv	Retrieve list of mounted VGs, UCIs, and monikers.
LMOUNT^%msv	Mount a local VG.
MMOUNT^%msv	Mount an in-memory VG.
MOUNT^%msv	Mount a local or remote VG.
NAME^%msv	Determine VG name from VG index.
RMOUNT^%msv	Mount a remote VG.
RO^%msv	Determine if VG is read-only.
TSPC^%msv	Determine total space in a VG.
TYPE^%msv	Return type of a database.
UNMOUNT^%msv	Unmount a VG.
UNMOUNTM^%msv	Unmount a VG specified by moniker.


Service Routines - Service Routines
Service Routines

OPEN^%mdfile

SAVE^%mdfile

DESTROY^%mdlcnse

INFO^%mdlcnse

SHOW^%mdlcnse

SHOWOK^%mdlcnse

ARI^%msgbox

E^%msgbox

I^%msgbox

W^%msgbox

OK^%msgbox

RC^%msgbox

YN^%msgbox

YNC^%msgbox

APPEXE^%msc

APPNAME^%msc

CHGKEY^%msc

DRVSPC^%msc

LOADXC^%msc

MSG^%msc

OPEN^%msc

PDEV^%msc

QQ^%msc

SRCHPAT^%msc

VARNAME^%msc

VT100^%msc

VT420^%msc

DELENTRY^%mprof

DELSECT^%mprof

GETENTRY^%mprof

GETNAMES^%mprof

GETSECT^%mprof

SETENTRY^%mprof

SETSECT^%mprof

VALUE^%mprof

DELENTRY^%mmprof

DELSECT^%mmprof

GETENTRY^%mmprof

GETNAMES^%mmprof

GETSECT^%mmprof

SETENTRY^%mmprof

SETSECT^%mmprof

VALUE^%mmprof

GETENTRY^%mreg

GETNAMES^%mreg

GETSECT^%mreg

VALUE^%mreg

PATH^%msrpath

LIST^%msrpath

RESET^%msrpath

SELECT^%mdserv

CHKUCI^%msu

CHKUCIVG^%msu

CHKUV^%msu

CHNGUCI^%msu

CURNTUCI^%msu

EXISTUCI^%msu

LIST^%msu

MONIKER^%msu

UCINAME^%msu

UCINUM^%msu

BIJFMT^%msv

BIJSIZE^%msv

CREATE^%msv

DISTRAN^%msv

ENTRAN^%msv

EXPAND^%msv

FREESP^%msv

FSPC^%msv

HOSTNAME^%msv

HOSTVOL^%msv

INDEX^%msv

LIST^%msv

LISTU^%msv

LMOUNT^%msv

MMOUNT^%msv

MOUNT^%msv

NAME^%msv

RMOUNT^%msv

RO^%msv

TSPC^%msv

TYPE^%msv

UNMOUNT^%msv

UNMOUNTM^%msv


OPEN^%mdfile

Example

Displays the host operating system Open File dialog box. Returns a value indicating which button was pressed or returns an error code.

Syntax

OPEN^%mdfile(FILE,DIR,Filters,Flags,Ext,Title)

Parameter	Type	Description
FILE	Input-Output	A reference to a variable for the filename.
DIR	Input-Output	A reference to a variable for the directory name.
Filters	Input	A string used to limit accessible file types.
Flags	Input	A string of options.
Ext	Input	The default file extension.
Title	Input	The window title.
Description

The FILE parameter determines the default file name. The parameter returns a file name or multiple vertical bar-delimited filenames. Multiple filenames cannot be specified as the input value of this parameter.

The DIR parameter determines the default directory. The drive and directory are returned in this parameter in the format Drive:Directory, or as a UNC identifier. The trailing "\" character is included.

The Filters parameter is a string of vertical bar-delimited filter-pairs in which each filter-pair consists of:

FilterPair = Description|Pattern;Pattern...

The default FilterPair (the choice initially presented in the List Files of Type box), is preceded by the "_" character. For example:

  "_Documents (*.doc;*.txt)|*.doc;*.txt|All Files (*.*)|*.*"

The Flags parameter is a string of comma-delimited flag codes. The string contains zero or more of the following codes.

Flags parameter codes

Code	Description
CC	Confirm create; prompt: "OK to create?" if the file does not exist.
FX	File must exist.
NN	No network button (affects old-style Windows file dialogs only).
HR	Hide Read-only check box.
MS	Multiple selection allowed.
PP	Preserve path; do not change the current path.
PX	Path must exist.
RO	Read-only box initially selected.
The Ext parameter is the default extension added to the file name if none is provided by the user.

The Title parameter is the caption for the window. The default is Open.

The return code differs from the standard return code conventions used by service routines.  The return code is one of the following values.

Return codes

Code	Description
-nn	Internal error occurred (for example, invalid parameter). Details may be provided in %MERR. Otherwise, the positive value nn represents an error value from the underlying Windows dialog.
0	CANCEL pressed.
1	OK pressed.
2	OK pressed and Read-only selected.


Because the SAVE entry point takes exactly the same form of parameters as the OPEN entry, this example includes only the open dialog.

Two variables will be passed by-reference to the function, receiving the details entered by the user. Although they can be pre-loaded on entry, they are left null in this example:

SET (FILE,DIR)=""

A filter list defines the options for filename filtering that will be available to the user. Each option is defined by two pieces; the text and the pattern. The default filter is marked by a leading underline character on the text:

SET FILTERS="_Text Files|*.txt;*.ini|All Files|*.*"

Flags control aspects of the dialog behavior. In this example, the read-only check box is hidden, the entered filename is required to match an existing file, and the original path is reset after completion if the user browsed to another directory.

SET FLAGS="HR,FX,PP"

The function now is called, and a title is specified for the dialog. Two parameters are passed by-reference:

SET TITLE="Choose File to View"

SET RESULT=$$OPEN^%mdfile(.FILE,.DIR,FILTERS,FLAGS,"",TITLE)

If the user pressed OK, then RESULT is 1, FILE contains the filename selected by the user, and DIR gives the full path to the file, including trailing backslash. If CANCEL was pressed, RESULT is 0.

Two other types of return value are possible. A value of 2 indicates that the read-only check box was set (this is not possible in this example, because the box is hidden). A negative value indicates a failure of the service routine, such as an unrecognized flag. More information may be present in the variable %MERR.


SAVE^%mdfile

Displays the host operating system Save File dialog box.  Returns a value indicating which button was pressed or returns an error code.

Syntax

SAVE^%mdfile(FILE,DIR,Filters,Flags,Ext,Title)

Parameter	Type	Description
FILE	Input-Output	A reference to a variable for the filename.
DIR	Input-Output	A reference to a variable for the directory name.
Filters	Input	A string used to limit accessible file types.
Flags	Input	A string of options.
Ext	Input	The default file extension.
Title	Input	The window title.
Parameters

The FILE parameter determines the default file name. The parameter returns a file name or multiple vertical bar-delimited filenames. Multiple filenames cannot be specified as the input value of this parameter.

The DIR parameter determines the default directory. The drive and directory are returned in this parameter in the format Drive:Directory, or as a UNC identifier. The trailing "\" character is included.

The Filters parameter is a string of vertical bar-delimited filter-pairs in which each filter-pair consists of:

FilterPair = Description|Pattern;Pattern...

The default FilterPair (the choice initially presented in the List Files of Type box), is indicated by an initial character of "_". For example:

  "_Documents (*.doc;*.txt)|*.doc;*.txt|All Files (*.*)|*.*"

The Flags parameter is a string of comma-delimited flag codes. The string contains zero or more of the following codes.

Flags parameter codes

Code	Description
CO	Confirm overwrite; prompt: "OK to overwrite?" if the file exists.
NN	No network button (affects old-style Windows file dialogs only).
HR	Hide Read-only check box.
MS	Multiple selection allowed.
PP	Preserve path; do not change the current path.
PX	Path must exist.
RO	Read-only box initially selected.
The Ext parameter is the default extension added to the file name if none is provided by user.

The Title parameter is the caption for the window. The default is Save As.

The return code differs from the return code conventions used by service routines.

The return code is one of the following values.

Return codes

Code	Description
-nn	Internal error occurred (for example, invalid parameter). Details may be provided in %MERR. Otherwise, the positive value nn represents an error value from the underlying Windows dialog.
0	CANCEL pressed.
1	OK pressed.
2	OK pressed and Read-only selected.


DESTROY^%mdlcnse

See also

Removes a license information window displayed using SHOW^%mdlcnse. Returns success or failure.

Syntax

DESTROY^%mdlcnse(WinName)

Parameter	Description
WinName	The name of the window created by SHOW^%mdlcnse.


INFO	SHOW	SHOWOK


INFO^%mdlcnse

See also

Retrieves license and version information.  Returns success or failure.

Syntax

INFO^%mdlcnse(OUT)

Parameter	Type	Description
OUT	Output	A reference to a variable to hold the information.
Description

The INFO entry point sets into nodes of the OUT array licensing and other properties of the executable.  Some nodes may be undefined.  Nodes that may be returned include the following.

Nodes returned in the output array

Node	Description
APPNAME	Application name.
CREATED	Creation date and time.
DEMO	TRUE if the application was built as a demonstration.
DISPLIC	TRUE if license information is to be displayed.
EXPIRES	Expiration date, if any.
LICTYPE	Type of license being used ("Internal" or "External").
SN	Micronetics license serial number.
USERNAME	Username of external license.
VARNAME	VAR name. From external license if this is being used, else name of VAR that created the application.
VERSION	Application version, format:  major.minor.revision description, Build buildnumber.


DESTROY	SHOW	SHOWOK


SHOW^%mdlcnse

See also

Displays the License Information window and leaves it on the screen.  Returns success or failure.

Syntax

SHOW^%mdlcnse(WINNAME)

Parameter	Type	Description
WINNAME	Output	The name of the window used to display license information.
Description

The SHOW entry point displays a license information window, and returns in WINNAME the name of the window used.  The developer must pass this name to DESTROY to remove the window.


DESTROY	INFO	SHOWOK


SHOWOK^%mdlcnse

See also

Displays the License Information window with an OK button on it so the user can dismiss the window. Returns success or failure.

Syntax

SHOWOK^%mdlcnse()

No parameters.


DESTROY	INFO	SHOW


ARI^%msgbox

Displays a message box with ABORT, RETRY, and IGNORE buttons.  Returns a value indicating which button was clicked.

Syntax

ARI^%msgbox(Text,Title,HelpFile,HelpContext,Default,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Default	Default button. 1 for Abort, 2 for Retry, 3 for Ignore. Optional, default is 1.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The ABORTRETRYIGNORE message box displays the warning icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help.  The ABORT button is the default.

The Windows sound called Question also is produced.

The return code is one of the following values.

Return codes

Code	Description
A	Abort was pressed.
R	Retry was pressed.
I	Ignore was pressed.


E^%msgbox

Displays an ERROR message box with an OK button.  The return value (always 1) can be ignored.

Syntax

E^%msgbox(Text,Title,HelpFile,HelpContext,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The ERROR message box displays the error icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help. The entry point can be called as a procedure or as an extrinsic function.

The Windows sound called Critical Stop is also produced.


I^%msgbox

Displays an INFO message box with an OK button.  The return value (always 1) can be ignored.

Syntax

I^%msgbox(Text,Title,HelpFile,HelpContext,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The INFORMATION message box displays the information icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help.  The entry point can be called as a procedure or as an extrinsic function.

The Windows sound called Asterisk is also produced.


W^%msgbox

Displays a WARNING message box with an OK button.  The return value (always 1) can be ignored.

Syntax

W^%msgbox(Text,Title,HelpFile,HelpContext,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The WARNING message box displays the warning icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help.  The entry point can be called as a procedure or as an extrinsic function.

The Windows sound called Exclamation is also produced.


OK^%msgbox

Displays a message box with OK and CANCEL buttons. Returns a value indicating the button clicked.

Syntax

OK^%msgbox(Text,Title,HelpFile,HelpContext,Default,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Default	Default button. 1 for OK, 2 for Cancel. Optional, default is 1.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The OK message box displays the query icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help. The OK button is the default.

The Windows sound called Question also is produced.

The return code is one of the following values.

Return codes

Code	Description
1	OK was pressed.
0	CANCEL was pressed.


RC^%msgbox

Displays a message box with RETRY and CANCEL buttons.  Returns a value indicating which button was clicked.

Syntax

RC^%msgbox(Text,Title,HelpFile,HelpContext,Default,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Default	Default button. 1 for Retry, 2 for Cancel. Optional, default is 1.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The RETRYCANCEL message box displays the query icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help.  The YES button is the default.

The Windows sound called Question also is produced.

The return code is one of the following values.

Return codes

Code	Description
R	Retry was pressed.
C	Cancel was pressed.


YN^%msgbox

Displays a message box with YES and NO buttons.  Returns a value indicating the button clicked.

Syntax

YN^%msgbox(Text,Title,HelpFile,HelpContext,Default,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Default	Default button. 1 for Yes, 2 for No. Optional, default is 1.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The YESNO message box displays the query icon and the specified text and title. A help file name and a help file index can be supplied to support context-sensitive help. The YES button is the default.

The Windows sound called Question is also produced.

The return code is one of the following values.

Return codes

Code	Description
1	YES was pressed.
N	NO was pressed.


YNC^%msgbox

Displays a message box with YES, NO, and CANCEL buttons.  Returns a value indicating which button was clicked.

Syntax

YNC^%msgbox(Text,Title,HelpFile,HelpContext,Default,Parent)

Parameter	Description
Text	The text displayed in the message box.
Title	The message box title.  Optional, default is the application name.
HelpFile	The name of the associated help file.  Optional.
HelpContext	The help topic index in the associated help file.  Optional.
Default	Default button. 1 for Yes, 2 for No, 3 for Cancel. Optional, default is 1.
Parent	The name of a window in ^$WINDOW that is to be the parent of the message box. If null or invalid, the message box has no parent. Optional, default is the window currently having focus.
Description

The YESNOCANCEL message box displays the query icon and the specified text and title. A help file name and context can be supplied to support context-sensitive help.  The YES button is the default.

The Windows sound called Question also is produced.

The return code is one of the following values.

Return codes

Code	Description
1	YES was pressed.
N	NO was pressed.
C	Cancel was pressed.


APPEXE^%msc

Returns the full path to the application's .EXE file.

Syntax

APPEXE^%msc

Must be called as an extrinsic function. Takes no parameters.


APPNAME^%msc

Retrieves the value of the application name string (defined when the executable is created).  Returns success or failure.

Syntax

APPNAME^%msc(APPNAME)

Parameter	Type	Description
APPNAME	Output	A reference to the variable that receives the application name.


CHGKEY^%msc

Changes the string generated by a function key in the current console window.  Returns success or failure.

Syntax

CHGKEY^%msc(Key,Value,Clear,Lock)

Parameter	Description
Key	A reference to the function key to be reprogrammed, in format [SHIFT+][ALT+]Fn, where n = 1 to 12.
Value	A string containing the value to be generated by the key.
Clear	Clear all function keys first?  0=yes, 1=no.  Optional, default=1.
Lock	Lock all function keys against reprogramming?  0=yes, 1=no.  Optional, default=1.
The console window device must be the current device, as reported in $IO.


DRVSPC^%msc

Determines the amount of free space on a specified drive in 1-Kbyte blocks.  Returns success or failure.

Syntax

DRVSPC^%msc(Drive,BLOCKS)

Parameter	Type	Description
Drive	Input	A drive letter.
BLOCKS	Output	A reference to the variable that receives the free-space value.


LOADXC^%msc

Loads an XCALL package.  Returns success or failure.

Syntax

LOADXC^%msc(File)

Parameter	Description
File	Fully-qualified name of a host file containing an XCALL package to be loaded.


MSG^%msc

Returns text for an error code or message.

Syntax

MSG^%msc(Error,Param1,…,Param9)

Parameter	Description
Error	Code or message to interpret. See below for formats. Defaults to %MERR if that variable exists, else to the current error code from $ZERROR.
Param1-9	Optional fill-in values to substitute in place of %1 to %9 within the message text.
The Error parameter can be one of the following formats.

Error parameter formats

Format	Description	Example
i:j	major:minor error numbers	4:1
<xxxxx>	MSM error code	<UNDEF>
n	Windows error code, often negative	-2147024829
xxxxx	Service routine error code, generally obtained from %MERR	PARMREQ~File~OPEN+16^%msc`
anytext	First `-delimited piece is processed, as follows: First ~-delimited piece is the message, optionally containing fill-in positions marked by %1, %2, …, %9. Subsequent ~-delimited pieces specify fill-in values which take precedence over any fill-in values passed in as Param1 to Param9.	Hello %1 world~MSM`ignored


OPEN^%msc

Opens a host file.  Returns success or failure.

Syntax

OPEN^%msc(File,Mode,DEV,RecFmt)

Parameter	Type	Description
File	Input	A fully-qualified host file name.
Mode	Input	An access mode identifier (R = read-only, W = write-only, M = mixed (read/write)).
DEV	Output	A reference to the variable that receives the device number.
RecFmt	Input	A double-byte host-file format (K = JIS90, J = Shift-JIS,  T = Transparent, X = EUC). If passed, it is used as Opt5 on the OPEN. Defaults to T, which is the only format supported on single-byte versions of MSM-Workstation.


PDEV^%msc

Resets the principal device. For example, when running legacy applications in a console window, allows U 0 in legacy code to work correctly.  Returns success or failure.

Syntax

PDEV^%msc(Device)

Parameter	Description
Device	The device number that is to be the principal device. Valid values are 1 and 31-37 for console window devices, and 11-18 for COM ports 1-8.


QQ^%msc

Doubles up quotes in a string.

Syntax

QQ^%msc(Str)

Parameter	Type	Description
Str	Input or Input-Output	The string that is to have double quotes.
Note  This entry point may be called as an extrinsic and return the quoted string as the function value, or may pass an argument by-reference.


SRCHPAT^%msc

Returns an M pattern to evaluate a search string using * (zero or more characters) and ? (one character) wild cards, or, if given a range indicated with "-", returns 1 and sets the range end-points in output parameters. Must be called as an extrinsic function.

Syntax

SRCHPAT^%msc(Srch,FIRST,LAST)

Parameter	Type	Description
Srch	Input	A search pattern, which can include ?,*, and -.
FIRST	Output	The first valid selection of a range.
LAST	Output	The last valid selection of a range.


VARNAME^%msc

Allows the value of the value-added reseller name string (defined when the executable is created) to be determined. This function is used, for example, to display the VAR name on the splash screen.  Returns success or failure.

Syntax

VARNAME^%msc(VARNAME)

Parameter	Type	Description
VARNAME	Output	A reference to the variable that receives the VARNAME value.


VT100^%msc

Resets F1 to F5 for VT100/VT200 values.  Returns success or failure.

Syntax

VT100^%msc()

No parameters.


VT420^%msc

Resets F1 to F5 for VT420 values.  Returns success or failure.

Syntax

VT420^%msc()

No parameters.


DELENTRY^%mprof

See also

Deletes an entry from the current user registry section.  Returns success or failure.

Syntax

DELENTRY^%mprof(Section,Entry)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name to be deleted, or if "" then it will remove the '(Default)' entry.
Example

Delete the entry 'Entry':

S ret=$$DELENTRY^%mprof("Section","Entry")

from the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


DELSECT^%mprof

See also

Deletes an entire section from the current user registry section and any subsections it may have.  Returns success or failure.

Syntax

DELSECT^%mprof(Section)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Example

Remove the whole registry section:

S ret=$$DELENTRY^%mprof("Section")

from under the key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


GETENTRY^%mprof

See also

Retrieves value of one or more entries from the current user registry.  Returns success or failure.

Syntax

GETENTRY^%mprof(Section,Entry,VALUE,Default)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
Entry	Input	An entry name, or "" for all entries except the '(Default)' registry entry. To get the '(Default)' entry use VALUE^%mprof.
VALUE	Output	An entry value, or for all entries an array in format VALUE(Entry)=value.
Default	Input	The value to return if the entry does not exist. Default is "".
Examples

Return in the variable VAL the value of the entry name 'Entry':

S ret=$$GETENTRY^%mprof("Section","Entry",.VAL,"Default")

from under the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If there is no entry for 'Entry' then VAL="Default" as this was the default value passed into the function.  If it succeeds then 'ret' is zero, any other value indicates that the function call failed.

Return the complete list of entries except the '(Default)' entry:

S ret=$$GETENTRY^%mprof("Section\Subsection","",.VAL)

from under the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section\Subsection

Values are returned in the variable VAL subscripted by the entry name. For example it may look like:

VAL("Position")="100,100,ZDLG"

VAL("Size")="200,100,ZDLG"

if this registry key has 'Position' and 'Size' entries.


Registry Information


GETNAMES^%mprof

See also

Retrieves a list of registry entry names in the current user registry section. The return values are placed in the local subscripted variable identified as NAMES.  Returns success or failure.

Syntax

GETNAMES^%mprof(Section,NAMES)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'; may be null to get top-level section names.
NAMES	Output	A list of entry names as NAME(Entry)="".
Example

Return the list of entry names at the base level in VAL:

S ret=$$GETNAMES^%mprof("",.VAL)

That is, the entries are at:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>

If it succeeds 'ret' is zero, any other value indicates that the function call failed.


Registry Information


GETSECT^%mprof

See also

Retrieves all the registry entries in a current user registry section. Returns success or failure. This is the same as calling GETENTRY^%mprof and passing the 'Entry' value as "".

Syntax

GETSECT^%mprof(Section,VALUE)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
VALUE	Output	List of entry values, in format VALUE(Entry)=value except for the '(Default)' registry entry.
Example

Return all entries:

S ret=$$GETSECT^%mprof("Section\Subsection",.VAL)

from the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section\Subsection

in the variable VAL. If this section has two entries called 'Position' and 'Size' then VAL would look like:

VAL("Position") = "30,40,ZDLG"

VAL("Size") = "50,40,ZDLG".

If it succeeds then 'ret' is zero, any other value indicates the function call failed.


Registry Information


SETENTRY^%mprof

See also

Sets a current user registry section entry to a specified value. Returns success or failure.

Syntax

SETENTRY^%mprof(Section,Entry,Value)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name to be set. If "" then it will set the '(Default)' registry entry.
Value	Value to set.
Examples

Set the entry name 'Entry' with a value of 'Value':

S ret=$$SETENTRY^%mprof("Section","Entry","Value")

into the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates the function call failed.

Set the '(Default)' entry to the value 'Test' for the above registry key:

S ret=$$SETENTRY^%mprof("Section","","Test")


Registry Information


SETSECT^%mprof

See also

Sets multiple current user registry entries to specified values.  Returns success or failure.

Syntax

SETSECT^%mprof(Section,VALUE)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
VALUE	Input	The value of each entry to be set, in format VALUE(Entry)=value.
Example

Set the entry 'One' to the value '1' and the entry 'Last' to the value 'End':

S VAL("One")=1,VAL("Last")="End"

S ret=$$SETSECT^%mprof("Section",.VAL)

in the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


VALUE^%mprof

See also

Returns the value of a current user registry entry.

Syntax

VALUE^%mprof(Section,Entry,Default)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name. If "" then return the value of the '(Default)' registry entry.
Default	The value to return if the entry does not exist.
Examples

Return the value of the entry 'Entry':

S value=$$VALUE^%mprof("Section","Entry","Default")

in the registry key:

HKEY_CURRENT_USER\Software\<VarName>\<AppName>\Section

If there is no such value it will return "Default":

Return the value of the '(Default)' entry in the registry key listed above. If there is no such value return "":

S value=$$VALUE^%mprof("Section","")


Registry Information


DELENTRY^%mmprof

See also

Deletes an entry from the local machine registry section.  Returns success or failure.

Syntax

DELENTRY^%mmprof(Section,Entry)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name to be deleted, or if "" then it will remove the '(Default)' entry.
Example

Delete the entry 'Entry':

S ret=$$DELENTRY^%mmprof("Section","Entry")

from the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


DELSECT^%mmprof

See also

Deletes an entire local machine registry section and any subsections it may have.  Returns success or failure.

Syntax

DELSECT^%mmprof(Section)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Example

Remove the whole registry section:

S ret=$$DELENTRY^%mmprof("Section")

under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


GETENTRY^%mmprof

See also

Retrieves value of one or more local machine registry entries.  Returns success or failure.

Syntax

GETENTRY^%mmprof(Section,Entry,VALUE,Default)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
Entry	Input	An entry name, or "" for all entries except the '(Default)' registry entry. To get the '(Default)' entry use VALUE^%mmprof.
VALUE	Output	An entry value, or for all entries an array in format VALUE(Entry)=value.
Default	Input	The value to return if the entry does not exist. Default is "".
Examples

Return the value of the entry name 'Entry':

S ret=$$GETENTRY^%mmprof("Section","Entry",.VAL,"Default")

from the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

in the variable VAL=<Value>. If there is no entry for 'Entry' then VAL="Default" as this was the default value passed into the function.  If it succeeds then 'ret' is zero, any other value indicates that the function call failed.

Return the complete list of entries except the '(Default)' entry:

S ret=$$GETENTRY^%mmprof("Section\Subsection","",.VAL)

from the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section\Subsection

in the variable VAL subscripted by the entry name. For example it may return:

VAL("Position")="100,100,ZDLG"

VAL("Size")="200,100,ZDLG"

if this registry key has 'Position' and 'Size' entries.


Registry Information


GETNAMES^%mmprof

See also

Retrieves a list of local machine registry entry names in a section. The return values are placed in the local subscripted variable identified as NAMES.  Returns success or failure.

Syntax

GETNAMES^%mmprof(Section,NAMES)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'; may be null to get top-level section names.
NAMES	Output	A list of entry names as NAME(Entry)="".
Example

Return the list of entry names at the base level in VAL:

S ret=$$GETNAMES^%mmprof("",.VAL)

that is at:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>

If it succeeds 'ret' is zero, any other value indicates that the function call failed.


Registry Information


GETSECT^%mmprof

See also

Retrieves all the local machine registry entries in a section. Returns success or failure. This is the same as calling GETENTRY^%mmprof and passing the 'Entry' value as "".

Syntax

GETSECT^%mmprof(Section,VALUE)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
VALUE	Output	List of entry values, in format VALUE(Entry)=value except for the '(Default)' registry entry.
Example

Return in VAL all entries:

S ret=$$GETSECT^%mmprof("Section\Subsection",.VAL)

from the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section\Subsection

If this section has two entries called 'Position' and 'Size' then VAL would look like:

VAL("Position")="30,40,ZDLG"

VAL("Size")="50,40,ZDLG"

If it succeeds then 'ret' is zero, any other value indicates the function call failed.


Registry Information


SETENTRY^%mmprof

See also

Sets a local machine registry section entry to a specified value. Returns success or failure.

Syntax

SETENTRY^%mmprof(Section,Entry,Value)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name to be set. If "" then it will set the '(Default)' registry entry.
Value	Value to set.
Examples

Set the entry name 'Entry' with a value of 'Value':

S ret=$$SETENTRY^%mmprof("Section","Entry","Value")

into the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates the function call failed:

Set the '(Default)' entry to the value 'Test' for the above registry key:

S ret=$$SETENTRY^%mmprof("Section","","Test")


Registry Information


SETSECT^%mmprof

See also

Sets multiple local machine registry entries to specified values.  Returns success or failure.

Syntax

SETSECT^%mmprof(Section,VALUE)

Parameter	Type	Description
Section	Input	A section name; if multi-key, use delimiter '\'.
VALUE	Input	The value of each entry to be set, in format VALUE(Entry)=value.
Example

Set the entry 'One' to the value '1' and the entry 'Last' to the value 'End':

S VAL("One")=1,VAL("Last")="End"

S ret=$$SETSECT^%mmprof("Section",.VAL)

in the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

If it succeeds then 'ret' is zero, any other value indicates that the function call failed.


Registry Information


VALUE^%mmprof

See also

Returns the value of a local machine registry entry.

Syntax

VALUE^%mmprof(Section,Entry,Default)

Parameter	Description
Section	A section name; if multi-key, use delimiter '\'.
Entry	An entry name. If "" then return the value of the '(Default)' registry entry.
Default	The value to return if the entry does not exist, defaults to "" if not passed.
Examples

Return the value of the entry 'Entry':

S value=$$VALUE^%mmprof("Section","Entry","Default")

in the registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\<VarName>\<AppName>\Section

If there is no such value it will return "Default":

Returns the value of the '(Default)' entry in the registry key listed above. If there is no such value return "":

S value=$$VALUE^%mmprof("Section","")


Registry Information


GETENTRY^%mreg

See also

Retrieves value of one or more registry entries.  Returns success or failure.

Syntax

GETENTRY^%mreg(Section,Entry,VALUE,Default)

Parameter	Type	Description
Section	Input	The full path to a valid key in the registry. If the first piece of the key is not valid it will return an error code.
Entry	Input	An entry name, or "" for all entries including the '(Default)' registry entry.
VALUE	Output	An entry value, or for all entries an array in format VALUE(Entry)=value with VALUE equal to value of the '(Default)' entry.
Default	Input	The value to return if the entry does not exist. Default is "".
Example

Return the value (in the variable VAL) of the entry 'Content Type' from the registry for the entry that specifies the content type for a file that ends in .TXT:

S ret=$$GETENTRY^%mreg("HKEY_CLASSES_ROOT\.txt","Content Type",.VAL,"?")

This value is commonly VAL="text/plain". If there is no entry for 'Content Type' or the 'HKEY_CLASSES_ROOT\.txt' key does not exist, then VAL="?" as this was the default value passed into the function.  If it succeeds then 'ret' is zero, any other value indicates that the function call failed.

Return the complete list of entries for this registry key in the variable VAL subscripted by the entry name:

S ret=$$GETENTRY^%mreg("HKEY_CLASSES_ROOT\.txt ","",.VAL)

This will commonly return:

VAL="txtfile"

VAL("Content Type")="text/plain"

The VAL="txtfile" corresponds to the '(Default)' registry entry for this key.


Registry Information


GETNAMES^%mreg

See also

Retrieves a list of registry entry names in a section. The return values are placed in the local subscripted variable identified as NAMES.  Returns success or failure.

Syntax

GETNAMES^%mreg(Section,NAMES)

Parameter	Type	Description
Section	Input	The full path to a valid key in the registry. If the first piece of the key is not valid it will return an error code.
NAMES	Output	A list of entry names as NAME(Entry)="".
Example

Return the list of entry names for the registry entry associated with the file type .TXT:

S ret=$$GETNAMES^%mreg("HKEY_CLASSES_ROOT\.txt",.VAL)

This is commonly just VAL("Content Type")=""

If it succeeds 'ret' is zero, any other value indicates that the function call failed.


Registry Information


GETSECT^%mreg

See also

Retrieves all the registry entries in a section. Returns success or failure. This is the same as calling GETENTRY^%mreg and passing the 'Entry' value as "".

Syntax

GETSECT^%mreg(Section,VALUE)

Parameter	Type	Description
Section	Input	The full path to a valid key in the registry. If the first piece of the key is not valid it will return an error code.
VALUE	Output	List of entry values, in format VALUE(Entry)=value including the '(Default)' registry entry in VALUE.
Example

Return the set of entries from the registry associated the file type .TXT:

S ret=$$GETSECT^%mreg("HKEY_CLASSES_ROOT\.txt",.VAL)

This is commonly:

VAL="txtfile"

VAL("Content Type")="text/plain"

The VAL="txtfile" corresponds to the '(Default)' registry entry for this key.

If it succeeds then 'ret' is zero, any other value indicates the function call failed.


Registry Information


VALUE^%mreg

See also

Returns the value of a registry entry.

Syntax

VALUE^%mreg(Section,Entry,Default)

Parameter	Description
Section	The full path to a valid key in the registry. If the first piece of the key is not valid it will return an error code.
Entry	An entry name. If "" then return the value of the '(Default)' registry entry.
Default	The value to return if the entry does not exist.
Example

Return the value of the entry 'Content Type' from the registry for the entry that specifies the content type for a file that ends in .TXT:

S value=$$VALUE^%mreg("HKEY_CLASSES_ROOT\.txt","Content Type","?")

This value is commonly "text/plain". If there is no entry for 'Content Type' or the 'HKEY_CLASSES_ROOT\.txt' key does not exist then it returns "?" as this was the default value passed into the function.

Return the value of the '(Default)' entry in the registry for the file type .TXT:

S value=$$VALUE^%mreg("HKEY_CLASSES_ROOT\.txt","")

This is commonly "txtfile". If there is no such value it will return "".


Registry Information


PATH^%msrpath

See also

Specifies routine search paths.  Returns success or failure.

Syntax

PATH^%msrpath(INARGS)

Parameter	Type	Description
INARGS	Input	An array that contains input arguments.
Description

MSM-Workstation allows routine search paths to be established using %msrpath. Routine search paths provide a facility similar to the PATH facilities provided by operating systems such as DOS, UNIX, and Windows. A reference to an array of parameters is passed to the entry point PATH.  The parameters specify locations from which routines can be loaded and to which routines can be saved.

These features facilitate the operation of certain application types. For example, the Workstation development environment uses search paths to provide access to the read-only Workstation application routines as well as to routines produced by the developer.

The arguments are passed in an input array. Routine search paths may specify rules for % (library) routines and non-% routines.  There are two aspects of the routine search path which may be specified independently: the ZSAVE rule and the search path rule.

All UCIs must be local. When Workstation has mounted a server database, only  the UCI specified in the mount is treated as local. Globals in other UCIs on the server may be accessible using extended global references or global translation, but search paths cannot be used to gain access to routines in those UCIs.

PATH^%msrpath is passed a reference to an array containing input arguments, and returns a success code. For example:

S result=$$PATH^%msrpath(.INARGS)

Arguments are passed in an input array INARGS with the following structure.

INARGS(Type,"ZSRULE")=ZSaveRule

INARGS(Type,"PATH",Index)=SearchPathRule

Type

Routine search paths specify rules for % (library) routines and non-% routines. These are specified by the Type parameter:

Value	Description
P	Percent routines
N	Non-percent routines
Index

The Index specifies search order. Lower indexed rules are applied before higher rules.

ZSaveRule

The ZSaveRule must be set to one of the following values:

Value	Name	Description
0	Traditional	Traditional save rule.  Restricts a % routine to a library UCI.
1	Save in Current	Save in the UCI of the process issuing the ZSAVE command.
2;uv     or 2;moniker	Save in Explicit	Save in the specified explicit uciname,vgname or ucinum,vgnum or in the UCI to which moniker is bound.
3	Save in Load	Save in the UCI specified by the Save component of the Search path rule which located the routine being saved when it was previously ZLOADed.  An error occurs if that component is NoSave.  If no ZLOAD was previously issued, the first search path element is used.
4	Save in Execute	Save in the UCI specified by the Save component of the Search path rule which located the routine issuing the ZSAVE command.  An error occurs if that component is NoSave.   If no ZLOAD was previously issued, the first search path element is used.
SearchPathRule

The SearchPathRule is defined as follows:

SearchPathRule ::= Load;Save;Save Here Only

Load

Load must have one of the following values:

Value	Description
uv	uciname,vgname or ucinum,vgnum pair.
moniker	A moniker name.
Current	The string literal 'Current' indicates the current UCI.
Library	The string literal 'Library' indicates the library UCI.  This is only valid for paths of Type P (percent routines).
Save

Save must have one of the following values:

Value	Description
uv	uciname,vgname or ucinum,vgnum pair.
moniker	A moniker name.
NoSave	The string literal 'NoSave', used in conjunction with ZSaveRule values 3 or 4, indicates that when loaded using this search path rule the routine may not be saved (3) or save (4).
SaveHereOnly

When the SaveHereOnly flag is set to the value 1, a routine loaded using this Search path rule may only be saved in the UCI named in the Save component of the rule.  This flag is only checked if the ZSAVE rule is "Save in current" and the routine is being saved with the same name with which it was ZLOADed.

Note: all Workstation applications have additional N-type and P-type search path rules automatically placed ahead of any user-specified rules. These guarantee that the routines forming the application will always be located from its %App database.


LIST	RESET


LIST^%msrpath

See also

Retrieves the currently effective routine path entries.  Returns success or failure.

Syntax

LIST^%msrpath(LIST)

Parameter	Type	Description
LIST	Output	A reference to the local variable that receives the path entries.
Description

The path entries are returned in a local subscripted variable. The entries can be interpreted by-reference to the specification for the PATH entry point.

Note that all Workstation applications have additional N-type and P-type search path rules automatically placed ahead of any user-specified rules. These guarantee that the routines forming the application will always be located from its %App database.


PATH	RESET


RESET^%msrpath

See also

Restores a traditional routine path environment.  No return value.

Syntax

RESET^%msrpath

No parameters

Description

The system treats all % routines as to be sought in the library UCI for the current UCI; all other routines are sought in the current UCI.


PATH	LIST


SELECT^%mdserv

Displays a dialog for entry of server connection information. This information subsequently may be used as input for RMOUNT^%msv to perform the mount.

Syntax

SELECT^%mdserv(INARGS,OUTARGS)

Parameter	Type	Description
INARGS	Input	A reference to a variable that contains input arguments.
OUTARGS	Output	A reference to the array that is to contain output arguments.
Input Arguments

Input arguments are passed as the following nodes of INARGS().

Node	Description
IPADDRESS	Server's IP address, or SPX network^node address (optional).
LINKTYPE	TCPIP or SPX (default is TCPIP).
OPTIONAL	Mounting is optional, show "work locally."
PASSWORD	Password (optional).
PORT	Server port (optional).
UCINAME	Remote UCI name to mount (optional).
VGNAME	Remote volume name to mount (optional).
Output Arguments

Output arguments are returned as the following nodes of OUTARGS().

Node	Description
IPADDRESS	Server's IP address or SPX network^node address.
LINKTYPE	TCPIP or SPX (default is TCPIP).
PASSWORD	Password.
PORT	Server port.
UCINAME	Remote UCI name to mount.
VGNAME	Remote volume name to mount.
WORK_LOCALLY	True if user elected to work locally.


CHKUCI^%msu

See also

Returns true if parameter is a valid format for a UCI name or UCI,VOL name. This does not imply that such a UCI exists.

Syntax

CHKUCI^%msu(uci)

Parameter	Description
uci	uciname or uvname.
Note  A Boolean value is returned directly from this entry point, which should be invoked via $$.

For a description of parameters, refer to "Service Routine Conventions."


CHKUCIVG	CHKUV	CHNGUCI	CURNTUCI
EXISTUCI	LIST	MONIKER	UCINAME
UCINUM


CHKUCIVG^%msu

See also

Determines the uvname and the uvnum for the current UCI, for a uciname,vgname pair, for a ucinum,vgnum pair, or for a moniker.  If the specified UCI is not present in a local database, but is available to be mounted on the same server on which a remote database (UCI) is currently mounted, this function also unmounts the original remote database and reconnects to the new one. Returns success or failure.

Syntax

CHKUCIVG^%msu(uv, UVNAME,UVNUM)

Parameter	Type	Description
uv	Input	uci or uvname or or ucinum or uvnum or moniker.
UVNAME	Output	A reference to the variable that receives a uvname.
UVNUM	Output	A reference to the variable that receives a uvnum.
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUV	CHNGUCI	CURNTUCI
EXISTUCI	LIST	MONIKER	UCINAME
UCINUM


CHKUV^%msu

See also

Returns if true if parameter is a valid format for a UCI,VOL name. This does not imply that such a UCI,VOL exists.

Syntax

CHKUV^%msu(Uvname)

Parameter	Description
Uvname	UCI name, volume group name.
Note  A Boolean value is returned directly from this entry point, which should be invoked via $$.

For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHNGUCI	CURNTUCI
EXISTUCI	LIST	MONIKER	UCINAME
UCINUM


CHNGUCI^%msu

See also

Changes the current UCI and volume group.  Returns success or failure.

Syntax

CHNGUCI^%msu(Uci, Vg)

Parameter	Description
Uci	A UCI name or number, or a moniker.
Vg	A volume group name or number (optional, defaulting to current VG, or ignored if first parameter is a moniker).
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CURNTUCI
EXISTUCI	LIST	MONIKER	UCINAME
UCINUM


CURNTUCI^%msu

See also

Determines the current UCI and volume group name.  Returns success or failure.

Syntax

CURNTUCI^%msu(UVNAME)

Parameter	Type	Description
UVNAME	Output	UCI name, volume group name.
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
EXISTUCI	LIST	MONIKER	UCINAME
UCINUM


EXISTUCI^%msu

See also

Returns TRUE if a uci,vg is currently available.

Syntax

EXISTUCI^%msu(Uci, Vg)

Parameter	Description
Uci	A UCI name or number.
Vg	A volume group name or number.
Note  A Boolean value is returned directly from this entry point, which should be invoked via $$.

For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
CURNTUCI	LIST	MONIKER	UCINAME
UCINUM


LIST^%msu

See also

Retrieves the list of UCIs in a specified volume group.  Returns success or failure.

Syntax

LIST^%msu(Vg,LIST)

Parameter	Type	Description
Vg	Input	A volume group name or number  (optional, defaults to current VG)
LIST	Output	A reference to the variable that receives a list of UCIs.
Description

The returned list is formatted as follows:

LIST(ucinum)=uciname

For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
CURNTUCI	EXISTUCI	MONIKER	UCINAME
UCINUM


MONIKER^%msu

See also

Determines the moniker(s) associated with a specified UCI and volume group.   Returns success or failure.

Syntax

MONIKER^%msu(Uci,Vg,MON)

Parameter	Type	Description
Uci	Input	A UCI name or number.
Vg	Input	A volume group name or number.
MON	Output	A reference to the variable that receives a comma-delimited list of moniker names.
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
CURNTUCI	EXISTUCI	LIST	UCINAME
UCINUM


UCINAME^%msu

See also

Retrieves the UCI and VG names from an internal uci/vg number.  Returns success or failure.

Syntax

UCINAME^%msu(uvint,UCINAME,VGNAME)

Parameter	Type	Description
uvint	Input	The internal number uvint.
UCINAME	Output	A UCI name.
VGNAME	Output	A volume group name.
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
CURNTUCI	EXISTUCI	LIST	MONIKER
UCINUM


UCINUM^%msu

See also

Retrieves the internal UCI number from a UCI name or number. Returns success or failure.

Syntax

UCINUM^%msu(Uci,Vg,UVINT)

Parameter	Type	Description
Uci	Input	A UCI name or number.
Vg	Input	A volume group name or number.
UVINT	Output	The internal number uvint.
For a description of parameters, refer to "Service Routine Conventions."


CHKUCI	CHKUCIVG	CHKUV	CHNGUCI
CURNTUCI	EXISTUCI	LIST	MONIKER
UCINAME


BIJFMT^%msv

Creates and formats a new before-image journaling (BIJ) file. Returns success or failure.

Syntax

BIJFMT^%msv(Name,Size)

Parameter	Description
Name	A fully-qualified host file name (maximum of 64 characters).
Size	The host file size in 1-K blocks. Should not be less than the size returned by a call to BIJSIZE^%msv with the matching database file's size.
Note  Generally, applications do not call the BIJFMT entry point. It is provided as a convenience to the application developer, should a BIJ be inadvertently deleted.


BIJSIZE^%msv

Determines the recommended size of the before-image journaling (BIJ) file. Returns success or failure.

Syntax

BIJSIZE^%msv(DBSize,BIJSIZE)

Parameter	Type	Description
DBSize	Input	The database size used to calculate the BIJ file size.
BIJSIZE	Output	A reference to the variable that receives the BIJ file size.
Description

The BIJSIZE^%msv routine can be used to determine the total space required to create a new database. This information is useful when limited disk storage is available. The BIJ file size is calculated from the database size, which is passed to the entry point as a parameter.


CREATE^%msv

Creates a new database.  Returns success or failure.

Syntax

CREATE^%msv(INARGS)

Parameter	Type	Description
INARGS	Input	A reference to an array that contains input arguments.
Input Arguments

Input arguments are passed as these nodes of INARGS().

Node	Description
DBNAME	Fully-qualified host file name (maximum 64 characters).
DBSIZE	Database size (1-K blocks).
VGNAME	Volume group name.  Optional.
Description

The CREATE entry point allows databases to be created under program control. The host file name and database size must be specified.


DISTRAN^%msv

Disables global translation.  Returns success or failure.

Syntax

DISTRAN^%msv( )

No parameters

Description

The DISTRAN entry point replaces the equivalent function in the TRANSLAT utility, present in other MSM versions.


ENTRAN^%msv

Enables global translation.  Returns success or failure.

Syntax

ENTRAN^%msv(INARGS)

Parameter	Type	Description
INARGS	Input	A reference to an array of input parameters.
Description

Global translation permits global accesses made by a program executing in one database to be redirected to another database. Accesses that do not include an explicitly-specified database name (given between vertical bars immediately preceding the global name) are filtered through the global translation table, if one is enabled. The table entries are checked in sequence, and the first match causes redirection of the global access.

The ENTRAN entry point replaces the equivalent function in the TRANSLAT utility, present in other MSM versions. The entry point takes a translation specification. The translation specification differs from the format that is traditionally stored in the ^SYS global. In particular, UCI and volume group specifications are now eye-readable.

The format of the INARGS array is:

INARGS("TRANSLATE",Index) = Translation specification

The Index is significant in that it determines translation order. The table will be loaded in local array collating sequence, so indices 1 to n are recommended.  The pieces of the Translation specification are delimited by ^.  The pieces are listed and described in the following table.

Translation specification

Piece	Description
1	From-UCI name or moniker. Together with piece 2 this sets what the current UCI of the M process must be in order for this translation specification to be eligible for use.
2	From-VolumeGroup name, or blank if moniker used in piece 1.
3	To-UCI name or moniker. Together with piece 4 this specifies where a gobal is to be accessed if the translation specification is found to apply.
4	To-VolumeGroup name, or blank if moniker used in piece 3.
5	Lock-UCI name or moniker (default same as 3). Together with piece 6 this specifies where a gobal LOCK or ZALLOCATE operation is to be recorded if the translation specification is found to apply.
6	Lock-VolumeGroup name, or blank if moniker used in piece 5 (default same as 4).
7	Functions - sum of the following values:  1=enable translation; 4= enable lock translation (default=5).
8	Not applicable of Workstation. Leave null.
9	Collating sequence (NUMERIC or STRING) (defaults to NUMERIC). Specifies the sequence being used by the corresponding global in the To-UCI.
10	The global name. May include subscripts, or may end with *. Dictates which global(s), or which sub-tree of a single global, will be translated according to the other pieces of this specification.
11	Bits (7 or 8) (default 8). Specifies whether the corresponding global in the To-UCI is 7-bit or 8-bit.


EXPAND^%msv

Expands a mounted database.  Returns success or failure.

Syntax

EXPAND^%msv(Vg,Size)

Parameter	Description
Vg	A volume group name or number.
Size	The number of 1-K blocks by which to expand the volume group.
For a description of parameters, refer to "Service Routine Conventions."


FREESP^%msv

Returns the number of free 1-K blocks in a volume group, or returns -1 on failure.

Syntax

FREESP^%msv(Vg)

Parameter	Description
Vg	A volume group name or number.


FSPC^%msv

Determines the amount of free space in a volume group. Returns success or failure.

Syntax

FSPC^%msv(Vg, BLKS)

Parameter	Type	Description
Vg	Input	A volume group name or number.
BLKS	Output	A reference to the variable that receives the number of free blocks.
For a description of parameters, refer to "Service Routine Conventions."


HOSTNAME^%msv

Determines the host file name or server address of the database associated with a volume of a volume group.  Returns success or failure.

Syntax

HOSTNAME^%msv(Vg,Vol,HOSTNAME,PORT)

Parameter	Type	Description
Vg	Input	A volume group name or number.
Vol	Input	A volume number; the default is volume 0. Not applicable to remote databases.
HOSTNAME	Output	A reference to the variable that receives the HOSTNAME string.
PORT	Output	A reference to the variable that receives the PORT on which the server connection is established. Only defined for remote databases.
For a description of parameters, refer to "Service Routine Conventions."


HOSTVOL^%msv

Uses the host file name of a local mounted database to determine a volume group index and name.  Returns success or failure.

Syntax

HOSTVOL^%msv(Hname,VGNUM,VGNAME)

Parameter	Type	Description
Hname	Input	The fully-qualified host file name for database.
VGNUM	Output	A reference to the variable that receives the volume group number.
VGNAME	Output	A reference to the variable that receives the volume group name.
For a description of parameters, refer to "Service Routine Conventions."


INDEX^%msv

Uses a volume group name to determine the volume group index. Returns success or failure.

Syntax

INDEX^%msv(Vgname,VGNUM)

Parameter	Type	Description
Vgname	Input	A volume group name.
VGNUM	Output	A reference to a variable that contains the volume group number.
For a description of parameters, refer to "Service Routine Conventions."


LIST^%msv

Provides a list of mounted volume group names and numbers.  Returns success or failure.

Syntax

LIST^%msv(LIST,Type)

Parameter	Type	Description
LIST	Output	A reference to the variable that receives a list.
Type	Input	Volume group type (R=remote, L=local, null for all).  Optional.
Description

The returned list is formatted as follows:

LIST(vgnum)=vgname


LISTU^%msv

Provides a list of mounted volume groups and their associated UCIs and monikers.  Returns success or failure.

Syntax

LISTU^%msv(LIST,Type)

Parameter	Type	Description
LIST	Output	A reference to the variable that receives the list.
Type	Input	Volume group type (R=remote, L=local, null for all).  Optional.
Description

The returned list has sequential integer subscripts and has with the volume group name, UCI, and moniker as the data, formatted as follows:

LIST(n)=uciname,vgname|ucinum,vgnum|moniker,…


LMOUNT^%msv

Mounts a local database. Returns success or failure.

Syntax

LMOUNT^%msv(INARGS,OUTARGS)

Parameter	Type	Description
INARGS	Input	A reference to an array of input arguments.
OUTARGS	Output	A reference to an array that is to contain output arguments.
Input Arguments

Input arguments are passed as the following nodes of INARGS():

Node	Description
DBNAME	Fully-qualified host file name.
LOCAL_ACCESS	Access permissions (N = none, R = read-only, or M = mixed (read/write)) (optional).
MONIKER	Symbolic name for database (optional).
REMOTE_ACCESS	Not applicable to MSM-Workstation.
UCINAME	UCI with which to associate moniker (optional, defaults to first UCI).
VGNUM	Volume group number desired (optional).
Output Arguments

Output arguments are returned as the following nodes of OUTARGS():

Node	Description
VGNAME	A volume group name.
VGNUM	A volume group number.
Notes

When DBNAME is not specified, MONIKER must identify a moniker recorded in the application's registry entry, from which the host filename is determined. The volume group index and the volume group name of the mounted database are returned as output arguments.

When DBNAME identifies a database file created using compatible MSM products in which multi-UCI volume groups can be created, this mount operation makes all the UCIs available to Workstation. The moniker is only associated with the nominated UCI


MMOUNT^%msv

Mounts an in-memory database. Returns success or failure.

Syntax

MMOUNT^%msv(INARGS,OUTARGS)

Parameter	Type	Description
INARGS	Input	A reference to an array of input arguments.
OUTARGS	Output	A reference to an array that is to contain output arguments.
Input Arguments

Input arguments are passed as these nodes of INARGS():

Node	Description
BLOCKS	Size of the volume group (optional).  Default 100.
MONIKER	Symbolic name for database (optional).
VGNAME	Name to mount as (also sets UCI name).
VGNUM	Requested index for volume group (optional).
Output Arguments

Output arguments are returned as the following nodes of OUTARGS():

Node	Description
VGNAME	A volume group name.
VGNUM	A volume group number.
Description

An MSM-Workstation application is able to mount a special type of database, known as an "in-memory database". Like a regular local or network database, an in-memory database can store globals. However, it is created empty when it is mounted, and its contents are lost when it is unmounted, or when the application terminates.

For example, to create a 100-block database called MEM:

K in

S in("VGNAME")="MEM"

I $$MMOUNT^%msv(.in) Q

;

; The database has been created


MOUNT^%msv

Mounts a local, remote or in-memory database. Provides the volume group index and the volume group name of the mounted database as outputs.  Returns success or failure.  Combines functions of LMOUNT, RMOUNT, and MMOUNT in a single entry point.

Syntax

MOUNT^%msv(INARGS,OUTARGS)

Parameter	Type	Description
INARGS	Input	A reference to an array that contains input arguments.
OUTARGS	Output	A reference to the array that is to contain output arguments.
Input Arguments

Input arguments are passed as one of the following sets of nodes of INARGS().

Local Settings

Node	Description
DBNAME	Fully-qualified host file name.
LOCAL_ACCESS	Access permissions (N = none, R = read-only, or M = mixed (read/write)) (optional, default is M).
MONIKER	Symbolic name for database (optional).
REMOTE_ACCESS	Not applicable to MSM-Workstation.
UCINAME	UCI with which to associate moniker (optional).
VGNUM	Requested index for volume group (optional).
Remote Settings

Node	Description
IPADDRESS	Server's IP or net address.
LINKTYPE	Type of link. TCPIP or SPX (optional, default is TCPIP).
LOCAL_ACCESS	Access permissions (N = none, R = read-only, or M = mixed (read/write)) (optional, default is M).
MONIKER	Symbolic name for database (optional).
PASSWORD	Password.
PORT	Server port.
UCINAME	Remote UCI name to mount.
VGNAME	Remote volume name to mount.
Memory Settings

Node	Description
BLOCKS	Size of the volume group (optional).  Default 100.
MONIKER	Symbolic name for database (optional).
VGNAME	Name to mount as (also sets UCI name).
VGNUM	Requested index for volume group (optional).
Output Arguments

Output arguments are returned as the following nodes of OUTARGS().

Node	Description
LINKTYPE	TCPIP or SPX (remote mount only).
LOCAL_ACCESS	Access permissions granted (N = none, R = read-only, W = write-only, or M = mixed (read/write)) (remote mount only).
SERVER_JOB	Job number assigned on server (remote mount only).
VGNAME	A volume group name.
VGNUM	A volume group number.
Notes

When mounting a local database, if DBNAME is not specified then MONIKER must identify a moniker recorded in the application's registry entry, from which the host filename is determined. The volume group index and the volume group name of the mounted database are returned as output arguments.

When mounting a remote database, if IPADDRESS and PORT are not specified then MONIKER must identify a moniker recorded in the application's registry entry, from which the host filename is determined. The address and port are returned as output arguments.


NAME^%msv

Determines the name of a volume group from a volume group number. Returns success or failure.

Syntax

NAME^%msv(Vg,VGN)

Parameter	Type	Description
Vg	Input	A volume group name or number.
VGNAME	Output	A reference to the variable that is to contain a volume group name.
For a description of parameters, refer to "Service Routine Conventions."


RMOUNT^%msv

Mounts a remote database hosted by an MSM-Server system.  Returns success or failure.

Syntax

RMOUNT^%msv(INARGS,OUTARGS)

Parameter	Type	Description
INARGS	Input	A reference to a variable that contains input arguments.
OUTARGS	Output	A reference to the array that is to contain output arguments.
Input Arguments

Input arguments are passed as the following nodes of INARGS().

Node	Description
IPADDRESS	Server's IP or net address.
LINKTYPE	Type of link. TCPIP or SPX (optional, default is TCPIP).
LOCAL_ACCESS	Access permissions (N = none, R = read-only, or M = mixed (read/write)) (optional, default is M).
MONIKER	Symbolic name for database (optional).
PORT	Server port.
PASSWORD	Password.
UCINAME	Remote UCI name to mount.
VGNAME	Remote volume name to mount.
Output Arguments

Output arguments are returned as the following nodes of OUTARGS().

Node	Description
LINKTYPE	Type of link established. TCPIP or SPX.
LOCAL_ACCESS	Access permissions granted (N = none, R = read-only,  W = write-only, or M = mixed (read/write)).
SERVER_JOB	Job number assigned on server.
VGNAME	A volume group name.
VGNUM	A volume group number.
Notes

When mounting a remote volume group and IPADDRESS and PORT are not specified, MONIKER must identify a moniker recorded in the application's registry entry, from which the host filename is determined. The address and port are returned as output arguments.


RO^%msv

Determines whether a volume group is read-only or read/write. Returns success or failure.

Syntax

RO^%msv(Vg,RO)

Parameter	Type	Description
Vg	Input	A volume group name or number.
RO	Output	A reference to the variable that is to receive TRUE if the volume group is read-only.


TSPC^%msv

Determines the total amount of space in a volume group. Returns success or failure.

Syntax

TSPC^%msv(Vg,BLKS)

Parameter	Type	Description
Vg	Input	A volume group name or number.
BLKS	Output	A reference to the variable that is to receive the number of blocks.
For a description of parameters, refer to "Service Routine Conventions."


TYPE^%msv

Return the type of a database.

Syntax

TYPE^%msv(Vg)

Parameter	Type	Description
Vg	Input	A volume group name or number (defaults to current volume group).
The function returns the following values.

Value	Meaning
L	Local database.
M	In-memory database.
R	Remote database.
If there is no such database mounted, the function returns the null string.

Description

To determine the type of database, use the extrinsic function TYPE^%msv:

S type=$$TYPE^%msv(1)

or

S type=$$TYPE^%msv("MEM")

To determine the type of database holding the current UCI:

S type=$$TYPE^%msv


UNMOUNT^%msv

Unmounts a volume group.  Returns success or failure.

Syntax

UNMOUNT^%msv(Vg)

Parameter	Description
Vg	A volume group name or number.
For a description of parameters, refer to "Service Routine Conventions."


UNMOUNTM^%msv

Releases a moniker previously bound to a database and unmounts it if appropriate. Returns success or failure.

Syntax

UNMOUNTM^%msv(Moniker)

Parameter	Description
Moniker	Moniker name.
The moniker is unbound. If no other monikers remain bound to the volume group, it is unmounted.


Certain legacy system utilities are included with MSM-Workstation.  Some provide silent services, and others are character-based utilities that run only in the console window or from the Tools menu.


Legacy Utilities A-Z

Entry Point	Description
^%CHKSUM	Compute checksums
^%D	Return a date in external format
^%DEBUG	Character-based debugger
^%DEVUSE	Show devices in use
^%DH	Decimal to hex conversion
^%DI	Convert an external date to internal format
^%DO	Convert an internal date to an external format
^%ER	Report errors
^%ET	Trap errors
^%FGR	Fast global restore
^%FGS	Fast global save
^%FL	List first lines
^%G	List globals
X ^%G	Character-based editor
^%GCH	List global characteristics
^%GCHANGE	Search and replace in globals
^%GCMP	Compare globals
^%GCOPY	Copy globals
^%GD	List global directory
^%GDE	List extended global directory
^%GDEL	Delete globals
^%GE	List global efficiency
^%GL	List globals
^%GR	Restore globals
^%GS	Save globals
^%GSE	Search globals
^%GSEL	Select globals
^%GSIZE	List global size
^%INDEX	Cross-reference routines
^%INDSTR	List structured programs
^LOCKTAB	Lock table display
^%MFUNC	Mathematical functions
^%NEWED	Search routines by date
^%PACKAGE	Load application package
^%RCHANGE	Routine search and replace
^%RCMP	Compare routines
^%RCOPY	Copy routines
^%RD	List routine directory
^%RDEL	Delete routines
^%RPRT	Print routines
^%RR	Restore routines
^%RS	Save routines
^%RSAND	Search routines for multiple strings
^%RSE	Search routines
^%RSEL	Select routines
^%RSIZE	List routine size
^%SDEV	Select i/o device
^%T	Return a time in external forma
^%TI	Convert an external time to internal format
^%TO	Convert an internal time to an external format
^VALIDATE	Validate database integrity
^VERIFY	Verify map blocks
^%VIDEO	Manipulate PC console video buffer
^%ZSTIME	Routine time stamp


Legacy Utilities by Function

Date/Time Conversion

Globals

Mathematical Utilities

Routines

System Utilities


Date/Time Conversion

Entry Point	Description
^%D	Return a date in external format
^%DI	Convert an external date to internal format
^%DO	Convert an internal date to an external format
^%T	Return a time in external forma
^%TI	Convert an external time to internal format
^%TO	Convert an internal time to an external format


Globals

Entry Point	Description
^%FGR	Fast global restore
^%FGS	Fast global save
^%G	List globals
^%GCH	List global characteristics
^%GCHANGE	Search and replace in globals
^%GCMP	Compare globals
^%GCOPY	Copy globals
^%GD	List global directory
^%GDE	List extended global directory
^%GDEL	Delete globals
^%GE	List global efficiency
^%GL	List globals
^%GR	Restore globals
^%GS	Save globals
^%GSE	Search globals
^%GSEL	Select globals
^%GSIZE	List global size


Mathematical Utilities

Entry Point	Description
^%DH	Decimal to hex conversion
^%MFUNC	Mathematical functions


Routines

Entry Point	Description
^%DEBUG	Character-based debugger
X ^%G	Character-based editor
^%CHKSUM	Compute checksums
^%FL	List first lines
^%INDEX	Cross-reference routines
^%INDSTR	List structured programs
^%NEWED	Search routines by date
^%PACKAGE	Load application package
^%RCHANGE	Routine search and replace
^%RCMP	Compare routines
^%RCOPY	Copy routines
^%RD	List routine directory
^%RDEL	Delete routines
^%RPRT	Print routines
^%RR	Restore routines
^%RS	Save routines
^%RSAND	Search routines for multiple strings
^%RSE	Search routines
^%RSEL	Select routines
^%RSIZE	List routine size
^%ZSTIME	Routine time stamp


System Utilities

Entry Point	Description
^%DEVUSE	Show devices in use
^%ER	Report errors
^%ET	Trap errors
^LOCKTAB	Lock table display
^%SDEV	Select i/o device
^VALIDATE	Validate database integrity
^VERIFY	Verify map blocks
^%VIDEO	Manipulate PC console video buffer


Legacy Utilities - Legacy Utilities
Legacy Utilities

^%CHKSUM

^%D

^%DEBUG

^%DEVUSE

^%DH

^%DI

^%DO

^%ER

^%ET

^%FL

^%FGR

^%FGS

^%G

^%GCH

^%GCHANGE

^%GCMP

^%GCOPY

^%GD

^%GDE

^%GDEL

^%GE

^%GL

^%GR

^%GS

^%GSE

^%GSEL

^%GSIZE

^%INDEX

^%INDSTR

^LOCKTAB

^%MFUNC

^%NEWED

^%PACKAGE

^%RCHANGE

^%RCMP

^%RCOPY

^%RD

^%RDEL

^%RPRT

^%RR

^%RS

^%RSAND

^%RSE

^%RSEL

^%RSIZE

^%SDEV

^%T

^%TI

^%TO

^VALIDATE

^VERIFY

^%VIDEO

^%ZSTIME

%G Editor


^%CHKSUM

Computes checksums.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%CHKSUM

This utility is used to compute a checksum value for one or more routines in a UCI.  The checksum value for a routine is the summation of the ASCII values of every character in the routine. The actual calculation is done using the $ZCRC function of MSM. The checksum value for each routine is stored in the CHECKSUM global in the following format:

^CHECKSUM(Routine)=Checksum


^%D

Returns the current date in external format or converts a date from internal to external format.

Syntax

INT^%D	; ignores %H and returns the current date

INTT^%D	; %H date

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%H	Input	Date in $H format. Used by INTT entry point only.
%DAT	Output	Date in MM/DD/YYYY format.
%DAT1	Output	Date in DD-MMM-YYYY format.
Description

The INT entry returns the current date; the INTT entry returns the external date for the numeric date passed in %H.

The internal value for a date, known as "$H format," is a five-digit number which is equal to the number of days since December 31, 1840. The range of acceptable dates is January 1, 1841, to December 31, 2099.

Sample terminal session

>K

>D INT^%D

>W

%DAT="11/22/1996"

%DAT1="22-NOV-96"

>S %H=58074

>D INTT^%D

>W

%DAT="1/1/2000"

%DAT1="1-JAN-00"

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.

MSM's built-in $ZDATE and $ZHL functions provide identical functionality and many additional formatting options. Refer to the MSM Language Reference Manual for information on these functions.


^%DEBUG

The MSM interactive debugger (%DEBUG) is provided as a tool to the programmer to facilitate the isolation and correction of errors in M programs.  It is a comprehensive tool that allows the user to interactively step through the execution of a program, display the contents of local variables, modify their values, and resume execution.

In MSM-Workstation, %DEBUG is a character-mode application that runs in a console window. The debug device must be a console window (devices 1 and 31-37), or a COM port (devices 11-18). For a sophisticated GUI-based alternative, use the debugger which is integrated with the File/Test facility.

To start the utility: from the Tools menu, select Routines and then Debugger; or from Tools, select Command Window and enter:

DO ^%DEBUG

This CHUI-mode debugger is started automatically when a debug-build .EXE is started with the +CHUIDEBUG switch.

Special care should be taken when using this tool to debug event-driven MWAPI code, including that generated by Workstation's window compiler. If you click away from the debug device while execution is suspended within callback code at the DEBUG> prompt, and you move focus to an MWAPI window on which there is an UNFOCUS event defined and enabled, you will be unable to return to the debug device to resume execution. The only option is to end the MSM-Workstation task using the Windows Task Manager. This issue does not arise when using the GUI debugger.

Sample startup session

>D ^%DEBUG

MSM - Interactive Debugging Utility

Available Options:

     1 - Run a Program

     2 - Enable Debugging Environment

     3 - Disable Debugging Environment

     4 - HELP Information

Select Option: ?

Enter the option number to select an option, or

Enter enough characters to identify the option, or

Enter <RETURN> or '^' to exit the utility.

Select Option:

See Also:

Options

Breakpoints

Commands


Options

Run a Program

This option is used to interactively debug a program.  The philosophy behind the interactive debugger is that a program in execution will be interrupted at user-specified locations and the interactive debugger will be invoked at each of these points to allow the user to examine the current state of the routine.

The program can be interrupted by explicit breakpoints in the program (a BREAK command with no arguments), the interrupt key (CTRL+C), program errors (errors that may or may not be handled by error trapping facilities), or implicit breakpoints (defined to the user through the debugger without actually modifying the code).  In addition, through the debugger, the user can specify that an implicit breakpoint should occur at the start of each line in a routine (line stepping) or at the start of each command in each line in a routine (command stepping).

Enable Debugging Environment

This option is used to enable the debugging environment without actually debugging a specific program.  This is necessary because argumentless BREAK commands within a program will be ignored unless debugging is enabled.

When debugging mode is on, the system maintains additional information about the program being executed.  In particular, the system maintains extended error information, including the location of the command within the line where the error occurred and the location of the argument within the command where the error occurred.  When debugging is enabled, the programmer prompt is preceded by the letter D.

Select Option: 2 - Enable Debugging Environment

Debug Device <1>:

Debugging Environment Enabled

D>

Disable Debugging Environment

This option is used to disable the debugging environment.  When debugging is off, argumentless BREAK commands are ignored and the extended error processing information is not maintained.

Select Option: 3 - Disable Debugging Environment

Debugging Environment Disabled

>


Breakpoints

Implicit Breakpoints

An implicit breakpoint is a user-specified location within a program where execution is to be interrupted and the interactive debugger is to receive control.  When the breakpoint is encountered, all of the information necessary to restart execution of the program from the point where it was interrupted is saved.  The debugger is then invoked and the user is prompted for an action.

An implicit breakpoint is defined by specifying the EntryRef in the routine where the break should occur.  This can be a routine name (^TEST), or line reference within a routine (ABC^MYPGM), or a line reference and offset within a routine (LABEL+4^YOURPROG).  In addition, the user can specify the command within the line (the first command is 1, the second is 2, and so on) and the action to be performed (a line of M code to be XECUTEd when the breakpoint is encountered.  Up to ten implicit breakpoints, numbered zero through nine, can be set.  The /B, /B=, /Bn, and /Bn= commands are all associated with breakpoints.

Conditional Breakpoints

An especially useful feature is the ability to break depending on the execution of user-defined code.  For example, a test could be made for the value of a particular variable, and execution stopped when the variable contains a certain value.  As another example, the value of a variable could be saved in a scratch variable, and a test made comparing the saved value and the current value, so that execution stops when the variable changes value.

Breakpoints in Command Stepping

You can break after every command and drop into Command Stepping mode, or continue executing, depending on the execution of user-defined code.  Using this feature, the precise command on which an event occurs can be identified.  The following is an example of how this can be done.

DEBUG>/C=IF ACCOUNT=12765 ZGO

The code IF ACCOUNT=12765 ZGO is executed by the debugger after each command in the application code.  If the ZGO is executed, the application continues to execute at the next command.  If the ZGO is not executed, then the user is dropped back into Command Stepping mode. The particular command would find the location in the application at which the ACCOUNT variable is equal to 12765.

Breakpoints in Line Stepping

The user can break after every line and drop into Line Stepping mode or continue executing, depending on the execution of user-defined code.  Using this feature, the precise line on which an event occurs can be identified.  For example:

DEBUG>/L=IF $GET(ACCOUNT)'?.E1C.E ZGO

The code IF $GET(ACCOUNT)'?.E1C.E ZGO is executed by the debugger after each line of application code.  If the ZGO is executed, the application continues to execute at the next line. If the ZGO is not executed, the user is dropped back into Line Stepping mode. The particular command would find the location in the application at which the ACCOUNT variable contained a control character.


Commands

To fully understand the capabilities of the interactive debugger, it is important to become familiar with the debugger's basic capabilities and with the terminology used in the debugger commands. Generally, for basic functions that exist in the debugger, there is a corresponding command to invoke the action.  The following sections describe each of these functions.

To request online Help for commands, enter ? at the prompt.

DEBUG> ?

Return                   Execute the next line

Space                    Execute the next command on the line

/B                       Display All Active Breakpoints

/B=                      Set new Breakpoint using prompts

/Bn                      Display Breakpoint n

/Bn=                     Set or Delete Breakpoint n using prompts

/Bn=line^routine:command;action  Set Breakpoint n

/C=action                Step to next command

/E                       List environmental Information

/H                       Display HELP Information

/L=action                Step to next line

/R                       Return Out of a Subroutine

/S                       Display the Current Execution Stack

/T                       Toggle Step Mode between Into and Over

ZGO                      Continue Without Command or Line Stepping

QUIT                     Stop Execution

Command Stepping (/C)

In this mode, an implicit breakpoint is inserted at the start of each command in each line.  This means that the debugger receives control at the start of execution of each command within a line. The SPACEBAR, the F1 key (ANSI terminals only), and the /C command can all be used to invoke command stepping.

Line Stepping (/L or Enter)

In this mode, an implicit breakpoint is inserted at the start of each line. This means that the debugger receives control at the start of execution of each line. The ENTER key and the /L command can be used to invoke line stepping.

Environmental Variables (/E)

The debugger can report on the state of environmental variables that are maintained by the MSM system, including $TEST, $JOB, $IO, $X, $Y, $ZUCI, $ZREFERENCE, and subroutine step mode.  The /E command displays the environmental variables.

Subroutine Step Mode (/T)

When a program is being debugged in line-step mode or command-step mode, an option exists to continue inserting breakpoints at the line or command level for a subroutine that is being called. If step mode is set to Into and a subroutine is called by a line step or command step, the system continues to insert breakpoints in the subroutine.  If step mode is set to Over, no breakpoints are inserted into the subroutine (the called subroutine is treated as a single command).

When debugging is in Into mode, the /R command can be issued to treat the remainder of the subroutine as a single command. The /T command is used to toggle between Into and Over mode.

Miscellaneous Commands (ZGO, QUIT, /S)

To round out the capabilities of the debugger, several additional commands are required.  The ZGO command, for example, is used to tell the debugger to resume execution of a routine and continue processing until the next implicit or explicit breakpoint is encountered.  When the debugger is entered from a breakpoint, the line step, command step, or ZGO command can be used to resume execution.

Sometimes it is desirable to exit completely from a program that is being debugged (for example, the program error has been found).  The QUIT command is used for this purpose.  When this command is entered, the debugger terminates and returns to programmer mode with debugging disabled.

The /S command within the debugger displays the current execution stack.  This provides a traceback of how control passed to the current routine and shows all nested DO and XECUTE commands down to the current execution level.


^%DEVUSE

Displays devices in use.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%DEVUSE

This utility is used to display the job number ($J) of the job that owns each active device.  A device is considered active if it has been OPENed. For Host File Server devices, the name of the file being accessed is also displayed.


^%DH

Converts decimal numbers to hexadecimal.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%DH

This utility is used to convert numbers from decimal to hexadecimal format.  The user is prompted for the decimal number to be converted. After it is entered, the utility displays the number in hexadecimal and prompts for another value.  If a null response is entered, the utility terminates.

To obtain this facility within your own code, use the $ZHEX function. Refer to the MSM Language Reference Manual for information.


^%DI

Converts an external date in virtually any recognizable format to its corresponding internal format.

Syntax

^%DI

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%DS	Input	Date in external format.
%DN	Output	Date in internal format, or undefined if an error occurred.
%ER	Output	Undefined if no error occurred, -1 if an error occurred.
Description

The input date may be in any of the following formats:

JANUARY 4, 1997

JAN 4, 1997

4 JAN 1997

1/4/1997

1-4-97

1 4 97

T

T+20

T-1

In the above examples, T is TODAY, T+20 is TODAY plus 20 days, and T-1 is yesterday. The date input may be any numeric form in which non-numeric characters are used as delimiters or a month name with any form of non-numeric delimiters. If a year is not specified, the current year is assumed.

The internal value for a date, known as "$H format," is a five-digit number which is equal to the number of days since December 31, 1840. The range of acceptable dates is January 1, 1841, to December 31, 2099.

Sample terminal session

>K

>S %DS="31-DEC-99"

>D ^%DI

>W

%DN=58073

%DS="31-DEC-99"

>S %DS="1-JAN-2000" D ^%DI W

%DN=58074

%DS="1-JAN-2000"

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.


^%DO

Converts an internal date to an external format.

Syntax

INT^%DO	; Format DD-MMM-YYYY

300^%DO	; Format YYYYMMDD

400^%DO	; Format MM/DD/YY

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%DN	Input	Date in internal (numeric) format.
%DS	Output	Date in external (string) format in the indicated format or undefined if an error occurred.
%DA	Output	Day of the week.
%ER	Output	Undefined if no error occurred, -1 if an error occurred.
Description

The different entry points can be called to return the external date in different formats. In each case, the external date is returned in the %DS local variable.

The internal value for a date, known as "$H format," is a five-digit number which is equal to the number of days since December 31, 1840. The range of acceptable dates is January 1, 1841, to December 31, 2099.

Sample terminal session

>K

>S %DN=58073

>D INT^%DO

>W

%DA="FRIDAY"

%DN=58073

%DS="31 DEC 99"

>S %DN=%DN+1 D INT^%DO W

%DA="SATURDAY"

%DN=58074

%DS="01 JAN 2000"

>K

>D INT^%DO

>W

%ER=1

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.

MSM's built-in $ZDATE and $ZHL functions provide identical functionality and many additional formatting options. Refer to the MSM Language Reference Manual for information on these functions.


^%ER

Reports errors.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%ER

This utility is used to display, print, erase, or summarize errors that have been logged using the %ET utility program.  When displaying errors, the user is prompted for the date on which the error occurred and which error to display if more than one error was logged.

For printing, erasing, or summarizing errors, the user is prompted for a date which may be a single date (for example, 8/24/90) or a range of dates (for example, 8/12/90 through 8/24/90).  When a range of dates is specified, the dates are separated by a colon (for example, 8/12/90:8/24/90).  For printing and summarizing errors, the %SDEV utility is called to select an output device for the report.


^%ET

Traps errors.

Description

This utility provides a generalized mechanism to record information about programming or environmental errors that occur during execution of a program or application.  When this routine is invoked, it saves the error code ($ZERROR), the date and time of the error, the job number, the current device number, the last global referenced, and all of the local variables that existed at the time of the error. Note that the % local variable is not saved because it is used by the %ET routine itself.  If the current device is 51 through 63, $ZA, $ZB, and $ZC are also saved.

The most common method of invoking the error trap utility is to set the $ZTRAP special variable to the routine name.  This is done by executing the following from within a program:

SET $ZTRAP="^%ET"

After this is done, the error trap utility is automatically invoked when an error occurs.  Before logging the error, the utility displays a message indicating that a program error has occurred and the value of the $ZERROR special variable. To suppress the message, the error trap utility can be entered at the INT entry point (INT^%ET):

SET $ZTRAP="INT^%ET"


^%FL

Lists the first lines of routines.

Description

To start the utility: from the Tools menu, select Routines and then select First Lines; or from the Tools menu, select Command Window and then enter:

DO ^%FL

This utility lists the first line from one or more routines. Generally, the first line of a routine contains a line label that matches the name of the routine, followed by a comment that (by convention) usually contains the initials of the programmer, followed by a descriptive comment about the routine. If the routine was filed through the line editor or the full-screen editor, the date and time appear at the end of the first line as a comment.

This utility calls the %RSEL routine to select one or more routines and then calls the %SDEV routine to select an output device.


^%FGR

Performs a fast global restore.

Description

To start the utility: from the Tools menu, select Globals and then select Fast Restore; or from the Tools menu, select Command Window and then enter:

DO ^%FGR

This utility is used to restore globals that were saved using the %FGS utility.  The routine calls the %SDEV utility to select the input device.  The device may be a host file or a tape unit.  After the device is selected, the utility reads the first two records from the device (the header information saved by the %FGS utility) and displays it on the terminal. The header information includes the date and time that the globals were saved and the user comment that was specified when the globals were saved.  This allows the person doing the restore to verify that the correct file is being used before the actual restore operation begins.

When restoring the globals, the user is asked whether or not a selective restore is to be performed; if so, then the user can specify which globals are to be restored, skip forward in the restore process until a specified global is reached, or continue restoring without prompts until a specified global is reached.  If the user responds NO to the selective restore prompt, then all globals will be restored.  As each global is restored, the name of the global is displayed.


^%FGS

Performs a fast global save.

Description

To start the utility: from the Tools menu, select Globals and then select Fast Save; or from the Tools menu, select Command Window and then enter:

DO ^%FGS

This utility is used to output one or more globals to a sequential device. The routine calls the %SDEV utility to select the output device. The device may be a host file or a tape unit.  It then prompts the user for a comment to be stored in the dump header.  Finally, it calls the %GSEL utility to select the globals to be saved.

This utility differs from the %GS utility in the method by which globals are saved.  In the case of the %GS utility, each individual global node is retrieved from the M database and written to the sequential device. In the case of the %FGR utility, the actual low-level data blocks, each containing multiple nodes, are retrieved and written to the sequential device. This approach is more efficient and requires less space. However, the output is not readily accessible to other programs or tools.


^%G

Lists globals.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%G

This utility is used to list one or more globals.  The %GSEL utility is called to select the globals to be listed, and the %SDEV utility is called to prompt for the output device.  If the list is being output to the current device, the utility prompts the user whether or not to scroll the list.  If the global being listed contains control characters, they are displayed as \nnn where nnn is the ASCII value of the character.

This utility differs from the %GL utility in that it allows the use of local variables to specify the nodes to be displayed in a partial global list. However, to specify a string node in a partial selection, the node must be enclosed with quotes.  Note that %G and %GL, unlike all of the other global utilities, invoke the %GSEL utility in such a way that ^UTILITY($J is not modified.  Therefore, the two Global Lister utilities can be used to examine ^UTILITY($J.


^%GCH

Manages global characteristics.

Description

To start the utility: from the Tools menu, select Globals and then select Characteristics; or from the Tools menu, select Command Window and then enter:

DO ^%GCH

This utility is used to change the characteristics of selected globals, including: the protection attributes and whether to allow a KILL of the entire global. To change the characteristics for a specific global, the user must either be logged on to the UCI containing the global when the utility is run, or logged on to the Workstation application's %App UCI (2,0) while using cross-UCI notation to identify the global.  When the utility is invoked, the user is prompted for the names of the globals to modify.  If a single global is selected and the global does not exist, the user is prompted to respond whether the utility should create the global. The following sections describe the purpose and use of each function in the utility. The functionality is also available to programs via the CALL entry-point. See the routine text for documentation.

Protection

The MSM system allows the user to control who is allowed to access information and the degree of access permitted.  This is done by assigning protection attributes to the global using the Protection option.  Protection within the system is divided into the following user groups or classes:

Group	Description
SYSTEM	Includes all users and programs that are running in the Workstation application's %App  UCI (2,0).
USER	Includes all users and programs running in the same UCI where the global is stored.
GROUP	Includes all users and programs that belong to the same UCI group.  A UCI group is the set of all UCIs on the same volume group.
WORLD	Includes all users and programs that do not belong to any of the other three classes.
Separate protection codes can be assigned for each class of user.  Within a class, one of the following types of protection can be specified:

Value	Description
READ	Allows users within the specified class to look at, but not modify, the global.
WRITE	Allows users within the specified class to look at and modify the global. Users are not permitted to delete (KILL) the global or nodes within the global.
DELETE	Allows users within the specified class to look at, modify, and delete the global.
NONE	Denies all access to the global for users within the specified class.
When a global is created, the system automatically assigns it protection codes. This default protection allows the USER and SYSTEM classes READ, WRITE, and DELETE access. The GROUP and WORLD classes are denied all access to the global. For globals that begin with a percent sign (%), the GROUP and WORLD classes are allowed READ access.

Allow/Prevent Kill

To prevent the inadvertent deletion of an entire global, an unsubscripted KILL can be stopped by using this option. When an unsubscripted KILL is issued to the global, a <PROT> error occurs, and the global will not be deleted.  Note that KILLs to individual subscripted nodes are not affected by this option.


^%GCHANGE

Searches and replaces strings in one or more globals.

Description

To start the utility: from the Tools menu, select Globals and then select Change; or  from the Tools menu, select Command Window and then enter:

DO ^%GCHANGE

This utility searches one or more globals for a particular string of characters and optionally replaces the string with another string.  The %GSEL utility is called to select the globals, and the %SDEV utility is called to select the output device.  The user is prompted for the search string (Replace:), the new string that will replace the search string (With:), and whether or not the change is to be verified before it is made.  If the result of the replacement would create a data value longer than 255 characters, an error message is issued and no change is made.


^%GCMP

Compares two globals.

Description

To start the utility: from the Tools menu, select Globals and then select Compare; or from the Tools menu, select Command Window and then enter:

DO ^%GCMP

This utility is used to compare two globals in the same or different UCIs.  The program highlights differences within nodes by using inverse video on the console or terminals, underlining on printers, or colors in RTF files.  Nodes present in only one of the two globals are shown by default.  Options allow ignoring nodes present in only one global, and displaying or not displaying the data of such nodes.

First, the %SDEV utility is called to prompt the user for the output device and settings.  Output may be directed to the console or terminal device, a host file, or a printer.  If host file output is selected and the host file name is specified with the .RTF extension, a rich-text format file will be created.

The %GSEL utility is called to select the globals to be compared.  Subtrees may be compared, and extended global references may be used to do cross-UCI compares.

After specifying what to do with nodes present in only one of the two globals, the compare is performed.  Summary information at completion displays the number of identical nodes, different nodes, nodes found only in the first global, and nodes found only in the second.


^%GCOPY

Copies globals.

Description

To start the utility: from the Tools menu, select Globals and then select Copy; or from the Tools menu, select Command Window and then enter:

DO ^%GCOPY

This utility copies one or more user-selected globals from the current UCI to another UCI. The %GSEL utility is called to select the globals.  The user is then prompted for the name of the UCI where the globals are to be copied.  The user must specify a UCI name that is different than the name of the current UCI.

The user is given the option of selectively copying the globals.  This allows some or all of the globals to be copied and allows renaming of each global if desired.  If the selective copy option is chosen, the user is prompted with each global name before it is copied and given three choices: <Y/N/R>.

Choice	Description
Y(es)	Copies the global as named.
N(o)	Does not copy the global.
R(ename)	Renames the global before copying it. Only the copy is renamed; the original is not. If Rename is chosen, the user is prompted for the new name. If the name is provided, the global is copied using the new name. An up-arrow (^) can be input to this prompt if the user decides not to copy the globals.
If the user does not copy selectively, copying begins immediately. As each global is copied, the name of the global is displayed. When copying is complete, a message is displayed.

Note that %GCOPY does not copy the global characteristics along with the data. Therefore, for globals with a collating sequence other than the system default, the global should first be created in the destination UCI using the %GCH utility, and the proper collating sequence set, before copying the global.


^%GD

Lists a global directory.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%GD

This utility lists, in alphabetical order, the name of every global saved in the current directory.  As a heading, it lists the name of the UCI and volume group, and the date and time.  In addition, %GD lists globals that are translated or replicated.  For replicated globals, the replication index is displayed before the translated global name.


^%GDE

Lists an extended global directory.

Description

To start the utility: from the Tools menu, select Globals and then select Extended Directory; or from the Tools menu, select Command Window and then enter:

DO ^%GDE

This utility is used to produce an extended display of the global directory for the current UCI.  The user is prompted for the output device where the report is to be produced.  The following items are displayed:

Column	Description
NAME	The name of the global.
CS	The collating sequence in effect for the global, either Numeric (N) or String (S).
JOURNAL	This flag indicates whether or not the global is to be journaled.  If the global is always to be journaled, this field displays ON.  If the global is never to be journaled, the field displays OFF.  If this field is blank, then the global honors the journal status of the UCI.
PROTC	The protection attributes associated with the global.  For each class (S=System, W=World, G-Group, U=User), the level of access allowed is displayed (R=Read, W=Write, D=Delete).  If a type of access is not allowed, then a period (.) is displayed in that position.
NOKILL	This flag indicates whether or not the entire global can be deleted via a KILL on the top level node (a KILL ^gname with no subscripts).  The letter Y is displayed if global delete has been prevented (see %GCH).
TOP POINTER BLOCK	The absolute block number of the top level pointer block.  It is followed by the block number expressed in the form of volume number:relative block number (0:65).
GROWTH	The map number of where the search for global expansion is to begin.  It is followed by the map expressed in the form of volume number:relative map number (0:65).


^%GDEL

Deletes globals.

Description

To start the utility: from the Tools menu, select Globals and then select Delete; or from the Tools menu, select Command Window and then enter:

DO ^%GDEL

This utility is used to delete one or more globals from the current UCI. The %GSEL utility is called to select the globals to be deleted.  It then prompts the user to verify that the globals are to be deleted.  As each global is deleted, the name of the global is displayed.


^%GE

Displays global efficiency.

Description

To start the utility: from the Tools menu, select Globals and then select Efficiency; or from the Tools menu, select Command Window and then enter:

DO ^%GE

This utility is used to display the size and efficiency of one or more globals.  The %GSEL routine is called to select the globals that are to be displayed.  For each global, information is displayed about the highest pointer block (depth 1), the next level pointer block (depth 2), all the way down to the bottom level pointer block (depth n-1) and the data block (depth n).  The following information is provided:

Item	Description
Pointer Blk	At each level, the address of the left-most block in the tree is displayed.  By using the right-link address in the block, all blocks at the same depth can be accessed.
Space Allocated	At each level in the global, the total number of blocks allocated and the total number of bytes allocated are displayed.  The number of bytes per block is 1012 because of system overhead associated with control information about the block.
Bytes Used	At each level in the global, the actual number of bytes used is displayed.  This is determined by looking at the byte offset pointer in each block on the level.
Percent Utilization	At each level in the global, the total utilization is computed using the number of bytes allocated versus the number of bytes used.
After all selected globals are displayed, a summary is presented for all globals.  It includes the total space used, and total space utilization expressed as a percentage.


^%GL

Lists globals.

Description

To start the utility: from the Tools menu, select Globals and then select List; or from the Tools menu, select Command Window and then enter:

DO ^%GL

This utility is used to list one or more globals.  The %GSEL utility is called to select the globals to be listed, and the %SDEV utility is called to prompt for the output device.  If the list is being output to the current device, the utility prompts the user whether or not the list is to be scrolled. If the global being listed contains control characters, they are displayed as \nnn where nnn is the ASCII value of the character.

This utility differs from the %G utility in that, when selecting a partial global to be listed, quotes need not be specified around string subscripts.  However, variables cannot be used to specify the nodes to be listed.  Unlike all other global utilities, %G and %GL invoke the %GSEL utility in such a way that ^UTILITY($J is not modified. Therefore, the two Global Lister utilities can be used to examine ^UTILITY($J.


^%GR

Restores globals.

Description

To start the utility: from the Tools menu, select Globals and then select Restore; or from the Tools menu, select Command Window and then enter:

DO ^%GR

This utility is used to restore globals that were saved using the %GS utility.  The routine calls the %SDEV utility to select the input device.  The device may be a host file or a tape unit.  After the device is selected, the utility reads the first two records from the device (the header information saved by the %GS utility) and displays it on the terminal.  The header information includes the date and time that the globals were saved and the user comment that was specified when the globals were saved.  This allows the person doing the restore to verify that the correct file is being used before the actual restore operation begins.

When restoring the globals, the user is asked whether or not a selective restore is to be performed.  If the user indicates that a selective restore is to be performed, then the user can specify which globals are to be restored, rename globals as they are being restored, skip forward in the restore process until a specified global is reached, or continue restoring without prompts until a specified global is reached.  If the user responds NO to the selective restore prompt, then all globals will be restored.  As each global is restored, the name of the global is displayed.


^%GS

Saves globals.

Description

To start the utility: from the Tools menu, select Globals and then select Save; or from the Tools menu, select Command Window and then enter:

DO ^%GS

This routine is used to output one or more globals to a sequential device. For terminal and printer type devices, the %GL utility should used because it produces output tailored for these devices.  The format of this utility's output is as follows:

date and time in external format

comment supplied by the user

global name(subscripts)

global data for node

       .

       .

       .

global name(subscripts)

global data for node

or ** to indicate end of global or end of file

or ** to indicate end of global or end of file

The routine calls the %SDEV utility to select the output device.  It then prompts for the size of the output media in 1-K blocks.  After the utility has written the specified number of blocks, it prompts the user to replace the media with the next one in the sequence.  This allows different types of tape drives and floppy disk drives to be used.  Finally, the user is prompted for a comment to be used in the dump header, and then the %GSEL utility is called to select the globals to be saved.


^%GSE

Searches globals for one or more strings.

Description

To start the utility: from the Tools menu, select Globals and then select Search; or from the Tools menu, select Command Window and then enter:

DO ^%GSE

This utility searches one or more globals for one or more user-specified strings.  A match occurs if a global contains any of the user-specified strings.  The utility calls the %GSEL utility to select the globals that are to be searched, and the %SDEV routine to select the output device where the list of globals that match the search criteria will be printed.  The user is then prompted for the search strings.


^%GSEL

Selects globals.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%GSEL

This utility is a general-purpose routine that is used to select one or more global names from the global directory of the current UCI. All of the MSM utility routines that prompt for global selection use this utility.  To select the globals, the %GSEL utility uses the $ORDER function to step through the global directory.  Each global name returned by the $ORDER function is examined using the criteria specified by the user.  If the global name matches the specified criteria, then the global is selected; otherwise, it is skipped and the next global name is examined.

The user may specify a single global name (ABC), a range of global names (AAA-HZZZ), a global name prefix (AB*), or all globals (*). The selection criteria may be preceded by a minus sign (-) to delete the corresponding entries from the list of selected globals.  Selected globals are stored in the UTILITY global in the following format:

^UTILITY($J,GlobalName)=""

In this example, $J is the job number of the current job, and GlobalName is the name of the global. If a list of globals already exists under the job number, the user can enter a period (.) to use this list.  When this is done, the utility displays the existing list and prompts for additional global selection criteria. When called from the %G and %GL (Global Lister) utilities, selected globals are stored in the %UTILITY local variable, which allows ^UTILITY($J) to be examined.

By default, %GSEL allows selection of globals in other UCIs and on remote systems.  It also allows the selection of portions of globals.  Any or all of these features can be disabled using an internal entry point called SELECT. Flags are passed to %GSEL using the parameter passing syntax which can specify which of the features are allowed. For example:

DO SELECT ^%GSEL("UR")

allows cross-UCI and remote system selection but not partial selection.  The following table describes the options in the %GSEL utility program.

Parameter	Function
U	Allows cross-UCI selection of globals on local systems.
R	Allows selection of globals on remote systems.
P	Allows partial global selection.
1	Allows only one global to be selected.
If %GSEL is invoked at the routine start (D ^%GSEL), a default value of "URP" is used.  When one or more features are disabled, the Help displayed reflects only the available features.


^%GSIZE

Displays size of globals.

Description

To start the utility: from the Tools menu, select Globals and then select Size; or from the Tools menu, select Command Window and then enter:

DO ^%GSIZE

This utility is used to display the size of one or more globals.  The %GSEL routine is called to select the globals that are to be displayed.  For each global, information is displayed about the highest pointer block (depth 1), the next level pointer block (depth 2), all the way down to the bottom level pointer block (depth n-1) and the data block (depth n).  The following information is provided.

Item	Description
Pointer Blk	At each level, the address of the left-most block in the tree is displayed.  By using the right-link address in the block, all blocks at the same depth can be accessed.
Space Allocated	At each level in the global, the total number of blocks allocated is displayed.
After all selected globals are displayed, the total number of 1-K blocks used by all of the globals is displayed.  This utility is a significantly faster option than the %GE utility when only the size of the globals needs to be known.


^%INDEX

Produces a cross-reference of one or more routines.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%INDEX

This utility produces a cross-reference of one or more routines.  It invokes the %RSEL utility to select the routines to index and the %SDEV utility to prompt for the output device. For each routine selected, the routine name is listed, followed first by the size of the routine in bytes and then by the cross-reference.

The cross-reference includes errors and warnings about a routine, a list by local variable name of the lines that reference them, a list by global variable name of the  lines that reference them, and a list of naked references by line. For local variables or global variables that are modified by the reference, or killed or newed, a special marker will indicate the type of manipulation.

The index also includes a list by line-label name within the routine of lines that reference them and a list of external line labels and the lines that reference them. If more than one routine is referenced, then a final cross-reference of all routines is included. This includes a list of local variables and the routines that reference them, a list of global variables and the routines that reference them, a list of the routine names and the routines they invoke, and a list of the routine names and the routines by which they are invoked.

If the user indicates that routines are to be listed with the cross-reference, then a structured program listing can be produced as an option. The %INDSTR routine is invoked by %INDEX to produce the structured listing.  Refer to this routine for a description of the structured listing that is produced.


^%INDSTR

Produces a structured program listing.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%INDSTR

This utility produces a structured program listing for one or more routines. The %RSEL utility is called to select the routines and the %SDEV utility is called to prompt for the output device.  The structured listing will display all commands, functions, and special variables using their full name, and will indent FOR loops to show the scope of the FOR loop, and so on.


^LOCKTAB

Displays the lock table.

Description

To start the utility: from the Tools menu, select System and then select Lock Table; or from the Tools menu, select Command Window and then enter:

DO ^LOCKTAB

This utility is used to display the contents of the system Lock table.  The Lock table contains the LOCK and ZALLOCATE commands that are currently active in the system.  The utility displays the job number and system name of the job that owns the lock, the mode of the lock (LOCK or ZALLOCATE), and the variable reference.

If the variable name is a Global, then the lock only affects jobs within the same UCI.  If the lock is a Local reference or begins with a percent sign (%) then the lock is system-wide and affects all jobs.


^%MFUNC

Provides mathematical functions.

Description

This utility contains a variety of entry points to perform common mathematical functions.  Each entry point is called as an extrinsic function. The functions are passed none, one, or two parameters depending upon the type. The following table lists the defined entry points:

Entry Point	Function
E()	The value of e (2.712818284590452354)
PI()	The value of ð (3.1415926535897932)
EXP(X)	The value of e (2.71...) raised to the power of X
LOG(X)	The logarithm (base 10) of X (LOG10 X)
LN(X)	The natural logarithm (base e) of X
PWR(X,Y)	The value of X raised to the power of Y (XY)
SQR(X)	The square root of the argument X
SIN(X)	The trignometric sine of X*
COS(X)	The trignometric cosine of X*
TAN(X)	The trignometric tangent of X*
COT(X)	The trignometric cotangent of X*
SEC(X)	The trignometric secant of X*
CSC(X)	The trignometric cosecant of X*
ASIN(X)	The trignometric inverse sine of X*
ACOS(X)	The trignometric inverse cosine of X*
ATAN(X)	The trignometric inverse tangent of X*
* Expressed in radians.  To convert from radians to degrees:

deg=(radians*360)/2p

For example:

S PI=$$PI^%MFUNC()


^%NEWED

See also

Searches routines by date.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%NEWED

This utility is used to search one or more routines to find the routines saved during a specified date range.  The routines must have been saved using the '.F' command of the program editor (^%), or the '.F' or '.W' command of the full-screen editor (^%E), the ^%G editor, or the Workstation shell editor. The %RSEL utility is called to select the routines, and the %SDEV utility is called to prompt for the output device.

The user is then prompted for a starting and ending date for the search.  All routines saved during the specified data range (which includes the starting and the ending date) are displayed.  The name of the routine and the first line of the routine are displayed.

Refer also to the documentation on the %ZSTIME utility.


^%ZSTIME


^%PACKAGE

Loads application package.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%PACKAGE

Some application packages supplied by Micronetics are distributed in %PACKAGE-format.  Each application package is supplied with user documentation and instructions on how to initialize the package, if required.  The application package is distributed in a format that is designed to be self-loading.  The actual loading of the package is initiated using the %PACKAGE utility program.  After the process is complete, all appropriate routines and globals will have been loaded.

The first step when installing an application package is to determine the UCI into which the package will be loaded. Care should be taken to ensure that the routines and globals that are supplied with the application package will not replace or conflict with any routines and globals that may already exist in the UCI. After the appropriate UCI for the application program is determined, the user logs on to the selected UCI in programmer mode and invokes the %PACKAGE utility.

This begins the process used to load the application package into the UCI. The %SDEV routine will be called to prompt for the input device.  In most cases, when an application package is installed on the system for the first time, some type of initialization process must be performed.  This process may include defining terminal types, identifying the host operating system, and supplying other information describing the operating environment.  Because the initialization process is unique for each type of package, it is important to refer to the instructions supplied with the application package that is being loaded.


^%RCHANGE

Searches and replaces in one or more routines.

Description

To start the utility: from the Tools menu, select Routines and then select Change; or from the Tools menu, select Command Window and then enter:

DO ^%RCHANGE

This utility searches one or more routines for a particular string of characters and optionally replaces the string with another string.  The %RSEL utility is called to select the routines and the %SDEV utility is called to select the output device.  The user is prompted for the search string (Replace:), the new string that will replace the search string (With:), and whether or not the change is to be verified before it is made.  If the result of the replacement would create a line longer than 255 characters, an error message is issued and no change is made.


^%RCMP

Compares routines.

Description

To start the utility: from the Tools menu, select Routines and then select Compare; or from the Tools menu, select Command Window and then enter:

DO ^%RCMP

This utility is used to compare one or more routines in the same UCI or in two different UCIs.

First, the %SDEV utility is called to prompt the user for the output device and settings.  Output may be directed to the console or terminal device, a host file, or a printer.  If host file output is selected and the host file name is specified with the .RTF extension, a rich-text format file will be created if the highlighting is selected (see below).

Next the user is prompted whether to use highlighting.  Responding Yes causes the new-style routine compare to be used.  This highlights differences within lines by using inverse video on the console or terminals, underlining on printers, or colors in RTF files.  Responding No uses the original version of routine compare which shows changed lines but not changes within lines.

The %RSEL utility is called to select the routines to be compared.  Next, the UCI that contains the routines that will be compared with the selected routines must be specified.  This can be the current UCI or a different UCI.  If the current UCI is selected (by pressing Enter), each selected routine is displayed and a compare-with routine must be specified.

If the old-style non-highlighting option was selected, the user is next prompted for the level of detail to be displayed. This can be any of the following:

Level	Description
Brief	A brief listing that shows lines that have been added, deleted, and modified.  Identical lines are not listed.
Detail	A detailed listing that shows the entire source program with an indication of which lines have been added, deleted, and modified, and which lines are identical.
Statistics	A statistical listing that shows a count of the number of lines added, deleted, and modified, and the number of lines that are the same.
Finally, the compare is performed.  If a device other than the current device is chosen for the listing and multiple routines are being compared, then the name of each routine will be written to the current device as it is compared.


^%RCOPY

Copies routines.

Description

To start the utility: from the Tools menu, select Routines and then select Copy; or from the Tools menu, select Command Window and then enter:

DO ^%RCOPY

This utility copies one or more user-selected routines from the current UCI to another UCI. The %RSEL utility is called to select the routines.  The user then is prompted for the name of the UCI to which the routines are to be copied.  The user must specify a UCI name different than the name of the current UCI.

The user is given the option of selectively copying the programs.  This allows some or all of the routines to be copied and allows renaming of each program if desired. If the selective copy option is chosen, the user is prompted with each routine name before it is copied and given three choices: <Y/N/R>

Value	Description
Y(es)	Copy the routine as named.
N(o)	Do not copy the routine.
R(ename)	Rename the routine before copying it. Only the copy will be renamed, the original will not. If Rename is chosen, the user is prompted for the new name. If the name is provided, the routine will be copied using the new name.  An up-arrow (^) may be input to this prompt if the user decides not to copy the programs.
If the user does not copy selectively, copying begins immediately.  As each routine is copied, the name of the routine is displayed.  When copying is complete, a message is displayed.  Routines which have been saved without source code cannot be copied over a network using this utility.


^%RD

Lists the routine directory.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%RD

This utility lists, in alphabetical order, the names of every routine saved in the current directory.  As a heading, it lists the name of the UCI and volume group, and the date and time.


^%RDEL

Deletes routines.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%RDEL

This utility is used to delete one or more routines from the current UCI. The %RSEL utility is called to select the routines to be deleted.  It then prompts the user to verify that the routines are to be deleted.  As each routine is deleted, the name of the routine is displayed.


^%RPRT

Prints routines.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%RPRT

This utility prints one or more routines to a user-selected device. The utility calls %RSEL to select the routines and %SDEV to select the output device.  The user is also prompted for the number of lines per page and the number of characters per line.

For each routine that is printed, a header line is displayed that includes the name of the routine, the name of the UCI where the routine is stored, and the date and time the routine was printed.  If the number of characters per line is greater than 80, the user is also prompted for a comment that appears in the header line.

During printing, lines that are longer than the specified number of characters per line are split across multiple lines.  Periods are inserted in the listing to show where spaces were inserted by the print utility.


^%RR

Restores routines.

Description

To start the utility: from the Tools menu, select Routines and then select Restore; or from the Tools menu, select Command Window and then enter:

DO ^%RR

This utility is used to restore routines that were saved using the %RS utility.  The routine calls the %SDEV utility to select the input device.  The device may be a host file or a tape unit.  After the device is selected, the utility reads the first two records from the device (the header information saved by the %RS utility) and displays it on the terminal. The header information includes the date and time that the routines were saved and the user comment that was specified when the routines were saved.  This allows the person doing the restore to verify that the correct file is being used before the actual restore operation begins.

When restoring the routines, the user is asked whether or not a selective restore is to be performed; if so, then the user can specify which routines are to be restored, rename routines as they are being restored, skip forward in the restore process until a specified routine is reached, or continue restoring with prompts until a specified routine is reached.  If the user responds NO to the selective restore prompt, then all routines will be restored.  As each routine is restored, the name of the routine is displayed.

When restoring routines with no source code, %RR restores only the p-code version that matches the volume group characteristics.  If a routine already exists, and an attempt is made to restore it, but the required p-code type was not saved, then the existing routine is deleted.  A list of all routines not restored because the correct p-code type was not saved is then created in the global ^UTILITY("%RR",$J).


^%RS

Saves routines.

Description

To start the utility: from the Tools menu, select Routines and then select Save; or from the Tools menu, select Command Window and then enter:

DO ^%RS

This routine is used to output one or more routines to a sequential device. For terminal and printer type devices, the %RP^%RPRTRT utility should be used since it produces output tailored for these devices.  This utility's format is as follows:

date and time in external format

comment supplied by the user

routine name

routine body

.

.

.

routine name

routine body

null line to terminate the file

The routine calls the %SDEV utility to select the output device.  It then prompts for the size of the output media in 1-K blocks. After the utility has written the specified number of blocks, it prompts the user to replace the media with the next one in the sequence. Finally, the user is prompted for a comment to be used in the dump header and then the %RSEL utility is called to select the routines to be saved.  If no source code is available for a selected routine, whatever p-code exists for the routine is saved.


^%RSAND

Searches routines for multiple strings which are simultaneously present.

Description

To start the utility: from the Tools menu, select Routines and then select Multi-string Search; or from the Tools menu, select Command Window and then enter:

DO ^%RSAND

This utility searches one or more routines for one or more user-specified strings.  A match occurs if a routine contains all of the user-specified strings.  The utility calls the %RSEL utility to select the routines that are to be searched and the %SDEV routine to select the output device where the list of routines that match the search criteria will be printed. The user is then prompted for the search strings.


^%RSE

Searches routines for one or more strings.

Description

To start the utility: from the Tools menu, select Routines and then select Search; or from the Tools menu, select Command Window and then enter:

DO ^%RSE

This utility searches one or more routines for one or more user-specified strings. A match occurs if a routine contains any of the user-specified strings. The utility calls the %RSEL utility to select the routines that are to be searched and the %SDEV routine to select the output device where the list of routines that match the search criteria will be printed.  The user is then prompted for the search strings.


^%RSEL

Selects one or more routine names.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^%RSEL

This utility is a general-purpose routine that is used to select one or more routine names from the routine directory of the current UCI.  All of the MSM utility routines that prompt for routine selection use this utility.  To select the routines, the %RSEL utility uses the $ORDER function to step through the routine directory.  Each routine name returned by the $ORDER function is examined using the criteria specified by the user.  If the routine name matches the specified criteria, then the routine is selected.  Otherwise, it is skipped and the next routine name is examined.

The user may specify a single routine name (ABC), a range of routine names (AAA-HZZZ), a routine name prefix (AB*), a wild-card character that matches any single character (AB?DE), or all routines (*).  The selection criteria may be preceded by a minus sign (-) to delete the corresponding entries from the list of selected routines.

Selected routines are stored in the UTILITY global in the following format:

^UTILITY($J,RoutineName)=""

In this example, $J is the job number of the current job and RoutineName is the name of the routine.  If a list of routines already exists under the job number, the user can enter a period (.) to use the existing list of routines.  When this is done, the utility  displays the existing list and prompts for additional routine selection criteria.


^%RSIZE

Displays routine sizes.

Description

To start the utility: from the Tools menu, select Routines and then select Size; or from the Tools menu, select Command Window and then enter:

DO ^%RSIZE

This utility is used to display the size of one or more routines.  The user is prompted for the routines to be displayed and the output device for the report.  The report consists of the routine name, the number of p-code and text blocks that exist for the routine, and the total number of blocks for the routine.


^%SDEV

Selects a device for input/output.

Description

This utility is used to select a device for input or output. The device may be a terminal, a printer, the current device, or a Host File Server (HFS) device. The utility opens the device and returns the selected device number in the %DEV local variable.  If an error occurs such that the requested device cannot be opened or if the user does not select a device, the QUIT local variable will be defined and set to null when the routine terminates. The calling routine should test for this condition before trying to access the device.

If the device being opened is a Host File Server device, the utility calls the Windows common dialog for file selection. It also returns the name of the host file in the %FN local variable and the value of the $ZA special variable in the %ZA local variable.  The routine supports the following internal entry points.

Entry point	Action
^%SDEV	Prompts for an output device with the Host File Server as the default.
OUT^%SDEV	Prompts for an output device with the Host File Server as the default.
IN^%SDEV	Prompts for an input device with the Host File Server as the default.
PR^%SDEV	Prompts for an output device with device 3 (the printer) as the default.
CRT^%SDEV	Prompts for an output device with the current device number as the default.
P0^%SDEV	Prompts for an output device with the device number 0 (zero) as the default.


^%T

Returns current time in external format, or converts a time from internal to external format.

Syntax

INT^%T	; ignores %H and returns the current time

INTT^%T	; %H time

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%H	Input	Time in $H format. Used by INTT entry point only.
%TIM	Output	Time in HH:MM format (24-hour time).
%TIM1	Output	Time in HH:MM AM/PM format.
Description

The INT entry returns the current time; the INTT entry returns the external time for the numeric date passed in the second comma piece of %H.

Sample terminal session

>K

>D INT^%T

>W

%TIM="10:39"

%TIM1="10:39 AM"

>S %H=",80000"

>D INTT^%T

>W

%TIM="22:13"

%TIM1="10:13 PM"

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.

The $ZHL function provides identical functionality and  many additional formatting options.


^%TI

Converts an external time in virtually any recognizable format to its corresponding internal format.

Syntax

^%TI

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%TS	Input	Time in external format.
%TN	Output	Time in internal format, or undefined if an error occurred.
%ER	Output	Undefined if no error occurred, -1 if an error occurred.
Description

The internal time format ($HOROLOG) value is the number of seconds past midnight. The time to be converted is passed to the routine in the %TS local variable. The time may be in any of the following formats:

11:23PM

23:23

12NOON

12MIDNIGHT

11 (assumes 11:00 AM)

13 (assumes 1:00 PM)

The words AM, PM, NOON, and MIDNIGHT can be abbreviated using one or more consecutive letters of the word (for example, NO for NOON). The space character can be used in place of the colon (:). If minutes are not specified, the system assumes zero minutes past the hour.

Sample terminal session

>K

>S %TS="18:36"

>D ^%TI

>W

%TN=66960

%TS="18:36"

>S %TS="6:36 PM" D ^%TI W

%TN=66960

%TS="6:36 PM"

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.


^%TO

Converts an internal time to an external format.

Syntax

^%TO	; 24-hour form

100^%TO	; 12-hour form

Arguments are passed in local variables rather than as parameters.

Variable	Type	Description
%TN	Input	Time in internal (numeric) format.
%TS	Output	Time in external (string) format in 24-hour form (HH:MM) or 12-hour form (HH:MM AM/PM) depending on the entry point used.
%ER	Output	Undefined if no error occurred, -1 if an error occurred.
Sample terminal session

>K

>S %TN=60000

>D ^%TO

>W

%TN=60000

%TS="16:40"

>D 100^%TO W

%TN=60000

%TS="4:40 PM"	;note the space

>K

>D ^%TO

>W

%ER=1

This is an older utility that communicates using local variables rather than parameter passing.  Unless the New command is used to protect the variables used by this utility, errors may occur if identically named variables are being used at outer levels of the application.

The $ZHL function provides identical functionality and many additional formatting options.


^VALIDATE

Validates database integrity.

Description

To start the utility: from the System menu, select Databases and then select Validate; or from the Tools menu, select Command Window and then enter:

DO ^VALIDATE

This utility is used to validate the integrity of an MSM volume group (all volumes of the volume group). It will validate, within a specified UCI, all routines, one or more globals, or both routines and globals.  The user is prompted for the name of the volume group and the UCI to be validated, and if globals are being validated, which globals.  If an error is encountered, the utility displays the block number in error, the offset within the block where the error occurred, and a description of the error.

If all UCIs on a Volume Group are selected for validation, VALIDATE checks the map blocks on that Volume Group. If all Volume Groups are selected, all system map blocks are checked. A map block can be checked independently of this utility using the VERIFY utility.

MSM-Workstation uses automatic before-image journaling which should prevent database corruption.  The VALIDATE utility is provided as a means of certifying that this is the case.  Should corruption be detected, the host file constituting the database must be replaced with a backup copy. Alternatively, repair may be possible using the DBFIX utility.

The VALIDATE utility includes a label called AUTO which checks the integrity of all mounted volume groups without user interaction.  In addition, invoking AUTO^VALIDATE checks all map blocks as when the VERIFY utility is run.  Errors are returned in the %ERR variable; its format is described below.

%ERR	Meaning
0	No errors found.
1	Errors found and returned in %ERR() array.
2	Abnormal termination. Value of %ERR is returned via S %ERR="@,"_$2E.
3	Device 63 is not available.
The %ERR array of errors has the following format:

%ERR(n)=

Data Format	Description
M Vgindex errcode	Map block errors
R UCI,VGN errcode	Routine errors
G UCI,VGN ^globalname errcode	Global errors
n is an integer starting with 1; errcode is the error code returned by the $ZVERIFY function.

Refer to the MSM Language Reference Manual for a complete list of $ZVERIFY error codes. To print the errors, an output device must be OPENed before calling AUTO^VALIDATE and the device name must be set into the %DEV variable.


^VERIFY

Verifies map blocks.

Description

To start the utility: from the Tools menu, select Command Window and then enter:

DO ^VERIFY

This utility is used to verify that the free-space count in each map block agrees with the individual entries in the map block that indicate whether the block is free or in use.  The utility reads in each map block in a volume group (all volumes of the volume group) and counts the number of free blocks. If the derived count agrees with the stored count, then a check successful message is displayed.  If not, it displays the volume number and block number, the offset, and a message that the count of free blocks is wrong.  If errors are not corrected, the system will still operate properly; however, performance will degrade. Use the DBFIX utility to correct counts.


^%VIDEO

Alters contents of the video buffer belonging to the current console window device.

Syntax

GET^%VIDEO(.Buffer,X,Y,NumCols,NumRows,Mode)

PUT^%VIDEO(Buffer,X,Y,NumCols,NumRows,Mode)

Parameter	Type	Description
Buffer	Output	For GET, a reference to a variable where the video information will be stored.
Buffer	Input	For PUT, a reference to a variable holding the video information.
X	Input	The location of the column of the upper left corner of the rectangle that is to be accessed.  The first column of the screen is 0.
Y	Input	The location of the row of the upper left corner of the rectangle that is to be accessed. The first row of the screen is 0.
NumCols	Input	The number of columns in the rectangle that is being accessed.
NumRows	Input	The number of rows in the rectangle that is being accessed.
Mode	Input	A value indicating what type of information is to be extracted from or inserted into the video buffer.  The values are as follows: 0 = Text values only 1 = Video attributes only 2 = Text and video attributes
Description

This utility is used to alter the contents of the video buffer belonging to the current console window device. It allows programs to extract information from or insert information into the video buffer.  The routine can access the data and video attributes, just the video attributes, or just the data for any rectangular area of the screen.  The routine is called using parameter passing with one of the following formats:

DO GET^%VIDEO(.Buffer,X,Y,NumCols,NumRows,Mode)

DO PUT^%VIDEO(Buffer,X,Y,NumCols,NumRows,Mode)

A Buffer in the GET subroutine can be specified only by using call-by-reference. Unless the Buffer is specified, the function will not work properly.  The PUT subroutine uses call-by-value parameter passing (no period (.) precedes the Buffer specification).


^%ZSTIME

Displays routine time stamps

Description

To start the utility from the Tools menu, select Command Window and then enter:

DO ^%ZSTIME

This utility is used to display the last-saved time of one or more routines.  The user is prompted for a sort option and the routines to be displayed.  The report consists of the routine name, date, and time saved.  The sort option may be by routine name, or by save time (chronological or reverse chronological).

These routine save times come from the routine directory itself rather than from textual time stamps added by editors, so the times are guaranteed to be present and accurate.


%G Editor

To invoke the %G full-screen character-mode editor, from the Tools menu, select Routines/Editor. Alternatively open a Command Window and enter the following M command:

X ^%G

If there is a program in the user's partition, it is loaded by the editor.  Otherwise, the editor initializes an empty workspace in which a new program can be created.

See Also:

Editor Screen Layout

Using the Workspace

Dialog Boxes

File Menu

Edit Menu

Search Menu

Window Menu

Help Menu

Customizing the %G Editor


Editor Screen Layout

The main editor screen consists of a title bar at the top of the screen, a menu bar on the line below the title line, and a status bar on the last line of the screen.  The area between the menu bar and the status bar is referred to as the workspace.

The title line contains the notation "MSM Routine Editor," followed by the name of the routine that is being edited.  If the routine is unnamed, the title line displays <noname> where the routine name is normally placed.  The title line also displays the name of the UCI and Volume Group that contain the routine being edited.

The menu bar contains a list of the available high-level menu actions:  File, Edit, Search, Options, Window, and Help.  To access the menu, press F10, which highlights the menu bar and positions the cursor on the File option.  Use the LEFT ARROW and RIGHT ARROW to position the cursor at the appropriate menu item and then press ENTER to select the menu item.

For performance reasons, pull-down menus are not used on terminal devices.  Instead, when the menu is accessed with F10, the menu bar is replaced with a menu bar that contains sub-menu items. After you use the arrow keys to highlight a menu item, either press ENTER or enter the highlighted letter to select the item.

The status bar, which is used to display information about the editing process, consists of two areas separated by a vertical bar. The left side of the status bar displays context-sensitive help information.  When no specific editor operation is in progress, the area displays the function keys that are used to obtain Help information, mark text (select), and activate the menu bar.

When an editor operation is active, this area displays information about the operation being performed.  For example, when a menu item is selected, the Help area displays a one-line description of the selected function.  When no editor operation is active, the editor displays a legend that lists the most commonly used function keys.

The right side of the status bar displays status indicators, the name of the currently invoked menu item, and the current time of day.  The status indicators include the following:

•	A number greater than one which indicates the number of open windows (a blank is displayed if only one window is open).

•	The letter M if the program in the workspace has been modified (a blank is displayed if the program is not modified).

•	The letter O if the editor is operating in overlay mode (a blank is displayed if the editor is in Insert mode).

•	The letter R if the program has been loaded as read-only (a blank is displayed if the program was loaded for read and write).


Using the Workspace

When the editor is invoked, the cursor is positioned in the upper-left corner of the workspace.  By default, the editor is in Insert mode; when characters are entered, they are inserted into the routine at the current cursor location.

Use cursor keys to navigate around the workspace. The arrow keys, PGUP, PGDN, HOME, and END move the cursor a specified distance.  When left and right arrows, HOME, and END are used in combination with CTRL, the amount of cursor movement is increased.  Use BACKSPACE to delete the character immediately before the cursor and DELETE to delete the character under the cursor.

Use INSERT to toggle between Insert mode and Overlay mode. When the editor is in Insert mode, pressing  INSERT switches the editor into Overlay mode. When this occurs, the letter O is displayed on the right side of the status line. When you enter a character in this mode, it overlays the character under the current cursor position.  If  you press INSERT again, the editor switches to Insert mode and the letter O in the status line is replaced with a blank.

To perform editing operations, position the cursor on the appropriate spot in the program and then select a function using the menu, function keys, or shortcut keys.

The following table lists the cursor positioning keys and their actions.

Cursor Movement Keys

Key	Action
	Moves cursor left one character.
	Moves cursor right one character.
	Moves cursor up one physical line.
	Moves cursor down one physical line.
HOME	Moves cursor to beginning of line.
END	Moves cursor to end of line.
PGUP	Pages back one screen.
PGDN	Pages forward one screen.
You can access all of the editing functions from the menu bar. For greater efficiency, you can access many of the functions directly using the function keys and without invoking the menu.

The following table lists the function keys and their actions.

Function Keys

Key	Action
F1	Displays context-sensitive Help information.
F2	Copies marked text to the Paste buffer.
F3	Cuts marked text and stores it in the Paste buffer.
F4	Inserts contents of the Paste buffer at the current location (to the left of the cursor).
F5	Undoes the last editing change.
F6	Changes a specified text string to a new text string.
F7	Finds an occurrence of a specified text string.
F8	Finds the next occurrence of a specified text string.
SHIFT+F8	Finds the previous occurrence of a specified text string.
F9	Selects text for a Cut, Copy, or Delete operation.
F10	Activates the menu bar.
F12	Cancels the current dialog box.
ESC	Cancels the current dialog box.
In addition to the editing functions, the menus provide access to other functions, including: loading and saving programs, marking text, escaping to the MSM Programmer Shell, and so on. All of these functions can be accessed from the menu. In addition, shortcut keys (formerly referred to as accelerator keys) which allow functions to be directly accessed without using the menu, are provided for the most commonly accessed functions.

The following table lists the shortcut keys and their actions.

Shortcut Keys

Key	Action
CTRL+A	Inserts line above current line.
CTRL+B	Switches to the previous open window.
CTRL+C	Closes the current window.
CTRL+E	Opens the MSM Command Window.
CTRL+F	Finds an occurrence of a specified string.
CTRL+G	Finds the next occurrence of a specified string.
CTRL+J	Jumps to a Label or a Label+Offset.
CTRL+K	Marks the current or next word in the line.
CTRL+L	Marks the current line.
CTRL+N	Switches to the next open window.
CTRL+O	Opens a new window.
CTRL+P	Prints the routine in the current window.
CTRL+R	Loads a routine into the current window.
CTRL+S	Saves the routine in the current window.
CTRL+T	Checks the syntax of the routine in the current window.
CTRL+U	Undoes all editing changes to the current line.
CTRL+V	Views the list of open windows.
CTRL+W	Equivalent to CTRL+S.
CTRL+X	Exits the editor and saves routine if modified.
CTRL+Y	Highlights all strings that match the Find string.


Dialog Boxes

The %G editor uses dialog boxes that prompt you to enter information. A dialog box is a pop-up window that contains a title describing the function, one or more fields which you must complete, and one or more action buttons.  Use the arrow keys or TAB to move from field to field. After you position the cursor in a field, press F1 to obtain Help information. If you press F1 a second time, the system displays a higher level of Help information.  Alternatively, press ?  to obtain online Help.

The action buttons are displayed at the bottom of the dialog box. The default button (the button selected when you press ENTER) is highlighted using a color or reverse-video.  Use the arrow keys or TAB to move the highlighting from button to button.


File Menu

To access the File menu, press F10 followed by the F key.  When you invoke the File menu, the menu options are displayed.  To select an option, use the arrow keys followed by ENTER, or enter the highlighted letter in the option. An option name followed by three periods (...) indicates that a dialog box will be displayed when the option is selected.  If the menu item has a shortcut key, it is displayed to the right of the menu option.

The following options are displayed when the File menu is selected.

File Options

Option	Description
New	Creates a new routine.  If the current window contains a routine that is modified, then a new window is created; otherwise, the current window is used.  A dialog box prompts you to enter the name of the routine to be created.
Retrieve	Loads a previously created routine into the workspace of the current window. A dialog box prompts you to enter the name of the routine to be retrieved and the edit mode (edit or read-write).  The editor also displays the current UCI and volume group from which the routine is to be retrieved. Use CTRL+R as an accelerator to access this option.
Save	Saves the routine in the workspace of the current window. The routine is saved without user interaction if the name on the first line is the same as the current routine name and the routine contains no syntax errors.  Otherwise, a dialog box prompts for an action. Use CTRL+S  or CTRL+W as a shortcut to access this option.
Save as	Saves the routine in the workspace of the current window and specifies a new name for the routine. In the dialog box, enter the new name of the routine.  If this name already exists, the system prompts you to verify whether the routine should be overlaid.
Delete	Deletes from disk the routine in the workspace of the current window. The editor prompts you to verify the delete action before it is performed.
Print	Prints the routine in the workspace of the current window.  In the dialog box, enter the number of lines per page, characters per line, header comment, output device, and output device parameters.  Use CTRL+P as a shortcut to access this option.
Syntax	Performs a syntax check of the routine in the workspace of the current window.  If an error is detected, a message is displayed and the error is highlighted.  Use CTRL+T as a shortcut to access this option.
Shell	Invokes the MSM Programmer shell.  Once in the shell, you can enter M commands as you would in direct programmer mode. To return to the editor, enter the QUIT command.  Use CTRL+E as a shortcut to access this option.
Exit	Exits the editor. If the workspace contains a modified program, a dialog box  prompts you to save or discard the modified program or return to the editor. Use CTRL-Q  or CTRL-X as a shortcut to access this option.


Edit Menu

To access the Edit menu, press F10 followed by the E key.  When you invoke the Edit menu, the menu options are displayed. To select an option, use the arrow keys followed by ENTER, or enter the highlighted letter in the option.  An option name followed by three periods (...) indicates that a dialog box will be displayed when the option is selected.  If the menu item has a shortcut key, it is displayed to the right of the menu option.

The following options are displayed when the Edit menu is selected.

Edit Options

Option	Description
Undo	Undoes the last editing operation. For example, if the last operation was a Cut, Undo restores the deleted text.  If you immediately reselect Undo, the restored text is deleted. This option only undoes changes to the current line and only if the cursor has not left the line since the changes were made.  Use F5 or CTRL+U as a shortcut to access this option.
Select	Marks text within the workspace.  When you select this option, the character under the cursor is marked either by highlighting the character with reverse-video or with the color red. To extend the mark, use the arrow keys or the arrow keys in combination with CTRL.  After an area is marked, it can be Cut, Copied, or Deleted.  Use F9 as a shortcut to access this option.
Copy	Copies the marked text to the Paste buffer. After the operation is complete, the text becomes unmarked. Use F2 as a shortcut to access this option.
Cut	Deletes the marked text and places it in the Paste buffer. Use F3 as a shortcut to access this option.
Paste	Inserts the text contained in the Paste buffer at the location immediately to the left of the cursor.  Use F4 as a shortcut to access this option.
Delete	Deletes the marked text. The deleted text is not placed in the Paste buffer.  Use DELETE as a shortcut to access this option.


Search Menu

To access the Search menu, press F10 followed by the S key.  When you invoke the Search menu, the menu options are displayed.  To select an option, use the arrow keys followed by ENTER, or enter the highlighted letter in the option.  If the menu item has a shortcut key, it is displayed to the right of the menu option.

The following options are displayed when the Search menu is selected.

Search Options

Option	Description
Find	Searches for a specified string of text.  When this option is selected, a dialog box prompts you for the search string, the match case (any case or match the specified case), the search direction (forward or backward), and the action to take when the end-of-routine is reached (either wrap around to the beginning or stop).  Use F7 or CTRL+F as a shortcut to access this option.
Change	Searches for a specified string of text and replaces it with a new text string.  When you select this option, a dialog box prompts you to enter the search string, the replace string, the match case (any case or match the specified case), the search direction (forward or backward) and the action to take when the end-of-routine is reached (wrap around to the beginning or stop).  Use F6 as a shortcut to access this option. When the Change operation finds an occurrence of the search string in the program, a pop-up window prompts you to enter a change action. Specify Change to replace the highlighted occurrence and search for the next occurrence; Once to change the highlighted occurrence and quit; Skip to leave the highlighted occurrence unchanged and to search for the next occurrence; All to replace the highlighted occurrence and all other occurrences without further prompting; or Quit to terminate the change operation.
Next	Repeats the previous Find operation.  The search begins at the current location and proceeds toward the end of the routine.  At the end of the routine, the search either stops or wraps to the beginning of the routine, depending on the option selected in the Find operation. Use F8 or CTRL+G as a shortcut to access this option.
Previous	Repeats the previous Find operation.  The search begins at the current location and proceeds toward the beginning of the routine.  At the beginning of the routine, the search either stops or wraps to the end of the routine, depending on the option selected in the Find operation.  Use SHIFT+F8 as a shortcut to access this option.
Jump	Moves the cursor to a specified location in the routine.  When this option is selected, a dialog box prompts you to enter the line label where the cursor is to be positioned.  The label may include a plus or minus offset (for example: CUST+3, FILE-4), or an absolute offset from the beginning of the routine (for example: +8) can be specified. Use CTRL+J as a shortcut to access this option.


Window Menu

To access the Window menu, press F10 followed by the N.  When you invoke the Window menu, the menu options are displayed.  To select an option, use the arrow keys followed by ENTER, or enter the highlighted letter in the option. An option name followed by three periods (...), indicates that a dialog box will be displayed when the option is selected.  If the menu item has a shortcut key, it is displayed to the right of the menu option.

The following options are displayed when the Window menu is selected.

Window Options

Option	Description
Open	Opens a new window in the editor.  When you select this option, the editor creates a new window with an empty workspace and then displays the new window. The count of open windows in the status bar then is increased by one.  Use CTRL+O as a shortcut to access this option.
Close	Closes the current window in the editor.  Before closing the window, the editor determines whether the window contains a modified program.  If it does, a dialog box prompts you to either save or discard the program.  Use CTRL+C as a shortcut to access this option.
Next	Switches to the next open window in the chain of active windows.  When the end of the chain is reached, the operation wraps to the start of the chain. Use CTRL+N as a shortcut to access this option.
View	Displays a list of all open windows.  The list includes the name of the program being edited, number of lines in the program, and program status (read-only or modified).  To position the cursor in the list, use the arrow keys and then press ENTER to switch to the highlighted window. Use CTRL+V as a shortcut to access this option.


Help Menu

To access the Help menu, enter F10 followed by the H key.  When you invoke the Help menu, the menu options are displayed.  To select an option, use the arrow keys followed by ENTER, or enter the highlighted letter in the option. An option name followed by three periods (...), indicates that a dialog box will be displayed when the option is selected.  If the menu item has a shortcut key, it is displayed to the right of the menu option.

The following options are displayed when the Help menu is selected.

Help Options

Option	Description
Help	Displays instructions for using the Help facility of the %G editor.
Cursor	Lists the cursor keys supported by the editor and their actions.
Functions	Lists the function keys supported by the editor and their actions.
Accelerators	Lists the accelerator (shortcut) keys supported by the editor and describes their actions.
Procedures	Lists commonly used editor procedures and instructions on how to perform them. To display information on a particular procedure, use the arrow keys to highlight the item and then press ENTER.
About	Displays the current release level of the %G editor.


Customizing the %G Editor

You can customize the behavior and appearance of the %G editor to some extent by editing the global ^ZMSMG which contains definitions and settings for several editor properties.  The ^%G global itself is read-only.

Node	Purpose
^%G(540,<property>,<device type>,<option>)	Contains system-wide setting options.
Local settings are maintained in global ^ZMSMG. This global is initialized if it is not present, but it is never changed during use of the %G editor. When using a newer version of the %G editor on a database that already has a ^ZMSMG global defined, it may be necessary to reinitialize local settings. To do this, save a copy of ^ZMSMG (in case it contains local settings that you wish to preserve), KILL ^ZMSMG, and then start the %G editor.

You can modify the following nodes of ^ZMSMG:

Node	Purpose
^ZMSMG(540,<property>,<device type>,<option>)	Overrides system-wide setting alternatives specified in ^%G(540). This is rarely used.
^ZMSMG(550,<property>,<device type>)	Contains default settings for a UCI.
^ZMSMG(560,<port>,<property>,<device type>)	Contains port-specific settings for a UCI. This is rarely used.
where:

<property> = One of the following:

AUTO	Automatic <device type> determination if =1.
COLOR	The color scheme to use in the %G editor.
EOL	An expression to display a character representing end-of-line.
LINE1	The first-line time stamp convention when saving routines.
TIME	Show a clock if =1.
WTAB	A statement to display a character representing TAB.
<device type> = one of the following:

PC	PC console.
CANS	Color ANSI emulation (can be used on the console).
ANSI	Monochrome ANSI emulation (can be used on the console).
1	The default if device type is unspecified or irrelevant.
<option> =	Depends on the property; uses 1 if unspecified.
AUTO – Terminal Type Selection

By default, the terminal emulation type is determined automatically. PC is used on the console window devices, and ANSI is used on other devices. To turn off auto-selection and have the system prompt for terminal-emulation type, set the node:

^ZMSMG(550,"AUTO",1) = 0

COLOR – Color Schemes

You can modify the color scheme of the %G editor's editing area. The color scheme of the menu bar, status bar, and pop-up windows currently cannot be modified.

Built-in alternative color schemes are stored at:

^%G(540,"COLOR",1,<option>)

A <color scheme> is a set of pieces delimited by "^".  These pieces may be edited:

Piece	Description
2	Text color
3	Marked text color
17	Comments
18	Labels
19	Preprocessor directives
The format of each "^" piece is:

<hi-intensity>,<foreground>,<background>

where:

<hi-intensity> = 0 or 1

<foreground> = 30 + 1 (red) + 2 (green) + 4 (blue)

<background> = 40 + 1 (red) + 2 (green) + 4 (blue)

The default color setting for a device type is stored at:

^ZMSMG(550,"COLOR",<device type>) = <option>

A specific color setting for a port can be stored at:

^ZMSMG(560,<port#>,"COLOR",<device type>) = <option>

To add new color schemes or override built-in schemes, set the following:

^ZMSMG(540,"COLOR",1,<option>) = <color scheme>

EOL – End-of-Line Representation

To modify the display of the character that represents the end of line (EOL), edit nodes as shown below:

^ZMSMG(550,"EOL",<device type>) = <option>

Available options are listed in the parallel nodes of ^%G(540), including:

<option> =	2	For no characters at all.
	4	For arrows on Japanese terminals.
LINE1 – Routine First Line Time Stamp

To select the format of the time stamp placed on the first lines of routines when they are filed, edit the node:

^ZMSMG(550,"LINE1",1)=<option>

To create a new format, add a node:

^ZMSMG(540,"LINE1",1,<option>)=<expression>

Study the nodes under ^%G(540,"LINE1") for examples and existing options.

<option> =	0	First line not touched.
	1	Micronetics standard time stamp in last ";" piece.
	>1	May be customized; <expression> is placed in the third   ";"piece.
TIME – Show a Clock

By default, the current time is displayed on the status line. To turn off this clock, set the node:

^ZMSMG(550,"TIME",<device type>) = 0

WTAB – Tab

To modify the display of the character that represents TAB, edit the node:

^ZMSMG(550,"WTAB",<device type>) = <option>

Available options are listed in the parallel nodes of ^%G(540), including:

<option> =	3	For no characters at all.
	4	For arrows on Japanese terminals.
The MWAPI standard defines several functions and variables that are implemented in MSM-Workstation.  They are documented here.

Summary of Special Functions and Variables

Entry Point	Description
$EREF	Contains ssvn reference at which MWAPI error occurred
$PDISPLAY	Identifies the principal MWAPI device
$WFONT	Get character size information for a font
$WTFIT	Determine how many characters will fit in a given area
$WTWIDTH	Get the width of a text string


$EREF Special Variable

The form of address for $EREF is:

$ER[EF]

The information returned is an indication of the ssvn reference at which an MWAPI error was detected. The following are typical examples:

For	Value of $ER
Displays	^$DISPLAY(display,attribute)
Windows	^$WINDOW(window,attribute)
Gadgets	^$WINDOW(window,"G",gadget,attribute)
Gadget choices	^$WINDOW(window,"G",gadget,"CHOICE",choice,attribute)
Menus	^$WINDOW(window,"M",menu,attribute)
Menu choices	^$WINDOW(window,"M",menu,"CHOICE",choice,attribute)
Timers	^$WINDOW(window,"T",timer,attribute)


$PDISPLAY Special Variable

MSM-Workstation provides an additional variable:

$PD[ISPLAY]

This is an intrinsic svn that contains the identity of the principal MWAPI display associated with an MSM process. MSM-Workstation supports one display per process.


$WFONT Function

Return character size information for a given font.

Syntax

$WFONT(fface,fsize,fstyle,units)

Definition

Returns information in the given units about the font matching fface, fsize, and fstyle, in the form: fheight,fmaxchar,favchar

Units must be PIXEL, POINT, or ZDLG.

Return values:

Parameter	Description
fheight	Height of the character cell plus leading.
fmaxchar	Maximum width of a single character.
favchar	Average width of a single character.


$WTFIT Function

Returns number of characters that will fit in a given area.

Syntax

$WTFIT(string,int,fface,fsize,fstyle,units)

Definition

Returns the number of characters in the given text string that could be displayed in an area int units wide, using characters of the font matching fface, fsize, and fstyle. The value returned is the number of characters that can be fully displayed.

Units must be PIXEL, POINT, or ZDLG.


$WTWIDTH Function

Returns width of a text string.

Syntax

$WTWIDTH(string,fface,fsize,fstyle,units)

Definition

Returns the width in units of the given text string for characters of the font matching fface, fsize, and fstyle.

Units must be PIXEL, POINT, or ZDLG.


External Calls A-Z

External call	Description
AnsiToOem	Convert a string of characters from one code page to another
Beep	Beep or play a system sound
CALLENTRY	Call a named function in a DLL
ConvertPoint	Convert units of coordinates
FINDENTRY	Find a function in a DLL
FREELIB	Release a reference to a DLL
GetErrorMsg	Get a human-readable description of a system error message
GetHWND	Get a system handle for a window
GetVersionInfo	Read data from the version resource of a load image
LOADLIB	Get a handle to a DLL
LocalKeyName	Determine the local name for a key
MdiCascade	Resize and move MDI children into a cascade pattern
MdiIconArrange	Arrange minimized MDI children into an orderly grid
MdiTile	Resize and move MDI children into a tile pattern
OemToAnsi	Convert a string of characters from one code page to another
SendWindowMessage	Send a message to a system window
SetZOrder	Change the position of a system window within its Z-order
WinHelp	Interface to Windows help engine


External Calls by Function

Call functions in DLLs

Character conversion

Create Windows sounds

Get system information

Manipulate window size and position

Miscellaneous

Use Windows API

Use Windows Help Engine


Call functions in DLLs

External call	Description
CALLENTRY	Call a named function in a DLL
FINDENTRY	Find a function in a DLL
FREELIB	Release a reference to a DLL
LOADLIB	Get a handle to a DLL


Character conversion

External call	Description
AnsiToOem	Convert a string of characters from one code page to another
OemToAnsi	Convert a string of characters from one code page to another


Create Windows sounds

External call	Description
Beep	Beep or play a system sound


Get system information

External call	Description
GetErrorMsg	Get a human-readable description of a system error message
GetVersionInfo	Read data from the version resource of a load image


Manipulate window size and position

External call	Description
MdiCascade	Resize and move MDI children into a cascade pattern
MdiIconArrange	Arrange minimized MDI children into an orderly grid
MdiTile	Resize and move MDI children into a tile pattern
SetZOrder	Change the position of a system window within its Z-order


External Call Functions - External Calls by Function - Miscellaneous
Miscellaneous

External call	Description
LocalKeyName	Determine the local name for a key
ConvertPoint	Convert units of coordinates


Use Windows API

External call	Description
GetHWND	Get a system handle for a window
SendWindowMessage	Send a message to a system window


Use Windows Help Engine

External call	Description
WinHelp	Interface to Windows help engine


External Calls

CALLENTRY

FINDENTRY

FREELIB

GetErrorMsg

GetVersionInfo

LOADLIB

AnsiToOem

Beep

ConvertPoint

GetHWND

LocalKeyName

MdiCascade

MdiIconArrange

MdiTile

OemToAnsi

SendWindowMessage

SetZOrder

WinHelp


CALLENTRY

Examples	See also

Calls a named function in a DLL, passing 0 to 10 32-bit parameters.

Syntax

&MSM.CALLENTRY(Handle,Function,Params)

Parameter	Type	Description
Handle	Input	A DLL handle, as returned from MSM.LOADLIB.
Function	Input	The name of the function to call.
Params	Input	The value of this parameter is treated as an array of from 0 to 10 32-bit values.  If the byte length of the parameter is not a multiple of 4 it is rounded down to the nearest such multiple.  If the byte length of the parameter is greater than forty, the excess bytes are ignored
Description

CALLENTRY calls a named function in a DLL, passing 0 to 10 32-bit parameters.

When the function is called, the first value in Params is passed as the first parameter, the second value is passed as the second parameter, and so on.  Within Params, the bytes in each value are in descending order of significance.


This loads the USER32.DLL, finds function MessageBeep, calls it, and releases the DLL:

S dll=$&MSM.LOADLIB("USER32.DLL")

I dll D

.  I $&MSM.FINDENTRY(dll,"MessageBeep") D

.  .  S param=$C(0)_$C(0)_$C(0)_$C(16)    ; #00000010

.  .  D &MSM.CALLENTRY(dll,"MessageBeep",param)

.  D &MSM.FREELIB(dll)


FINDENTRY	FREELIB	LOADLIB


FINDENTRY

Examples	See also

Determines if a given function can be found in a DLL.

Syntax

$&MSM.FINDENTRY(Handle, FuncName)

Parameter	Type	Description
Handle	Input	A DLL handle, as returned from MSM.LOADLIB.
FuncName	Input	The name of the function to find.
Description

FINDENTRY determines if a given function can be found in a DLL.

The function returns non-zero if the function was found, zero otherwise.


CALLENTRY	FREELIB	LOADLIB


FREELIB

Examples	See also

Releases a reference to a DLL.

Syntax

$&MSM.FREELIB(Handle)

Parameter	Type	Description
Handle	Input	A DLL handle, as returned from MSM.LOADLIB.
Description

FREELIB releases a reference to a DLL.

The function returns True if it succeeded, False otherwise.


CALLENTRY	FINDENTRY	LOADLIB


GetErrorMsg

Examples

Get a formatted description for a system error in the user default language.

Syntax

$&MSM.GetErrorMsg(Error)

Parameter	Type	Description
Error	Input	A system error number
Description

GetErrorMsg gets a formatted description for a system error in the user default language.

If there is system defined description for the given error number, that description is returned.  If there is no description available, the message returned is of the form:

FormatMessage: The system cannot find message for message number 0xdddddddd in message file for Windows.

where 0xdddddddd represents the hexadecimal value of the given error number.

If the function fails, the message returned will instead be of the form:

FormatMessage(0xdddddddd): error message for failure


The command:

W $&MSM.GetErrorMsg(#80020009)

produces the output:

Exception occurred.

on Windows NT4 with English as the default language for the current user.


GetVersionInfo

Examples

Read data from the version resource of a load image.

Syntax

$&MSM.GetVersionInfo(File, Type, Info)

Parameter	Type	Description
File	Input	The name of the file in which to find the version resource.
Type	Input	Specifies the type of information to be retrieved.
Info	Output	Holds the requested data.  The data returned cannot exceed 256 bytes in length.
Description

GetVersionInfo reads data from the version resource of a load image.  The type of information to be retrieved is specified by Type, which may be one of the three forms:

\
\VarFileInfo\Translation
\StringFileInfo\LangCharSet\StringName

See the documentation of the Win32 API VerQueryValue for further information.

Return values

Value	Description
0	the function failed
-1	the function succeeded, but there is no data to return
1	the function succeeded, and the requested data is in Info


The following code:

S field="\StringFileInfo\040904E4\FileDescription"

S info=""

S result=$&MSM.GetVersionInfo("MSMWS002.DLL",field,.info)

W:result=1 info

produces the output:

 MSM-Workstation, Version 2.0.0


LOADLIB

Examples	See also

Gets a handle to a DLL.

Syntax

$&MSM.LOADLIB(DLL)

Parameter	Type	Description
DLL	Input	The name of the Dynamic Link Library to be loaded.
Description

LOADLIB gets a handle to a DLL, loading it if necessary.  MSM.FREELIB should be called to release the DLL when it is no longer needed.

The function returns the handle of the DLL, or 0 if the handle could not be obtained.


CALLENTRY	FINDENTRY	FREELIB


AnsiToOem

See also

Converts a string of characters from one code page to another.

Syntax

$&MWAPI.AnsiToOem(String)

Parameter	Type	Description
String	Input	A string of ANSI characters to be translated
Description

AnsiToOem converts a string of characters from one code page to another.  String is assumed to contain characters encoded using the current ANSI code page.  The result contains the same characters, where possible, encoded using the OEM code page.  Where a particular character does not appear in both code-pages, a system-defined character is substituted for it.

A simple example of a call to this function is:

S oem=$&MWAPI.AnsiToOem(ansi)


OemToAnsi


Beep

Beep or play a system sound.

Syntax

$&MWAPI.Beep(Type)

Parameter	Type	Description
Type	Input	Type of sound.  This parameter is optional.  If omitted, the sound produced is the standard beep using the computer speaker.
Description

Beep will produce a beep, or play a system sound configured through the Control Panel Sounds applet.

A simple example that will produce a beep sound is:

D &MWAPI.Beep("M,ERROR")

The return value, if called with function syntax ($&MWAPI), is True if the function succeeded, False otherwise.

Type options

Type	Description
M,DEFAULT	Default Beep or Default sound
M,ERROR	Critical Stop
M,INFO	Asterisk
M,QUEST	Question
M,WARN	Exclamation


ConvertPoint

Examples

Converts an (x,y) coordinate pair from one set of units to another.

Syntax

$&MWAPI.ConvertPoint(Point,Units,Id)

Parameter	Type	Description
Point	Input	A point specified relative to the origin of the window or gadget indentified by Id, in the form: x,y,units
Units	Input	The desired units
Id	Input	The ID attribute of a window or gadget in ^$WINDOW.
Description

ConvertPoint converts an (x,y) co-ordinate pair from one set of units to another.

The return value is a string specifying the point in the new units.  An empty string is returned if the given parameters are invalid.


The following command:

W $&MSM.ConvertPoint("1,1,CHAR","PIXEL",^$W("MyWindow","ID"))

produces a point specification, such as:

17,20,PIXEL

where the x and y coordinates are the width and height respectively of the maximum width character in the basis font for the given window.


GetHWND

Examples

Obtain a system handle for a gadget or window.

Syntax

$&MWAPI.GetHWND(Id)

Parameter	Type	Description
Id	Input	The ID attribute of a window or gadget in ^$WINDOW.
Description

GetHWND obtains a system handle for a gadget or window, allowing direct manipulation of the gadget or window through the system API.  Such manipulation is strongly proscribed.  By-passing the normal mechanisms can lead to inconsistent GUI states and unpredictable program behavior.

The return value is zero if the function failed, otherwise the handle of the main system window implementing the gadget or MWAPI window.


Return the hWnd of the window called "TEST":

S hwnd=$&MWAPI.GetHWND(^$W("TEST","ID"))

Return the hWnd of the gadget called "GADGET" on the window called "TEST":

S hwnd=$&MWAPI.GetHWND(^$W("TEST","G","GADGET","ID"))


LocalKeyName

Examples

Determine the local name for a key on the keyboard.

Syntax

$&MWAPI.LocalKeyName(Keycode)

Parameter	Type	Description
Keycode	Input	An MWAPI defined keycode.
Description

LocalKeyName determines the local name for a key on the keyboard.  The local name is supplied by the current keyboard driver and is normally in the language for which the keyboard is designed.

The function returns the local name for the given keycode, or an empty string if Keycode does not identify a key.


The command:

W $&MSM.LocalKeyName("SHIFT+ALT+ENTER")

might produce:

Alt+Shift+Enter


MdiCascade

Examples	See also

Arrange MDI children in a cascade pattern.

Syntax

$&MWAPI.MdiCascade(WindowName,SkipDisabled)

Parameter	Type	Description
WindowName	Input	The name of the MDI window
SkipDisabled	Input	If True, only the active MDI children of WindowName are rearranged.  If False, all its MDI children are rearranged.
Description

MdiCascade requests an MDI window to resize and move its MDI children into a cascade pattern.  The request may apply either to all the MDI children or only the active ones.


Cascade the MDI child windows belonging to the MDI parent "TEST":

D &MWAPI.MdiCascade("TEST")


MdiIconArrange	MdiTile


MdiIconArrange

Examples	See also

Arrange minimized windows.

Syntax

$&MWAPI.MdiIconArrange(WindowName)

Parameter	Type	Description
WindowName	Input	The name of the MDI window
Description

MdiIconArrange requests an MDI window to arrange all its minimized windows into an orderly grid.

The return value is –1 if ^$W(WindowName) is not an MDI window, otherwise 0.


Arrange the minimized icons in the MDI parent window "TEST":

D &MWAPI.MdiIconArrange("TEST")


MdiCascade	MdiTile


MdiTile

Examples	See also

Arrange MDI children in a tiled pattern.

Syntax

$&MWAPI.MdiTile(WindowName,Horizontal,SkipDisabled)

Parameter	Type	Description
WindowName	Input	The name of the MDI window
Horizontal	Input	If True, the windows are arranged one above another.  If False, the windows are arranged one beside another.
SkipDisabled	Input	If True, only the active MDI children of WindowName are rearranged.  If False, all its MDI children are rearranged.
Description

MdiTile requests an MDI window to resize and move its MDI children into a horizontal or vertical tile pattern.  The request may apply either to all the MDI children or only the active ones.

The return value is –1 if ^$W(WindowName) is not an MDI window, otherwise 0.


Tile the MDI child windows belonging to the MDI parent "TEST" one above another:

D &MWAPI.MdiTile("TEST",1)


MdiCascade	MdiIconArrange


OemToAnsi

See also

Converts a string of characters from one code page to another.

Syntax

$&MSM.OemToAnsi(String)

Parameter	Type	Description
String	Input	A string of OEM characters to be translated
Description

OemToAnsi converts a string of characters from one code page to another.  String is assumed to contain characters encoded using the current OEM code page.  The result contains the same characters, where possible, encoded using the ANSI code page.  Where a particular character does not appear in both code pages, a system-defined character is substituted for it.

A simple example is:

S ansi=$&MWAPI.OemToAnsi(oem)


AnsiToOem


SendWindowMessage

Examples

Send a message to a system window.

Syntax

$&MWAPI.SendWindowMessage(Handle,Message,WParam,LParam)

Parameter	Type	Description
Handle	Input	A system handle for the target window
Message	Input	The message number
WParam	Input	A 32-bit value, as required by the given message number.
LParam	Input	A 32-bit value, as required by the given message number.
Description

SendWindowMessage sends a message to a system window, and returns a 32-bit result code, as defined by the given message number.


Force the region pointed to by 'hwnd' to repaint itself by sending the WM_PAINT message to it:

D &MWAPI.SendWindowMessage(hwnd,15,0,0)


SetZOrder

Examples

$&Change the position of a system window within its Z-Order.

Syntax

$&MWAPI.SetZOrder(PlaceThis,AfterThis)

Parameter	Type	Description
PlaceThis	Input	The value of the ID parameter of an MWAPI window or gadget whose Z-order is to be changed.
AfterThis	Input	The value of the ID parameter of an MWAPI window or gadget behind which PlaceThis is to be inserted, or a special value described below.
Description

SetZOrder changes the position of a system window within its Z-order.  The window identified by PlaceThis is re-inserted into its Z-order after the window or position AfterThis.  If AfterThis is a window, it must be in the same Z-order list as PlaceThis, otherwise the function has no effect.  When drawn, a window appears in front of all windows that follow it in the Z-order, so the effect of this function is to make PlaceThis be drawn behind the window AfterThis or at the position AfterThis as appropriate.

AfterThis may be the value of the ID parameter of a window or gadget, or one of the following:

AfterThis options

Value	Description
Top	In front of all windows with the same topmost status
Bottom	Behind all other windows, losing topmost status
TopMost	In front of all topmost windows
NoTopMost	Behind all other topmost windows, losing topmost status
See the documentation of SetWindowPos in the Win32 API for further details.

Return values

Value	Description
0	Success
1	The PlaceThis parameter is invalid
2	The AfterThis parameter is invalid


Move window "TEST" to the top of the Z-order:

D &MWAPI.SetZOrder(^$W("TEST","ID"),"Top")

Move gadget "G1" on window "TEST" just behind "G2" on the same window:

D &MWAPI.SetZOrder(^$W("TEST","G","G1","ID"),^$W("TEST","G","G2","ID"))


WinHelp

Syntax

$&MWAPI.WinHelp(HelpFile,Command,Data)

Parameters

Parameter	Type	Description
HelpFile	Input	The name of the file, including the path if necessary, to be opened by the Help application.
Command	Input	Specifies the type of help requested.  See below
Data	Input	This parameter is required to provide the data for some values of Command.  It should be omitted if not required.  See below for the values of Command requiring data:
Description

This interface to the Windows help engine provides access to .HLP files. Use the following call:

DO &MWAPI.WinHelp(HelpFile,Command,Data)

If the outcome of the command needs to be checked, the following variant will set result to a return value defined later:

SET result=$&MWAPI.WinHelp(HelpFile,Command,Data)

HelpFile contains the path, if necessary, and the name of the help file to be displayed. The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file.

Command options

Command	Description
Command	Executes a Help macro or macro string.
Contents	Displays the topic specified by the Contents option in the [OPTIONS] section of the .HPJ file. This is for backward compatibility. New applications should provide a .CNT file and use the Finder command.
Context	Displays the topic identified by the given context identifier as defined in the [MAP] section of the .HPJ file.
ContextPopup	Displays in a pop-up window the topic identified by the given context identifier as defined in the [MAP] section of the .HPJ file.
Finder	Displays the Help Topics dialog, which displays the contents of help as a hierarchy of books.
ForceFile	Ensures that WinHelp is displaying the correct help file. If the incorrect help file is being displayed, WinHelp opens the correct one; otherwise, there is no action.
HelpOnHelp	Displays help on how to use Windows Help, if the WINHELP.HLP file is available.
Key	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index with the topics listed in the Topics Found list box.
MultiKey	Displays the topic specified by a keyword in an alternative keyword table.
PartialKey	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, or an empty string is given as the key, displays the Index tab.
Quit	Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application.
SetContents	Specifies the Contents topic. The Help application displays this topic when the user clicks the Contents button.
SetWinPos	Displays the Help window, if it is minimized or in memory, and sets its size and position as specified.
Command-specific options for Data

Command	Data
Command	String that specifies the name of the Help macro(s) to execute. If the string specifies multiple macro names, the names must be separated by semicolons. You must use the short form of the macro name for some macros because Help does not support the long name.
Contents	None
Context	The context identifier for the topic.
ContextPopup	The context identifier for a topic.
ForceFile	None
HelpOnHelp	None
Key	A keyword for the desired topic.
MultiKey	A string of the form: char,keyword where char is a footnote character identifying the alternate keyword table in the help file, and keyword is the keyword to be matched.
PartialKey	A keyword for the desired topic, or an empty string.
Quit	None
SetContents	The context identifier for the Contents topic.
SetWinPos	A string of the form: x,y,dx,dy,showcommand;secwindow  where x and y determine the help window's position, and dx and dy determine its size (units such that 0,0 is the top-left of the screen and its size is 1024x1024). showcommand is one of the following keywords: Hide, ShowNormal, ShowMinimized, ShowMaximized, ShowNoActivate, Show, Minimize, ShowMinNoActive, ShowNA or Restore.  In some cases x, y, dx, and dy are ignored, but they must always be present) secwindow gives the name of the secondary help-window, as defined in the help project file, to which the command applies.  If this is omitted, the preceding semicolon is still required, and the command applies to the main help window.
Return values

Value	Description
1	Call to WinHelp failed
2	Call to WinHelp succeeded
-1	Insufficient memory to complete the call
-2	Invalid window position
-3	Invalid multi-key specification
-4	Invalid context identifier
-5	Unrecognised Command
-6	Invalid show parameter


Workstation as an Automation Controller

Automation (formerly OLE Automation) is a feature of the Component Object Model (COM), an industry standard used by applications to expose objects to development tools and other applications. Increasingly, new applications and development tools provide support for this technology, allowing them to control, or be controlled by, other applications or tools.

Workstation gives you the ability to control other programs that expose a COM interface. This could be used to load a document into a word processor, format and print it; to send an email message; or to check a file out of a source control program.

For an example we will use Workstation to control MSM-Activate/COM as this is likely to be installed on your system. For information on the properties and methods supported by MSM-Activate/COM, refer to the documentation provided with it. The techniques illustrated will work equally well for an application like Microsoft Word, Microsoft Excel, etc. if you change the objects, properties and methods that are used.

See Also:

Creating an Automation object

Accessing Properties and Methods

Large Strings

Arrays

Data Type Conversions

MSM-Activate and Workstation

Object Errors


Creating an Automation object

The first step in controlling another application via Automation is to create an instance of the object that you wish to control.  Use either the $ZCREATEOBJECT or $ZGETOBJECT function for this purpose. Refer to the MSM Language Reference Manual for additional information.

To create an instance of the 'M.Command' object and store the reference to it in an M local variable named 'ObjRef':

ZSET ObjRef=$ZCREATEOBJ("M.Command")

To create an instance of the object associated with the .MCO file extension (which is normally the M.Command MSM-Activate object) and load this object with the information contained in the C:\TEST.MCO file:

ZSET ObjRef=$ZGETOBJ("C:\TEST.MCO")

The $ZCREATEOBJ or $ZGETOBJ are used to create the object, and the ZSET command assigns the object reference (oref) returned from the function into the local variable. An oref can only be assigned to a local variable. It may be stored at a subscripted level of the variable, but cannot be used as a key. Globals cannot hold orefs. See the MSM Language Reference for more details about the ZSET command.

Each time an oref is assigned to a local variable, the object it references will increase its reference count by one. When a local variable element containing an oref is destroyed, the object will decrement its reference count by one. This destruction may occur as a result of an explicit KILL, an implicit kill (QUIT from context in which the variable was NEWed) or immediately before another value or oref is assigned to the same element.

What happens when an object's reference count reaches zero can vary, depending on the behavior of the server application which supplied the object. Some servers will shut down automatically, others will remain active. In the latter case, the controller may want to cause a shutdown before destroying its last reference, for example by using an appropriate method.

To discover if a local variable contains an oref, or if two orefs point to the same underlying object, use the $ZOBJREFERENCE function. See the MSM Language Reference for more details.


Accessing Properties and Methods

To access an object's properties or methods, follow the oref with '.' and then the name of the property or method. Note that unlike M local variable names, COM property and method names are case insensitive. However, if the name includes characters not valid within an M variable name, enclose the name in quotes. For example:

D deuword."DateiSchließen"

Indirection of property and method names is not supported.

To assign the value of the 'Type' property of the MSM-Activate/COM object instance created above:

S type=ObjRef.Type

To set the value of the property is just as easy:

S ObjRef.Type="TCPIP"

Methods can be accessed by DOing them. For example to run the Login method on the MSM-Activate/COM object:

D ObjRef.Login

Parameters

Some properties and methods take parameters. These are enclosed in parentheses after the property or method name. For example the Login method of the MSM-Activate/COM object can optionally take the password as a parameter. To call this passing the password 'TEST' use

D ObjRef.Login("TEST")

Expressions can also be used as parameters, and are evaluated first before passing the result as the method parameter:

S Pass1="T",Pass2="EST"

D ObjRef.Login(Pass1_Pass2)

A simple local variable name used as a parameter is passed by value. No changes which the method may make to the parameter are passed back to the M variable:

S Var="The message"

D ObjRef.Do("Tag^mycode",Var)

To pass a parameter by reference, the standard M by-reference parameter syntax is used:

D ObjRef.Do("Tag^mycode",.Var)

This format is also used for passing arrays and large strings to the object.

Optional parameters may be omitted.

Where the object supports named parameters, these may be used:

D anobj.ameth(third:="After",first:=$H)

Default Properties

If an object has a default property (MSM-Activate/COM does not) then the value can be returned by entering:

S Default=ObjRef

If ObjRef is used in any expression which is expecting a value and not an object reference, the value of the default property of ObjRef will automatically be used. If ObjRef does not have a default property then it reports an object error #80020003.

Chaining properties

It is quite legal to chain multiple properties one after the other as long as each property returns another object. So if ObjRef has a property called Object that is also an object and this has a property Name then you can enter

S Name=ObjRef.Object.Name

These multiple level references are always evaluated from left to right, so ObjRef.Object is evaluated internally to an object from which the Name property is obtained.


Large Strings

The largest local variable supported in MSM-Workstation is 32,764 bytes. However the COM string data type (BSTR) supports strings up to a theoretical limit of 4Gb. To overcome this mismatch you can use local arrays in Workstation to pass large strings as parameters to Automation servers.

To make a large string, create an M array in which each node contains a section of the full string. The subscripts are normally sequential integers starting at zero, but they can be anything you like as long as they collate in the desired order. Large strings must be passed as by-reference parameters to the Automation server. For example, to pass a string containing 64,001 space characters as the first parameter to the method called Method:

N Str

S Str(0)=$J("",32000),Str(1)=$J("",32000),Str(9)=" "

D ObjRef.Method(.Str)

In the above call, since Str is passed by reference the server can modify it and return another value. If it returns a short string, say "Hello", then on the return from this method Str="Hello" and the subscripts will have been killed. If it returns a large string, then an array under Str will be created with sequential integer subscripts starting at zero.

After passing a parameter by reference to a method it is important to check if it has returned a normal or large string or an array. The M program can determine whether or not a received string is large by looking at $DATA of the string. If $D is 1, then this is a normal-size string; if $D is 10, then it is a large string; and if $D is 11, then it is an array.

Note that because these large strings are held in locals, you must ensure that the M partition size can support the total size of all the variables that are likely to exist.


Arrays

To pass arrays to Automation servers we need to convert from an M array into a data type called a Safe Array. This is quite different from an M style array. For example, you need to specify the dimensions of the arrays.

To create an M array in MSM-Workstation which is compatible with this Safe Array, specify the number of dimensions in the array in the root node of the array, followed by the size of each dimension separated by the ~ character (ASCII 126). Then create the local array with integer sequential subscripts starting at zero. Any nodes that are not defined are assumed to be "". The array must be passed by reference to the method.

So a 3x5 array will have a base node of "2~3~5" because it has two dimensions, the first dimension has size of 3 and the second dimension's size is 5. Example M code to create this array and pass this by reference to a method called Method:

K Array

S Array="2~3~5"

N i,j

F i=0:1:2 D

. F j=0:1:4 D

..  S Array(i,j)=$R(100)

D ObjRef.Method(.Array)

When passing a parameter by reference to a method, Workstation detects if this is an array by looking to see if the root node conforms to the array format by having numbers separated by "~" symbols and then it checks that $D(Array)=11 so there is at least one element in the array defined.

To create a blank array ready for the Automation server to fill in, simply set the root node and one of the elements. For example, to create a 5x8x3 blank array

K Array

S Array="3~5~8~3"

S Array(0,0,0)=""

D ObjRef.Method(.Array)

Arrays can contain large strings that are stored in the same way as standard large strings—by using an extra level of subscripts. For example, instead of Array(x,y,z) having a string, it will be stored in Array(x,y,z,INDEX).

To determine if an item in an array is large, look at $D for the node. If it has descendents, then it is large; otherwise, it is a normal item. To create a 2x2 array with the first element being 64,000 characters of spaces

K Array

S Array="2~2~2"

S Array(0,0,0)=$J("",32000)

S Array(0,0,1)=$J("",32000)


External Access - Workstation as an Automation Controller - Data Type Conversions
Data Type Conversions

Workstation's internal data types differ from the standard COM variant data type. When Workstation calls an Automation server and passes any parameters, the data types are converted as follows:

Workstation Data Type	Example	Variant Data Type
Integer	5	VT_I4
Float	3.43 or 1E2 or 5.0	VT_R8
String	"Hello" or ""	VT_BSTR
Object Reference	$ZCREATEOBJ("M.Command")	VT_DISPATCH
Undefined Variable	'K Var' then Var is Undefined	VT_ERROR
Variable by reference	When you use the .VAR syntax	See below
If the variable is passed by reference, then the conversion to a variant data type follows these rules:

If Var is an Object then VT_DISPATCH | VT_BYREF

Else if Var is in array format then convert to VT_ARRAY | VT_BYREF

Else use the appropriate type from this table, with VT_BYREF added

If the parameter is passed by reference, then the value returned by the Automation controller is converted back to the original data type of the variable.

This can cause problems that you need to be aware of. For example, if you pass an Integer variable by reference to a function that returns a float, then the returned float value will be converted back to an integer. To make sure the returned value is a float, you must pass a float as input. This can be done by passing 1.0, which is a float data type, rather than 1, which is an integer.  Another strategy is to force both the input and return values to be strings by passing "1" as input.

This data type conversion can also cause problems when accessing properties that are sensitive to the input data type. For example, assume there is an Index property that takes either an integer index value or a string value of a unique key. If it is called with the following MSM code, it will receive a string value of "2", instead of the intended integer index value 2.

S Input="2.343"

S Num=$P(Input,".")

S Return=ObjRef.Index(Num)

This is because $PIECE returns a string value. This same problem can happen with global references, because all globals are stored as strings. If the property depends on a numeric parameter, you must  force the type conversion to a number with something like:

S Return=ObjRef.Property(+Num)


MSM-Activate and Workstation

Starting with MSM-Workstation 2.0, the array-passing facilities have been further enhanced to simplify use when an MSM-Workstation application uses the MSM-Activate/COM object to communicate with an MSM-Server system or with another MSM-Workstation application built as an Automation Server. In the former case, the MSM Server must have at least Version 4.4 of the MSM-Activate server routines, which are shipped with MSM-Server Version 4.4.0.

This capability transmits any M local array to the server system exactly as it is in MSM-Workstation. The server can modify it and the changes to the array will appear in Workstation. There is no need to deal with safe-array-compatible structures.

To use this capability, simply create the local array and pass it by reference in the DO call. For example:

ZSET MCommand=$ZGetObject("C:\TEST.MCO")

D MCommand.Login

S A="TOP",A(4)="FIRST",A(4,3)="SECOND",A(6)="LAST"

D MCommand.Do("Entry^Pt",.A)

On the server system, label "Entry" in routine "Pt" might look like this:

Entry(B)     ; Example entry point

K B

S B("TEST")="FIRST AND LAST"

Q:$Q "" Q

At the top of the entry point, the local B contains exactly what was set on MSM-Workstation in the local array A. After the call completes on MSM-Workstation, the local A will only contain the A("TEST") node. This new function simplifies the process of writing client/server programs using MSM-Workstation and MSM-Server.

Note: This only applies when MSM-Workstation is using the MSM-Activate/COM or MSM-Activate/OCX object. The Automation server application is always M, so it can deal with M arrays. If you wish to send an array to any other automation server then you must use the Safe Array structure described in Arrays.


Object Errors

If an action you perform on an object causes an error, then Workstation will report an <OBJCT> error. The error code (or SCODE) returned from the object is specified in the sixth piece of $ZERROR and is normally a large negative number.

If you run the program with the MSM debugger enabled, then when the object error occurs Workstation will display a message box reporting the error message returned by the object. This often contains significantly more information than can be obtained from the object error code and so is a good aid in tracking down errors with object handling.

Many error codes will be specific to the object that you are using, in which case you will need to look them up in the documentation supplied for that object. They are normally listed in hexadecimal. To convert the decimal SCODE from $ZERROR to hexadecimal enter

W $ZHEX(+$P($ZE,":",6))

Some object error codes are general to all objects, such as calling a method that does not exist or trying to set a read-only property. Descriptive text can be obtained for these error codes by calling MSG^%msc and passing it the SCODE:

W $$MSG^%msc(+$P($ZE,":",6))


Workstation as an Automation Server

Automation (formerly OLE Automation) is a feature of the Component Object Model (COM), an industry standard used by applications to expose objects to development tools and other applications. Increasingly, new applications and development tools provide support for this technology, allowing them to control, or be controlled by, other applications or tools.

Workstation can create Automation server objects that can be accessed from other applications (including Workstation itself).

See Also:

Building an Automation Application

General Considerations

Dual-Mode Executables

Enter and Exit

Parameter Passing

Data Type Conversions


Building an Automation Application

To specify an Automation application during the Make EXE process, check the Automation Server check box on the Application tab of the Make EXE Options window.

Building an Automation application basically involves designing and implementing entry points in routines to expose the desired functionality of the application.  These entry points are invoked by the MSM-Activate/COM or MSM-Activate/OCX object using the 'Do' method from client applications.

Refer to the MSM-Activate/COM documentation for details on how to call a Workstation-built Automation server from other applications.


General Considerations

All entry points that will be called via Automation must be extrinsic functions. The Automation interface always expects a return value from the function, which may or may not be passed on to the client depending on whether the client system requests a return value. If a subroutine QUITs without a return value a <DPARM> error will occur.

Nothing precludes the Automation server from itself operating as a client (or Automation Controller) of another COM object. However, an Automation server should avoid direct interaction with the user, such as using dialogs. Such behavior is likely to cause the controlling application to believe that the server is not responding. It also presents problems when the server is executing on a different system, where a user may not be present.


Dual-Mode Executables

A single executable can function in dual modes, as both an automation server and an interactive application. Concurrent instances of such an EXE can be run, so long as they do not all try to mount the same local database for read-write access.  An Automation Server and another interactive application can simultaneously connect with read-write access to a single MSM-Server network database.

For example, an application might run in the foreground to manage a local database (security, expansion, and so on) through GUI windows; and a non-M client may run the same application as an Automation Server to store and retrieve data. There is a restriction; the two cannot run concurrently because the database is local, but the EXE is the same in both cases.

The macro %%IsOLEserver enables the application's action logic to differentiate as necessary.  It returns TRUE when the EXE is running as an Automation Server.


Enter and Exit

When any EXE built with Workstation is started, the mode of use is checked first.  If the EXE is being started as an interactive application but was built as an Automation Server only, an error message is displayed and it terminates.  Likewise, an EXE that was built only as an interactive application cannot be started as an Automation server.

The Enter code run at startup can execute your own authentication code, mount databases, and perform other server initialization tasks.  If a problem occurs at startup (for example, a database cannot be mounted), the %%NotOK macro is used to signal that startup is terminating abnormally.  This shuts down the server. Optionally, a return code may be provided to the Automation Controller by SETting %%RetCode to a positive integer before quitting the Enter code. The controller will receive an SCODE equal to 0x80040300+%%RetCode.

If startup is via MSM-Activate (as a server) and if Workstation fails to start (for example, it cannot mount the database, or the Enter code signals %%NotOK), then a failed-to-start error is returned to MSM-Activate, which then passes it back to the controller application.

The following error codes indicate failures during startup of a Workstation-built Automation server.

Return Code	Description
800403FF	Enter logic of application signaled %%NotOK without setting %%RetCode, or having set %%RetCode to a value outside the range 1 – 200
800403FE	Unable to open device 63 (this should never happen).
800403FD	Unable to read configuration block (this should never happen).
800403FC	The EXE is not built to be an OLE Server (see the check box on the Make EXE options).
800403C8	Enter logic set %%RetCode=200 and signaled %%NotOK
…	%%RetCode set in range 199 – 2
80040301	Enter logic set %%RetCode=1 and signaled %%NotOK
The Exit logic of the application module, which is run at shutdown, can perform cleanup tasks.


Parameter Passing

For details on passing parameters to an MSM-Workstation Automation server, including how to pass large strings, arrays, and object references, see "Parameter Passing" in the MSM-Activate/COM documentation.


External Access - Workstation as an Automation Server - Data Type Conversions
Data Type Conversions

MSM-Workstation's internal data types differ from the standard COM variant data type. When a Workstation-built Automation server is called, the data types are converted as follows:

Variant Data Type	Workstation Data Type	Information
VT_EMPTY	Undefined variable
VT_NULL	""	Zero length string
VT_UI1	Integer
VT_BOOL	Integer
VT_I2	Integer
VT_I4	Integer
VT_DATE	Float
VT_R8	Float
VT_R4	Float
VT_CY	Float
VT_BSTR	String	Become a string, or if it is over 32,764 characters it becomes a local array (large string format).
VT_ARRAY	Local Array	Converted into the Workstation representation of a Safe Array format. Each element of the array is also converted to the required internal type.
VT_DISPATCH	Object Reference
VT_ERROR	Error	Generate an error.
VT_UNKNOWN	Error	Generate an error.
If the parameter is passed by reference to the Workstation-built Automation server then the value returned is converted back to the original variant data type. So if a variable is passed in as a VT_I2 and you change it to "Hello" in the Automation server, then the returned value will be zero, the result of converting a string into a VT_I2.


Issuing Windows Commands

All types of Windows commands can be issued from within a Workstation application through use of extrinsic functions supplied with the system.  One extrinsic function exists for each mode in which a Windows command can be issued.  These functions are contained in the %HOSTCMD utility program, which the developer must include as a component of any application that calls the functions.  The following table illustrates how to invoke each function.

Extrinsic Function Entry Point	Command Type
$$JOB^%HOSTCMD(Command[,Console])	Background Command
$$JOBWAIT^%HOSTCMD(Command[,Console])	Foreground Command
$$WINAPP^%HOSTCMD(Command[,Console])	Background Windows Application
$$WINAPPWT^%HOSTCMD(Command[,Console])	Foreground Windows Application
The first parameter that is passed to the function is the Windows command or application to be executed.

The second parameter, which is optional, specifies whether a console window should be created for the command.  If its value is "CONSOLE", a console window will be created for the command.  If its value is "MINIMIZE", a minimized console window will be created.  If its value is "HIDE", a console window will be created, but it will be hidden from the user.  If its value is "NOCONSOLE", the command will be run without a console.  The default for the JOB and JOBWAIT entry points is "MINIMIZE."  The default for the WINAPP and WINAPPWT entry points is "NOCONSOLE."

Since the Windows commands are executed as a result of a call to an extrinsic function, a value is returned to the caller.  For a Foreground Command, the value that is passed back is the return code which was received from the issued command. Any meaning assigned to the value is specific to the command being executed. Typically, if the return code is zero, the command completed normally (without an error).  Under Windows 95, the Windows command processor (the JOBWAIT entry point) does not make the command return code available.

For a Background Command, the value returned is the process identifier for the Windows command being executed.  Because no indication is provided when a background command terminates, this is the only available information about the new process.


Calling External Programs with XCalls

While writing programs in MSM-Workstation's native programming language, M, it is at times beneficial to link to software outside the MSM environment. References to such "external" software are called external functions, external procedures, or XCalls.

In the program\xcall subdirectory of an MSM-Workstation installation is a toolkit for interfacing non-M programs to MSM. It provides an interface in the form of external calls (XCalls) from M to user-written programs in assembler language or the C programming language. This provides the flexibility to perform functions that are not easily executed with standard M code.

Development of XCall packages requires suitable third-party development tools, such as a C compiler and linker. For more information on the XCall development process, see the documentation provided with the toolkit. However, note that certain aspects of the documentation apply only to use of the toolkit with MSM-Server systems. For example, the XCALLMGR utility is accessible from the menu Tools/System/XCall Manager. A package developed for use with MSM-Workstation results in a .DLL file, which is made available to the M environment by using the LOADXC^%msc service routine, typically during application Enter logic.


DDE Support

MSM-Workstation implements a proposed MWAPI extension to allow M applications to operate as servers or clients in DDE (Dynamic Data Exchange), an integrating technology widely available in the Microsoft Windows environment.

This section describes how to use these features and is provided with the assumption that you are familiar with programming using the MWAPI.  Experience with DDE also is an advantage.  Because the MWAPI extension is not intended to apply only to Microsoft's DDE, some of the terminology may differ.

An MSM-Workstation application can act as a DDE server. It also can operate as a DDE client, using DDE services offered by other applications. A Workstation application may be only a server, only a client, both server and client, or neither. By default, it is neither.

See Also:

Terminology

Workstation as a Data Exchange Server

Workstation as a Data Exchange Client

Notes


Terminology

A Workstation application using DDE exchanges data over a link.  To initiate this link the client specifies a pair of values - service and topic.  This pair is called a source. In any one link, a Workstation application takes only one of the two roles, client or server.  Most exchanges involve one or more items made available by the topic on the service, and it is the client's responsibility to nominate the items.

The client specifies the mode of exchange for an item from the following options:

•	Automatic (sometimes called a hot link), in which changes to the item on the server are passed to the client immediately.

•	Notify (warm link), in which the client is informed that the item has changed, but the new value is not passed.

•	Manual (cold link), in which all transfer is initiated by the client.

The client initiates transfer by specifying an action to be performed asynchronously over a link.  The client is subsequently notified if the action was a success, failed, or resulted in a timeout. The available client actions are:

•	Poke a value into the item on the server.

•	Request the value of the item from the server.

•	Execute a command on the server.


Workstation as a Data Exchange Server

Service - Topic - Item

Server Events


Service - Topic - Item

Service

To act as a server, an MSM-Workstation application must first set its service name into the following node:

^$DISPLAY($PDISPLAY,"LINKSERVICE")

Do not use punctuation in service names. Use unique service names (avoid choices such as "WinWord," "ProgMan," "Shell," and so on).  Because service names are not case-sensitive, MSM and Msm identify the same service.

Topic

Each MWAPI application window created on the display by the application acts as a topic when it has a topic name in the following node:

^$WINDOW(window,"LINKTOPIC")

This node may only be set during creation of the window and may not be modified thereafter. For a window created using %%DoWin, this means the attribute must be set using the Settings parameter of the macro.

Topic names should not include punctuation. Topic names are case-insensitive and should be unique within the service.

The service name and topic name are concatenated to form a source name, as follows:

source=service_$C(124)_topic

The separator, ¦ , is a vertical bar with an ASCII value of 124. Do not confuse it with similar symbols that are available in some character sets.

Item

If a window has a LINKTOPIC attribute and its display has a LINKSERVICE attribute, every TEXT and DOCUMENT gadget on the window is automatically offered as an item of that topic on that service.  The item name is the gadget name.  External applications connecting to the service will be able to retrieve and change the VALUE attribute of those gadgets.  A gadget does not have to be visible or active, nor does its window.


Server Events

When acting as a server, there are five MWAPI events that may occur for the Workstation application as a result of DDE operations.  Three are window-level events, and two are gadget-level events. Their callbacks are specified on the following nodes:

^$WINDOW(window,"EVENT","LINKOPEN")

^$WINDOW(window,"EVENT","LINKEXECUTE")

^$WINDOW(window,"EVENT","LINKCLOSE")

^$WINDOW(window,"G",gadget,"EVENT","LINKPOKE")

^$WINDOW(window,"G",gadget,"EVENT","LINKREQUEST")

All these events set ^$EVENT("CLASS") to LINK.  The standard nodes "TYPE", "WINDOW" and "SEQUENCE" are also supplied.  Each link is assigned an ID when it is opened, which is supplied in the "LINKID" of all events on that link. Each link ID is unique within the Workstation application.  ^$EVENT("LINKSOURCE") is supplied on each event, giving the source name for which the event occurs.  It is equivalent to the following expression, and does not identify the client:

^$DI($PD,"LINKSERVICE")_$C(124)_^$W(^$E("WINDOW"),"LINKTOPIC")

On the gadget-level events, ^$EVENT("LINKITEM") is also supplied. This is the server's item name.

Each open link to a Workstation application acting as a server is recorded in a node of the following form:

^$DISPLAY($PDISPLAY,"LINKID",id)=role

where id is the ID assigned when the link was opened and role is "SERVER".  The application may terminate a link by KILLing the corresponding node.

A client application may exchange data with several items on the same topic using a single link or may use multiple links.

LINKOPEN

The LINKOPEN event occurs when another application has established a link with the topic offered by that window.  During processing of this event, Workstation's M code can KILL ^$EVENT("OK") to cause the link to be terminated when the event callback completes. By the time Workstation processes the event, the DDE link is already open and the client can be exchanging data with topic items.

The DDE protocol is fundamentally anonymous. Unless the developer devises schemes for client validation, a server's typical basis for terminating a particular connection to a topic could be a wish to limit the number of concurrent connections.

LINKEXECUTE

The LINKEXECUTE event occurs when a client application submits a command for execution.  The command is given in ^$EVENT("LINKCOMMAND"), and it is the responsibility of the callback to perform or refuse this command.  If Workstation wishes to inform the client that the command failed, it may KILL ^$EVENT("OK") before completing the callback.

LINKCLOSE

The LINKCLOSE event occurs when a client application terminates a link.

LINKPOKE

The LINKPOKE event occurs for a gadget when a client application is about to poke a value into the item which this gadget represents.  If Workstation wishes to refuse the new data, it may KILL ^$EVENT("OK") before completing the callback.  Otherwise, the new value appear in the gadget's value immediately after the callback completes and before any other callback.

LINKREQUEST

The LINKREQUEST event occurs for a gadget when a client application requests the value of the item which this gadget represents.  If Workstation wishes to refuse the request, it may KILL ^$EVENT("OK") before completing the callback.


Workstation as a Data Exchange Client

To act as a client, an MSM-Workstation application associates one or more TEXT or DOCUMENT gadgets with items of sources offered by data exchange servers.  A list of available sources is given in nodes of the following form:

^$DISPLAY($PDISPLAY,"LINKSOURCE",source)=""

DDE sources take the form service¦topic; the delimiter is ASCII 124.  Because maintenance of this list requires Workstation to query all DDE servers, it is more efficient to fetch this information using a MERGE command rather than a $ORDER:

K sources M sources=^$DI($PD,"LINKSOURCE")

See Also:

Client Attributes

Client Events


Client Attributes

A TEXT or DOCUMENT gadget's participation is specified using the following five gadget attributes:

LINKSOURCE

LINKSOURCE identifies the data source.  It normally is set to one of the values obtained from the list in ^$DISPLAY, taking the form service¦topic.

LINKITEM

LINKITEM identifies the item of the source.  When the client gadget is TEXT type, data supplied by this item will be truncated at the first occurrence of $C(13,10).

LINKMODE

LINKMODE specifies the mode of exchange, taking one of the following values.

Value	Description
NONE	No link is open.
AUTOMATIC	When the item identified by LINKSOURCE and LINKITEM changes, the gadget's VALUE is updated and a LINKUPDATE event occurs.
MANUAL	The gadget is not informed of changes in the value of the item identified by LINKSOURCE and LINKITEM.
NOTIFY	A LINKNOTIFY event occurs for the gadget when the item identified by LINKSOURCE and LINKITEM changes, but the gadget's VALUE is not updated.
LINKACTION

LINKACTION may be set to one of the following values in order to perform the corresponding action.

Value	Description
POKE	The application at the other end of this element's Data Exchange link is asked to assign the text in the gadget's VALUE to the current item.
REQUEST	The application at the other end of this gadget's Data Exchange link is asked to send the text of the current item.  The text received is assigned to the gadget's VALUE.
EXECUTE	The application at the other end of this element's Data Exchange link is asked to execute the command in the gadget's VALUE.
Actions performed in this way are asynchronous, and the outcome cannot be known until a corresponding LINKACTION event occurs for the client gadget.  It is not safe to fetch the new value from the gadget immediately after setting LINKACTION to "REQUEST".

LINKACTION may also be set to null ("") if no action is required. Fetching the value of LINKACTION always returns null.

LINKTIMEOUT

LINKTIMEOUT specifies the time in seconds within which the server is expected to respond to a LINKACTION instruction.  Otherwise a LINKACTION event will occur, reporting the timeout.  The default LINKTIMEOUT is 1. Any value assigned to this attribute must be greater than zero.

Each gadget associated with a data item using the above attributes creates a separate link to the data source. Each open link from a Workstation application acting as a client is recorded in a node of the following form:

^$DISPLAY($PDISPLAY,"LINKID",id)=role

where id is the ID assigned when the link was opened and role is "CLIENT".  Workstation may terminate a link by killing the corresponding node.

When acting as a client, there are four MWAPI events that may occur for Workstation as a result of DDE operations.  All are gadget-level events, and their callbacks are specified on the following nodes:

^$WINDOW(window,"G",gadget,"EVENT","LINKUPDATE")

^$WINDOW(window,"G",gadget,"EVENT","LINKNOTIFY")

^$WINDOW(window,"G",gadget,"EVENT","LINKACTION")

^$WINDOW(window,"G",gadget,"EVENT","LINKCLOSE")


Client Events

LINKUPDATE

The LINKUPDATE event occurs after a gadget with LINKMODE equal to "AUTOMATIC" has been assigned a new VALUE by the server.  This includes an assignment that may occur as a result of a POKE action by this client.

LINKNOTIFY

The LINKNOTIFY event occurs when the source item of a gadget with LINKMODE equal to "NOTIFY" has changed on the server.  This includes an assignment that may occur as a result of a POKE action by this client.

LINKACTION

The LINKACTION event occurs to report the outcome of action specified by setting a non-null value into the gadget's LINKACTION attribute.

^$EVENT("LINKSTATUS") will contain one of the following: "SUCCESS," "FAILED," or "TIMEOUT."

In the case of a status "FAILED," ^$EVENT("LINKREASON") will contain a short description from the DDE system which may help determine the problem. Values are currently as follows:  "UNKNOWN," "SERVER DIED," "NOT PROCESSED," "MEMORY ERROR," "LOW MEMORY," and "BUSY."

LINKCLOSE

The LINKCLOSE event occurs when the server terminates the link to the gadget.

All these events set ^$EVENT("CLASS") to "LINK".  The standard MWAPI nodes "TYPE", "WINDOW", "ELEMENT" and "SEQUENCE" are also supplied.  Each link is assigned an ID when it is opened, which is supplied in the "LINKID" of all events on that link.  Each link ID is unique within the Workstation application.

^$EVENT("LINKSOURCE") and ^$EVENT("LINKITEM") are supplied on each event, giving the source and item name for which the event occurs.


Notes

If a Workstation application is acting as a data exchange server then the service and topics it offers do not appear in its own ^$DI($PD,"LINKSOURCE") list.  Workstation cannot establish a link to itself, but one Workstation application can link to another Workstation application in the same Windows environment.  This provides an effective method for one to signal the other. The first offers a service, topic, and item. The second establishes a link to the item using a LINKMODE of NOTIFY or AUTOMATIC.  When the first is ready to signal, it changes the value of the item. The second receives a LINKNOTIFY or LINKUPDATE event.

It is possible to use an advanced feature of DDE called NetDDE to establish connections across a suitable network.  Consult your Windows documentation for additional information.

If another Windows application is to act as a DDE server, you may need to start it.  To do so, use entry-points in the %HOSTCMD utility. Remember to include this routine as a component of your application.


Using Peripheral Devices

This document describes the physical and logical peripheral devices that are supported by MSM-Workstation. Information is provided on using each device type and controlling device features and functions.

MSM-Workstation supports a wide range of physical and logical devices. Physical devices include terminals, modems, printers, and sequential devices such as tape drives. Logical devices can be used to examine or modify Windows files, access networking and so forth.

Before accessing a device, a Workstation application gains ownership of the device by issuing it an OPEN command. If the device is available, it is added immediately to the list of devices owned by the job. If a device is not available, execution of the application is suspended until the device becomes available.

When a device is OPENed, the user can specify the amount of time to wait if the device is not immediately available. If the device still is unavailable after the specified time interval, the OPEN command is terminated. The OPEN mechanism allows an application to gain ownership of more than one device at a time.

Because each application can access only one device at a time, an M command is used to specify the device to be used for input and output operations. The application directs input and output to a specific device with the USE command.

The USE command makes the specified device the current device. The current device is used for all subsequent input or output operations until it is explicitly changed by another USE command, or until the device is closed.

After ownership and use of a device are established, an application can read from or write to the device using extended ASCII character strings. When an application no longer requires a device, it should issue a CLOSE command to the device. This command returns the device to the system and enables it to be reassigned to another user.

After a device is returned to the system with a CLOSE command, it must be acquired with an OPEN command before it can be USEd again. When a terminal type device is OPENed, device characteristics established through previous OPEN or USE commands are automatically reset to the default values.

See Also:

Device Designators

Accessing Peripheral Devices

Input and Output Commands

Special Variables

Mnemonic Namespaces

Console Window Devices

Windows Printer Devices

Communications Devices

Null Device

Magnetic Tape Devices

Host File Server Devices

TCP/IP Socket Device

Socket Control Mnemonics

Record Boundaries

$ZA, $ZB, and $ZC Feedback Information

VIEW Device


Device Designators

Every device available to MSM-Workstation is assigned a unique device designator. This designator is used as an argument on the OPEN, USE, and CLOSE commands to identify a specific device. The following table lists the device designators.

Device Designators

Device Number	Description
1	Primary console window (ZMTERM) - default $I and $P on startup when Make-EXE Option requests a console window.
2	Reserved for future use
3-10	Windows printers
11-18	COM1 through COM8
19-30	Reserved for future use
31-37	Secondary console windows (ZMTERM)
38-45	Reserved for future use
46	Null device - default $I and $P on startup unless Make-EXE Option requests a console window.
47-50	Tape 1 through tape 4
51-54	HFS devices
55	Reserved for future use
56	TCP/IP sockets
57-62	Reserved for future use
63	VIEW device
64+	Reserved for future use


Accessing Peripheral Devices

When an MSM-Workstation application starts, it already owns a principal device, whose device designator is given in the $PRINCIPAL special variable.

The $IO special variable always contains the device designator of the current device. All input or output operations (for example: READ, WRITE, ZPRINT) are directed to the current device. The initial value assigned to the $IO special variable at application startup is the device designator of the principal device (it is equal to $PRINCIPAL). By definition, any reference to a device designator of zero is interpreted to mean the principal device.

An application can own more than one device. Device ownership is obtained by issuing an OPEN command with one or more device designators as the command's operand.

The operand of the USE command is the designator of the device that functions as the current device. The designator for the device (which must have been previously opened), becomes the new value for the $IO special variable. This device remains the current device until it is changed by another USE command. The $IO special variable can be referenced in any expression to determine the current device, but can be changed only with the USE command.

After an application finishes using a device, it should issue a CLOSE command, specifying the device designator as the operand. This command returns the device to the system, allowing it to be reassigned to other applications if it is a shared resource (for example: a tape unit). When a Workstation application exits all open devices are automatically CLOSEd.


Input and Output Commands

In MSM-Workstation, all peripheral devices except the VIEW device look like sequential devices. The same input and output commands can be used regardless of the device type accessed. MSM supports the following input and output commands.

Input and Output Commands

Command	Purpose
READ	Requests input from a device. The information returned by the device is stored in a local or global variable. Optionally, the command can include a prompt string and formatting characters.
WRITE	Sends information to a device. Format characters, ASCII values, literals, and local or global variables can be included.
ZLOAD	If no operands are specified, transfers a routine from the current device to the partition.
ZPRINT	Writes the routine loaded in the partition to the current device.
ZWRITE	Writes the contents of all or part of the local symbol table to the current device.


Special Variables

For each device, the system maintains the following special variables that provide feedback information.

Special Variables

Variable	Purpose
$X	Represents the cursor position relative to the left margin. The system only counts printable characters (ASCII characters between the decimal values of 32 and 126, inclusive, and all 8-bit ASCII values). If terminal-specific control sequences are used to move the cursor, $X no longer represents the true cursor position unless it is explicitly updated by using the SET or USE command. If the value of $X exceeds 255 characters, the system resets it to zero.
$Y	Contains the number of line feed characters that were written to the device since the last form feed. If the value of $Y exceeds 255 characters, the system resets it to zero.
$ZA	Contains information such as error indicators or status information specific to the device that is currently accessed.
$ZB	Contains information such as block numbers or buffer offsets specific to the device that is currently accessed.
$ZC	Contains information that is common to all devices and indicates whether an end-of-file condition or error condition occurred.


Mnemonic Namespaces

The mnemonic namespaces feature allows users to develop MSM applications that are device-independent. Mnemonic namespaces are used to access the device types supported by MSM, including terminal devices, host file server, and magnetic tape.

Mnemonic namespace support is available for any device supported by MSM that allows the WRITE command to be used. Mnemonic controls are specified in the same manner that is used to specify format arguments on the WRITE command.  The following format is used to specify mnemonic controls:

/MnemonicName(Operand1,Operand2, ... ,Operandn)

In the sample format, the slash ( / ) is required, and the operands are optional. In a READ or WRITE command, a Mnemonic control can be used wherever a format character can be used. In fact, Mnemonic controls are considered to be format characters.

MSM-Workstation supports multiple system-supplied mnemonic namespaces. For example, ANSI X3.64-1979 is available for terminals, TCP is provided for sockets. Through the USE command, the application identifies the namespace to be associated with the device.

Refer to Appendix C, "Mnemonic Namespaces," in the MSM Language Reference Manual for a list of the Namespaces supplied with the system. MSM-Workstation does not currently support user-defined mnemonic namespaces.

MSM provides the $DEVICE and $KEY special variables, which enhance the capabilities of mnemonic namespaces. Refer to the MSM Language Reference Manual for additional information on the USE, READ, and WRITE commands, format characters, and the $DEVICE and $KEY special variables.


Console Window Devices

MSM-Workstation provides eight predefined MWAPI MTERM or ZMTERM console window devices that are used for character-type operations on the console. Each console window emulates an ANSI 3.64 terminal device.

Console window devices enable applications that were developed for ANSI terminals to be run from the console. Console windows can be positioned and sized like other windows and can be minimized when they are not in use.

Device numbers for console windows are 1 and 31 through 37. The following commands are valid for console window devices:

OPEN	CLOSE	USE
WRITE	ZPRINT	ZWRITE
READ	ZLOAD	ZUSE
The Workstation development environment uses the first available device in the range 31-38 for the Tools/Command Window option and for running legacy character-mode utilities.

The following service routine entry points are relevant to console window devices:

CHGKEY^%msc

PDEV^%msc

VT100^%msc

VT420^%msc

OPEN, USE, and CLOSE Parameters

When a console window device is opened, or when output is directed to the device with the USE command, the command can be used to specify information that modifies options for the window. Window options remain in effect either until they are changed by a subsequent OPEN or USE command or the device is CLOSEd. The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} Dev{:(Opt1:Opt2:...:Opt12)} {:Time}

USE{:Cond} Dev{:(Opt1:Opt2::...:Opt12)}

CLOSE{:Cond} Dev

In these commands, the Cond operand is a post-conditional statement that controls command execution. If the post-conditional is true, the command is executed. If it is false, the command is not executed. The Time operand on the OPEN command indicates the amount of time (in seconds) to wait for the specified device to become available.

After the OPEN command completes and if the Time operand was specified, the $TEST special variable contains a 1 if the OPEN was successful; otherwise, it contains a 0. If the timeout option is not specified, $TEST is unchanged.

Note that every Workstation application has its own private set of these devices, so an OPEN command should always succeed.

The options on the OPEN and USE commands are applied in left-to-right order with one exception; option 6 is applied before option 5. In other words, the device characteristics specified by option 6 are reset first, then the characteristics specified by option 5 are set.

Right Margin - (Opt1)

The right margin setting specifies when a carriage return/line feed sequence is inserted automatically by MSM during output operations. When the value of the $X special variable is equal to the right margin, the system inserts a carriage return/line feed before it outputs the next character to the device. Insertion of the carriage return/line feed is suppressed if the character that is output is a carriage return. If the right margin is set to 0, automatic insertion of a carriage return/line feed sequence is suppressed.

Reserved for Future Use - (Opt2)

This option is reserved for future use. If a value is present, it is ignored by the system. To ensure compatibility with future MSM releases, this option should not be used.

Fixed Length Read - (Opt3)

This option sets the maximum number of characters to be accepted on the next read operation. After the specified number of characters are entered, the READ command is automatically terminated, even if a carriage return was not received. After completion of each READ command, the system resets this value to 255. The syntax USE PORT:(::3) READ X is equivalent to USE PORT READ X#3.

Reserved for Future Use - (Opt4)

This option is reserved for future use. If there is a value, it is ignored. To ensure compatibility with future MSM releases, this option should not be used.

Device Characteristics to be Set - (Opt5)

This option is used to set functions for the console window device. In binary, the value of this option represents a bit string in which each bit specifies a characteristic. If the bit is on, the characteristic is set. If the bit is off, the characteristic remains unchanged.

The following table provides a list of the bit numbers, describes their functions, and provides the decimal values that correspond to the bit value. The characteristics associated with Opt6 are applied before the Opt5 values.

Controlling Terminal Functions

Bit #	Characteristic	Description of Characteristic
31	RESERVED	Reserved for future use.
30	MODAL	If this bit is set in the parameters of an OPEN that creates a ZMTERM window, the window is made application-modal. Otherwise, an OPEN that creates a ZMTERM window creates it non-modal. (Decimal value = 1073741824)
29	RESERVED	Reserved for future use.
28	RESERVED	Reserved for future use.
27	RESERVED	Reserved for future use.
26	PROMPTED READ	If this bit is set, a prompted READ operation does not flush (discard) the characters in the input buffer. If this bit is not set, the system flushes the characters in the input buffer each time a prompted read is issued. (Decimal value = 67108864)
25	TYPEAHEAD	If this bit is set, the system, at the start of each READ, flushes the input buffer of all characters that were received. If this bit is not set, the system uses any characters that are in the input buffer as a result of typeahead.  (Decimal value = 33554432)
24	RESERVED	Reserved for future use.
23	PASS ALL	If this bit is set, the system does not interpret any characters received other than user-specified READ terminators (see Opt9) or ESC if ESCAPE processing is enabled. If this bit is not set, the system-defined control characters are interpreted. (Decimal value = 8388608)
22	RESERVED	Reserved for future use.
21	RESERVED	Reserved for future use.
20	RESERVED	Reserved for future use.
19	EMPTY LINE DELETE	If this bit is set when the system BACKSPACE character (Backspace or Delete, or both) is received and the input buffer is empty, the READ operation is terminated and the low-order byte of $ZB is set to 127. If this bit is not set, the system ignores the BACKSPACE character that is received when the input buffer is empty. (Decimal value = 524288)
18	DATA LENGTH	If this bit is set (the default), the system allows input of full 8-bit characters. If this bit is not set, the high-order bit of each character is set to 0 as it is read. By not setting this bit, input is restricted to the 7-bit ASCII character set.  (Decimal value = 262144)
17	$X and $Y UPDATE	If this bit is set, the system does not update the values of the $X and $Y variables on a WRITE *N operation. If this bit is not set, the values of $X and $Y are updated when a WRITE *N sequence is used. (Decimal value = 131072)
16	RESERVED	Reserved for future use.
15	INTERRUPT	If this bit is set, it indicates that an interrupt was received from the device. If this bit is not set, it indicates that a break was not received from the device. The bit is reset either by using Opt6 or when BREAK 0 is executed.  (Decimal value = 32768)
14	LOWERCASE	If this bit is set, all lowercase characters sent by the device are converted to uppercase. If this bit is not set, lowercase characters are passed through as they are received. (Decimal value = 16384)
13	RESERVED	Reserved for future use.
12	RESERVED	Reserved for future use.
11	RESERVED	Reserved for future use.
10	RESERVED	Reserved for future use.
9	FLASH ON READ	If this bit is set, a READ command that applies to the window causes the window to flash if it is not the currently active window in the Windows environment.
8	RESERVED	Reserved for future use.
7	CURSOR POSITIONING	If this bit is set, it indicates that the cursor is to be positioned at the specified location when the value of $X or $Y is altered or if Opt7 is specified on an OPEN or USE command. If the bit is not set, the cursor is not moved.  (Decimal value = 128)
6	ESCAPE	If this bit is set, the ESCAPE processing feature is enabled. If this bit is not set, ESCAPE processing is disabled, and the escape character is interpreted as a carriage return. Refer to "Escape Processing" in this document for additional information. (Decimal value = 64)
5	RESERVED	Reserved for future use.
4	RESERVED	Reserved for future use.
3	RESERVED	Reserved for future use.
2	CRT	If this bit is set, it indicates that the device in use is a CRT, and characters are to be erased from the screen on backspace. If this bit is not set, it indicates that the device is a hard-copy device and \ is echoed on backspace. Defaults to set for all console devices. (Decimal value = 4)
1	RESERVED	Reserved for future use.
0	ECHO	If this bit is set, it indicates that characters received from the device are not to be echoed back to the device. If this bit is not set, printable characters received from the device are written back to the device. (Decimal value = 1)
To enable functions, the appropriate bit or bits as indicated by this option field must be turned on with the OPEN or USE command. The binary representation for the specified decimal value must contain the bits to be turned on. A decimal value or an expression that evaluates to a decimal value can be specified.

Device Characteristics to be Cleared - (Opt6)

This option allows the bits associated with various console window functions to be turned off. The definition for the bits is the same as described for the Device Characteristics to be Set - (Opt5).

To disable functions, the appropriate bit or bits (as indicated by this option field) are turned off with the OPEN or USE command. The binary representation for the specified decimal value must contain the bits to be turned off. A decimal value or an expression that evaluates to a decimal value can be specified.

Value of $X and $Y Special Variables - (Opt7)

This option is used to set the value of the $X and $Y special variables. The new values are specified as a single number that is equal to the new value of $Y multiplied by 256 and then added to the new value of $X. For example, a value of 3112 is specified to set $X to column 40 and $Y to row 12.

Alternatively, the user can directly set the values of $X and $Y. A normal SET command is used to assign new values to the $X and $Y special variables. Refer to "Special Variables" in the MSM Language Reference Manual for additional information.

Reserved for Future Use - (Opt8)

This option is reserved for future use. If a value is present, it is ignored by the system. To ensure compatibility with future MSM releases, this option should not be used.

READ Terminators - (Opt9)

This option specifies which ASCII control characters (values 0 through 31and 127) are to be recognized as READ terminators. When a READ command is issued to a device and one of the specified characters is encountered, the READ terminates. The value of the termination character is stored in the low byte of $ZB. When the device is opened, RET and ESC are set as the default terminators ($C(13,27)).

A maximum of 32 different READ terminator characters can be specified for each console window device. When the null string is specified for this option, no READ terminator characters are in effect for the device. The program then must use either fixed-length READs (for example, READ X#80) or single-character READs (for example, READ *X) to process device input.

If CTRL/S ($C(19)) is specified as a terminator, it is interpreted as DEL ($C(127)) instead. Therefore, the 32 possible READ terminator characters consist of ASCII values 0 through 18, 20 through 31, and 127.

Window Title - (Opt10)

This option is used to specify the title of the console window. If no title is specified, the system uses the application name followed by the window device number. The application name is specified by the developer who created the application.

Window Buffer Size - (Opt11)

This option specifies the number of rows and columns maintained by MSM in a buffer to enable the display of data that is larger than the physical window size. When the window size is smaller than this value, a horizontal or vertical scroll bar is displayed. The buffer size is specified as the number of rows multiplied by 256, and then added to the number of columns. This option's default value is the initial window size. If a value is specified that is smaller than the window size, the window size is used. This option is valid only on an OPEN command, and is ignored if it is specified on a USE command.

Window Size - (Opt12)

This option is used to specify the size of the console window. The window size is specified as the number of rows multiplied by 256, and then added to the number of columns. For example, a value of 3112 is specified for a window that consists of 12 rows and 40 columns.

Window Placement - (Opt13)

This option is used to specify the location of the console window. The window's location is defined as the row and column in which the window's upper-left corner is to display. This location is specified as the number of rows multiplied by 256, and then added to the number of columns. For example, a value of 777 is specified to place a window's upper-left corner on the display in column 9 of row 3 (3 multiplied by 256 and added to 9).

Escape Processing

In MSM, escape processing enables programmers to use a minimum of coding in a program to handle input escape sequences generated by a console window. Console devices emulate ANSI 3.64 terminal devices and transmit an escape sequence when a program function key or arrow key is pressed.

An escape sequence consists of an escape character ($C(27)), followed by one or more characters.

When escape processing is enabled, the system reads one additional character after the escape character is received and terminates the READ. If the character received is another escape (ESC), a question mark (?), a left bracket ( [ ), or the letter O, it is ignored and one more character is read and similarly examined. This character is stored in the high-order byte of the $ZB special variable, $ZB\256. If the READ is not terminated with an escape sequence, the high-order byte of the $ZB special variable is 0. In either case, the low-order byte of $ZB contains the ASCII value of the character that terminated the READ ($ZB#256 is RETURN or ESCAPE).

If the escape sequence is received while a single-character READ command is active, the value of the variable specified on the READ is 0.

MSM supports standard ANSI 3.64 function keys. The following table lists function key codes.

Function Key Codes for Console Window Devices – VT420 mode

Function Key	Escape Sequence	$ZB\256
F1 F2  F3  F4  F5  F6  F7  F8  F9  F10  F11 F12 UP ARROW DOWN ARROW RIGHT ARROW LEFT ARROW HOME INSERT DEL END PAGE UP  PAGE DOWN	Esc[11~   Esc[12~ Esc[13~ Esc[14~ Esc[15~ Esc[17~  Esc[18~  Esc[19~  Esc[20~  Esc[21~  Esc[23~  Esc[24~  Esc[A  Esc[B  Esc[C  Esc[D  Esc[1~  Esc[2~  Esc[3~  Esc[4~  Esc[5~ Esc[6~	31  32  33  34  35  37  38  39  40  41  43  44  17  18  19  20  21  22  23  24  25 26
These escape sequences match those produced by a VT420 terminal. VT100 alternatives can be enabled using the VT100^%msc service routine entry point. The following table lists those function key codes.

Function Key Codes for Console Window Devices – VT100 mode

Function Key	Escape Sequence	$ZB\256
F1 F2  F3  F4  F5  F6  F7  F8  F9  F10  F11 F12 UP ARROW DOWN ARROW RIGHT ARROW LEFT ARROW HOME INSERT DEL END PAGE UP  PAGE DOWN	EscOP  EscOQ EscOR EscOS  EscOT  Esc[17~  Esc[18~  Esc[19~  Esc[20~  Esc[21~  Esc[23~  Esc[24~  Esc[A  Esc[B  Esc[C  Esc[D  Esc[1~  Esc[2~  Esc[3~  Esc[4~  Esc[5~ Esc[6~	32  33  34  35  36  37  38  39  40  41  43  44  17  18  19  20  21  22  23  24  25 26
 $ZA, $ZB, and $ZC Feedback Information

After each console window input or output command, status information about the console window and the last operation performed is stored in the $ZA, $ZB, and $ZC special variables. After the routine that issued the input or output command interrogates these variables, it selects a programming path based on the variables' contents.

For window devices, the $ZA, $ZB, and $ZC special variables have the following meanings.

Variable	Description
$ZA	The 32-bit value of the device characteristics for the console window device. The individual bit values are defined in Console Window Devices, OPEN and USE Parameters, and Device Characteristics to be Set (Opt 5).
$ZB	Contains information that describes how the input command was terminated. If ESCAPE processing is disabled, the value of $ZB is as follows:
	Value of $ZB	Description
	$ZB=13	If the READ command was terminated with a carriage return.
	$ZB=27	If the READ command was terminated by an escape character.
	$ZB=nn	If the READ command was terminated because a user-specified termination character was received (when $C(nn) is the termination character).
	$ZB=0	If the READ command was terminated because the number of characters specified by the field length option was received.
$ZC	Contains 0 (zero) if the operation completed normally, -1 if end-of-file was reached, or 1 if a device error occurred.
If ESCAPE processing is enabled, $ZB contains a two-byte value with the low-order byte containing the information described above.

The values of $ZA, $ZB, and $ZC are always returned for the current device. A USE command must be issued to specify the current device.

Configuring the Console Window Font

A console window can use both raster and TrueType fonts.  The raster font used is always the Terminal font, and the sizes displayed for selection are determined by enumerating the available sizes for the font.  The Workstation's locale-dependent resources include the name of a TrueType font to use and the sizes of that font to offer for selection.

The end-user of the window can select a font size using the window's system menu, or its toolbar if this is visible. The programmer can read and set this by accessing the underlying MWAPI window's ZMTFONT attribute.

All open console windows have a corresponding MWAPI structure in the ssvn ^$WINDOW, where the initial subscript corresponds to the device number. Many of the parameters that can be set with  the OPEN and USE commands can also be accessed in the ssvn. However, the ssvn governs some parameters not accessible in any other way.

One example is the ZMTFONT attribute. For example, assuming console window device 1 is open:

^$WINDOW(1,"ZMTFONT")

returns a value of the form:

width,height,technology

where width and height give the pixel size of the currently selected font, and technology is either R (raster) or T (TrueType fonts).

When setting ZMTFONT, fields can be omitted. The following forms are allowed:

width [,height [,technology]]

width ,[height],technology

,height[,technology]

For example:

8

8,12

8,12,R

8,,R

,12

,12,R

The actual font selected is the closest match from among the fonts listed in the font drop-down box on the window's optional toolbar. The actual font's width and height normally does not exceed the requested width and/or height. If width is supplied, the closest width is chosen, and height and technology (in that order) are used if needed to eliminate duplicates.  If width is not supplied, the closest height is chosen, and technology is used if needed to eliminate duplicates. If not enough fields are provided to narrow the choice to one font, the first match found is selected. If no suitable match is found, the system's OEM_FIXED_FONT is picked, in which case the font may be larger than requested.

If ZMTFONT is used to save and restore a font setting, generally the same font is used on restore as was used on save. However, if the set of available fonts has changed between save and restore, for example through changes to Windows Display properties, the same font might not be used.

The name of the TrueType font and/or its selectable sizes can be configured via the registry or a user profile, using the keys TTFace and TTSize under the section name %MTerm.  MSM-Workstation first looks for application-specific data according to the settings in the application's configuration block. That is, it looks either in the application's .INI file or in the registry under:

HKEY_CURRENT_USER\Software\<VAR>\<Application>

For font data that is not found in this location, the system looks in the registry under:

HKEY_LOCAL_MACHINE\Software\Micronetics\MSM-Workstation

For font data that also is not specified at the second location, MSM-Workstation looks in its locale-dependent resources.

The value of the TTFace key should be the name of a TrueType font that supports the current OEM code-page.  The value of TTFSize should be a comma-separated list of font sizes.  Font sizes greater than 99 are ignored.

As an example, the default English settings (expressed in profile file form) are as follows:

[%MTerm]

TTFace=Lucida Console

TTSize=5,6,7,8,10,12,14,16,20,24,28,36,72

Console Window Device Examples

The following examples illustrate how to use the OPEN, USE, and CLOSE commands to access console window devices. The # (pound) sign indicates that the value provided is in hexadecimal format.

OPEN, USE, and CLOSE Examples for Console Window Devices

OPEN/USE Command	Description
U 1:(0::::64)	Turns on ESCAPE processing for the primary console window device and disables automatic line wrap.
U $I:(::::::::$C(13,27,127))	Sets READ terminators to carriage return, escape, and delete.
O 31:(::::#840001)	OPENs device 31, turns on pass-all and 8-bit modes, and turns off echo.
U $I:(::::33554432)	Disables typeahead for the current device.
U 0:(::::P:$ZA)	Turns off all Device Characteristics bits, and then turns on the bits specified by the value of variable P.
U $P:(::::16385)	Turns off echo and turns on lowercase processing on the principal device.
U 0:80	Sets line width to 80 characters. Parentheses are optional if only Opt1 is specified.


Windows Printer Devices

Windows printer devices allow users to access printers defined by the Windows Print Manager. Documents created by MSM-Workstation are scheduled for printing based on the Print Manager's standard procedures.

Device numbers for Windows printers are 3 through 10. The system includes a built-in mnemonic namespace for printer devices. This namespace provides special functions for setting and querying printer characteristics. The namespace cannot be changed by the user, and user-defined namespaces are not supported for Windows printer devices.

The following commands are valid for printer devices:

OPEN	CLOSE	USE
WRITE	ZPRINT	ZWRITE
OPEN and USE Parameters

When a Windows printer device is opened or when output is directed to the device with the USE command, the command can be used to alter options for the Windows printer. Options set for the Windows printer remain in effect until they are changed by a subsequent OPEN or USE command or until the device is CLOSEd. The format of the OPEN and USE commands is as follows:

OPEN{:Cond} Dev{:{(Opt1:Opt2:...:Opt6)}{:Time}}

USE{:Cond} Dev{:(Opt1:Opt2:...:Opt6)}

In these commands, the Cond operand is a post-conditional statement that is used to control execution of the command. If the post-conditional is true, the command is executed. If it is false, the command is not executed. The Time operand on the OPEN command indicates the amount of time (in seconds) to wait for the specified device to become available.

After the OPEN command completes and if the time was specified, the $TEST special variable contains 1 if the OPEN was successful; otherwise, it contains 0. If the timeout option is not specified, $TEST is unchanged.

Note that every Workstation application has its own private set of these devices, so an OPEN command should always succeed.

The options on the OPEN and USE commands are applied in left-to-right order with one exception; option 6 is applied before option 5. In other words, the device characteristics specified by option 6 are reset first, then the characteristics specified by option 5 are set.

Right Margin - (Opt1)

Windows printer margins generally are set as a distance from the edge of a page. This option allows the user to specify the right margin in terms of the number of characters that are written, beginning at the left margin. The mnemonics section describes the preferred method for setting margins.

This option specifies the number of characters that make up a line. A new right margin is calculated using the average character width of the current font.

Printer Name - (Opt2)

This option specifies the name of the Windows printer that is to print the document created on this MSM device. If the name is not known to the Windows Print Manager, the command fails. The printer name cannot be changed after a document is started. If no name is specified, the default Windows printer is used.

Document Name - (Opt3)

This option specifies the name that is assigned to the output document.  This name can be used to identify the document in the Windows Print Manager. If no name is specified, the name "MSM Document" is used.

Form Name - (Opt4)

This option specifies the name of the form to be used with the printer. If no form is specified, the default form for the printer is used.

Device Characteristics to be Set - (Opt5)

Use this option to enable one or more device characteristics for the printer. If the bit is on, then the characteristic is set. If the bit is off, then the characteristic is left unchanged.

The following table lists the bit numbers and describes the functions associated with each bit.

Bit	Description
31-24	Reserved for future use.
23	If this bit is set, all data is written directly to the printer, bypassing most aspects of the Windows printer driver.  The data may contain printer control sequences.  The system will not add any formatting control, and the printer mnemonics which control formatting are invalid. If this bit is not set, pages are formatted by MSM and the Windows printer driver using the specified margins, font, and so on. (Decimal value = 8388608)
22-18	Reserved for future use.
17	This bit applies only if bit 23 is set. If this bit is set, MSM does not update the values of the $X and $Y variables on a WRITE *N operation. If this bit is not set, the values of $X and $Y are updated when a WRITE *N sequence is used.  (Decimal value = 131072)
16-14	Reserved for future use.
13	This bit applies only if bit 23 is set. If this bit is set, MSM  sends only a carriage return for the exclamation point (!) format character in WRITE commands. If this bit is not set, a carriage return/line feed sequence is sent.  This bit also applies to the control sequence sent for margin processing. (Decimal value = 8192)
12	This bit applies only if bit 23 is set. If this bit is set, the tab character ($C(9)) is passed directly through to the printer. If this bit is not set, the tab character is translated to the number of spaces needed to move to the next tab position, which is the next multiple of eight.. (Decimal value = 4096)
11-0	Reserved for future use.
Device Characteristics to be Cleared - (Opt6)

Use this option to disable one or more device characteristics for the printer. The definition for the bits is the same as described for the Device Characteristics to be Set (Opt5).

CLOSE Parameters

When a Windows printer device is closed, the CLOSE command can be used to specify processing options. The format of the CLOSE command is as follows:

CLOSE{:Cond} Dev{:(Opt1)}

The Cond operand is a post-conditional statement that is used to control execution of the command. If the post-conditional is true, the command is executed. If it is false, the command is not executed.

Document Disposition - (Opt1)

This option is used to specify the disposition of the document that is being closed. If a disposition of  "D" is specified, the document is discarded rather than printed. If the disposition is null or is omitted, the document is released to the Windows Print Manager for printing.

Creating a Print Document

To create a print document, information must be supplied in a particular order. If this order is not observed, the system may create multiple documents when only one was intended, or a document's appearance may not be as expected.

The first step in creating a document is to OPEN a Windows printer device and specify the name of the printer that is the output's destination. A document name and form name also can be specified as part of an OPEN command. As an alternative, the /SETDOCUMENT and /SETFORM mnemonics can be used to specify the document and form name after the device is OPENed and before any output is sent to the device.

After the Windows printer is OPENed and the initial document setup is complete, the page format, including page orientation, font information, and document margins, can be specified.

The document text is written using normal WRITE commands. Each page is created from top to bottom and left to right, observing the margins. Overflow into the right or bottom margins can cause a new line or page to be started.

When the document is complete, a CLOSE command ends the document and releases it to the Print Manager for printing. Refer to the appropriate Windows documentation for information on the Print Manager.

Windows Printer Mnemonics

The document to be printed is created using standard MSM WRITE commands. Control mnemonics can be used to specify formatting and setup information for the document. Some mnemonics only specify information that is stored for future reference. Because these mnemonics do not immediately affect the device status, errors are not detected. When a mnemonic is issued that changes the device status, or when the status is implicitly changed by writing normal output after new characteristics are set, the $DEVICE special variable is set to reflect the operation's success or failure. Mnemonics that explicitly change the device status are identified in the following descriptions.

The following mnemonics are supported for printer devices.

/CHOOSEPRINTER(Printer,Form,Orientation)

This mnemonic causes the Windows printer selection dialog box to display, prompting the user to select a printer. This mnemonic's parameters are optional and can be used to initialize fields in the dialog box. These parameters are as follows.

Parameter	Description
Printer	The name of a Windows printer. If the parameter is null or an invalid printer name is specified, the Windows default printer is used.
Form	The name of a Windows printer form (for example, LETTER or A4). If the parameter is null, Windows supplies a default form. If the parameter is not a valid form name, the form field in the dialog box is not initialized.
Orientation	The page orientation. A value of 1 specifies portrait orientation, and a value of 2 specifies landscape orientation. If the parameter is omitted or is 0, Windows supplies a default orientation.
After the /CHOOSEPRINTER mnemonic completes, the $DEVICE special variable can be interrogated to determine the dialog's success or failure. If an error was detected or if the user selected CANCEL, then $DEVICE evaluates as TRUE. Otherwise, $DEVICE evaluates as FALSE to indicate that no errors occurred and that printer selection was successful.

/CHOOSEFONT(Name,Size,Bold,Italic,Underline,Strikeout)

This mnemonic causes the Windows font selection dialog box to display, prompting the user to select a font. The mnemonic's parameters are optional and can be used to initialize fields in the dialog box. These parameters are as follows.

Parameter	Description
Name	Sets a font's typeface name (for example, Courier New). If the name is null or is an invalid font name, no default font value is displayed in the dialog box.
Size	Sets a font's size, in points. If the size is zero or an invalid value, no default value for size is displayed in the dialog box.
Bold and Italic	Specifies whether bold and italic attributes are to display as default values in the font selection dialog box. A value of 1 specifies that the indicated style is to be set as the default value in the dialog box. A value of 0 specifies that the indicated style is not to be set as the default value in the dialog box. If neither bold nor italic is set, the default style is Regular.
Underline and Strikeout	Specifies whether the underline and strikeout attributes are to be applied to a selected font. A value of 1 specifies that the indicated style is to be applied to the font. A value of 0 turns off the indicated style for the font. Because these styles do not appear in the dialog box, they cannot be changed by the end-user.
After the /CHOOSEFONT mnemonic completes, the $DEVICE special variable can be interrogated to determine the dialog's success or failure. If an error was detected or the user selected CANCEL, $DEVICE evaluates as TRUE. Otherwise, $DEVICE evaluates as FALSE to indicate that no errors occurred and that font selection was successful.

/CHOOSECOLOR(Red,Green,Blue)

This mnemonic displays the Windows color dialog box. The parameters specify the default color.  If no parameters are specified, the default color is black.  If any parameter is specified, then all three must be provided. The parameter values should be in the range 0-255.

The dialog may be used to set a custom color on the printer, but information about a custom color set defined during use of the mnemonic is not available on return. Nor is the custom color set preserved between uses of the mnemonic.

After the /CHOOSECOLOR mnemonic completes, the $DEVICE special variable can be interrogated to determine the dialog's success or failure. If an error was detected or the user chose the CANCEL button, $DEVICE evaluates as TRUE. Otherwise, $DEVICE evaluates as FALSE to indicate that no errors occurred and that font selection was successful.

/SETPRINTER(Printer)

This mnemonic associates a Windows Printer with the MSM printer device. It can be used to specify a printer directly rather than allowing the user to select one from the /CHOOSEPRINTER dialog. If no printer is set before output is written to the MSM device, the Windows default printer is used.

/SETFORM(Form)

This mnemonic sets a Form name to be used with the document created by the current MSM printer device. It can be used to specify a form directly rather than allowing the user to select a form from the /CHOOSEPRINTER dialog, or to override the user's choice. If no form is set before output is written to the MSM device, the default form for the selected printer is used.

/SETDOCUMENT(Name)

This mnemonic specifies a Name to be assigned to the document. If no name is specified before output is written to the MSM device, the name "MSM Document" is used.

/SETORIENTATION(Orientation)

This mnemonic sets the Orientation to be used with the document created by the current MSM printer device. It is used to specify an orientation directly rather than allowing the user to select an orientation from the /CHOOSEPRINTER dialog, or to override the user's choice. If no orientation is set before output is written to the MSM device, the default orientation for the selected printer is used. If this mnemonic is used after output is sent to the MSM device, the current page is terminated and a new page with the appropriate orientation is started.

Parameter	Description
Orientation	Specifies the orientation of the page. A value of 1 specifies portrait orientation, and a value of 2 specifies landscape orientation.
/SETCOLOR(Color)

The first variant of this mnemonic specifies whether color printers are to produce color or monochrome output. It can be used to specify the Color option directly rather than allowing the user to select color printing from the /CHOOSEPRINTER dialog, or to override the user's choice. If no Color option is set before output is written to the MSM device, the default Color option for the selected printer is used.

Parameter	Description
Color	Specifies a printer's color attributes. A value of 0 specifies that the output is to be monochrome, and a value of 1 specifies color output.
/SETCOLOR(Red,Green,Blue)

The second variant of this mnemonic specifies the color for subsequent WRITE operations. It can be used to specify the output color directly rather than allowing the user to select a color from the /CHOOSECOLOR dialog, or to override the user's choice.  All three parameters must be specified.  The values should be in the range 0-255.

/STARTDOCUMENT

This mnemonic applies the current printer name, document name, form name, orientation, and color option to initiate creation of a logical document. A /STARTDOCUMENT mnemonic is issued implicitly by the MSM system if output is sent to the MSM printer device without explicitly issuing the /STARTDOCUMENT mnemonic. If /STARTDOCUMENT is issued when a document is active, the current document is closed and a new document is started.

After the /STARTDOCUMENT mnemonic completes, the $DEVICE special variable can be interrogated to determine the operation's success or failure. If any of the document's values (for example: device, document name, or form name) are invalid, $DEVICE evaluates as TRUE, indicating that an error occurred. Otherwise, $DEVICE evaluates as FALSE to indicate that no errors occurred and the document was successfully created.

/SETFONTNAME(Font,Charset)

This mnemonic sets the current font to the typeface name specified in Font. After a typeface is set, it is used for all subsequent output.

Optionally, a Charset may be specified using a value from the following table:

0	ANSI
161	Greek
162	Turkish
186	Baltic
204	Russian
238	East European
/SETFONTSIZE(Points)

This mnemonic sets the current font size (in points) to a specified value. If the font is not scalable, Windows substitutes the closest available size.

/SETFONTBOLD (Option)
/SETFONTITALIC(Option)
/SETFONTUNDERLINE(Option)
/SETFONTSTRIKEOUT(Option)

These mnemonics specify whether a font style is to be used. If the value of Option is 1, the selected style is applied for subsequent output. If the value is 0, the style is turned off for subsequent output.

/SETFONT

This mnemonic uses the current font settings to load a font in the printer device. If an error is detected, $DEVICE is set to a TRUE value. If the font name is not a valid Windows font, Windows may substitute a default font without indicating an error. This mnemonic is performed implicitly by MSM when output is written to the device after any font parameter is changed.

/SETUNITS(Units)

This mnemonic sets the type of values that are used to measure text and page size and position on a page.

If Units=1, character units are used for horizontal values, and line units are used for vertical values. For variable pitch fonts, the average character width is used for margin calculations. This is the default value before /SETUNITS is issued to the MSM printer device.

If Units=2, device units (pixels) are used.

If Units=3, hundredths of an inch are used.

If Units=4, millimeters are used.

/SETLEFTMARGIN(Margin,Units)
/SETRIGHTMARGIN(Margin,Units,Wrap)
/SETTOPMARGIN(Margin,Units)
/SETBOTTOMMARGIN(Margin,Units,Wrap)

These mnemonics set the margin values for each document page.

Parameter	Description
Margin	Specifies the distance from the appropriate edge of the paper to the point at which the printed output starts (for TOPMARGIN and LEFTMARGIN) or stops (for RIGHTMARGIN and BOTTOMMARGIN).
Units	Specifies the units in which the margin is specified. Defined values for units are provided in the description for the /SETUNITS mnemonic in this section. If units is 0 or is omitted, the current value from /SETUNITS is used.
Wrap	Specifies whether MSM is to automatically wrap output that overflows into the margin. If Wrap has a value of 1, then any output that would otherwise overflow into the margin causes MSM to generate a new line or page. If Wrap is 0 (zero), then any output that would overflow into the margin is lost until the user explicitly begins a new line or new page. If Wrap is omitted, the current wrap setting is unchanged.
When the MSM print device is initially opened, the default margins are 0.5 inches on all four sides with wrap enabled.

/SETLINESPACING(Space,Units)

This mnemonic sets the vertical spacing for lines of text.

Space is the vertical distance that the print head advances for each new line.

If Units is 1, then Space is a multiple of the normal line spacing for the current font.  For example, Space=1 is single spacing, Space=2 is double spacing, Space=1.5 is midway between single and double spacing.

If Units is 2, 3, or 4, then Space is the actual value in pixels, hundredths of an inch, or millimeters, respectively.

If Units is 0 (zero) or is omitted, the current value from /SETUNITS is used.

/SETPOSITION(X,Y)

This mnemonic sets the starting position for the next output operation.  Both parameters are required.  The position is interpreted as relative to the current left and top margins.  Negative values are not allowed, and the right and bottom margin values are enforced.  The units of the parameters is the current value from /SETUNITS.

X is the horizontal position. Y is the vertical position.

^$DEVICE Nodes

The structured system variable ^$DEVICE is used to examine the current status of MSM printer devices. It also is used instead of mnemonics to modify certain device settings. Some nodes only report status and cannot be set to new values. Attempts to set these nodes result in a <PROT > error.

The following nodes are defined for MSM printer devices. In the following sections, device is the referenced MSM Windows printer device. For all nodes that report size or position, the units used are the current units in effect for the device.

^$DEVICE(Device,ZPRT,FORMHEIGHT,PRINTAREA)

The height of one page of the current document. The reported size is the maximum printable area for the specified printer.

^$DEVICE(Device,ZPRT,FORMHEIGHT,PAGEAREA)

The height of one page of the current document. The reported size is the physical size of the entire page from edge to edge.

^$DEVICE(Device,ZPRT,FORMWIDTH,PRINTAREA)

The width of one page of the current document. The reported size is the printable area for the specified printer.

^$DEVICE(Device,ZPRT,FORMWIDTH,PAGEAREA)

The width of one page of the current document. The reported size is the physical size of the entire page from edge to edge.

^$DEVICE(Device,ZPRT,POSITION)

The current output position on the page, in the format X;Y, where X is the horizontal position and Y is the vertical position.  This node also can be used to set the output position.

^$DEVICE(Device,ZPRT,POSITION,X)

The current horizontal output position on the page. This node also can be used to set the output position.

^$DEVICE(Device,ZPRT,POSITION,Y)

The current vertical output position on the page. This node also can be used to set the output position.

^$DEVICE(Device,ZPRT,PRINTER)

The name of the Windows printer associated with this device.

^$DEVICE(Device,ZPRT,FORM)

The name of the Windows form that is used for the current document.

^$DEVICE(Device,ZPRT,ORIENTATION)

The orientation of the current document. The value is either PORTRAIT or LANDSCAPE.

^$DEVICE(Device,ZPRT,FONT,NAME)

The typeface name of the current font.

^$DEVICE(Device,ZPRT,FONT,SIZE)

The size (in points) of the current font.

^$DEVICE(Device,ZPRT,FONT,PITCH)

The pitch type of the current font. Its value is either FIXED or VARIABLE.

^$DEVICE(Device,ZPRT,FONT,BOLD)

The value of the bold attribute for the current font. A value of 1 indicates that the current font has the bold style. A value of 0 indicates that the font does not have the bold style.

^$DEVICE(Device,ZPRT,FONT,ITALIC)

The value of the italic attribute for the current font. A value of 1 indicates that the current font has the italic style. A value of  0 indicates that the font does not have the italic style.

^$DEVICE(Device,ZPRT,FONT,UNDERLINE)

The value of the underline attribute for the current font. A value of 1 indicates that the current font has the underline style. A value of 0 indicates that the font does not have the underline style.

^$DEVICE(Device,ZPRT,FONT,STRIKEOUT)

The value of the strikeout attribute for the current font. A value of 1 indicates that the current font has the strikeout style. A value of 0 indicates that the font does not have the strikeout style.

^$DEVICE(Device,ZPRT,FONT,LINESPACING)

The value of the linespacing attribute for the current font

^$DEVICE(Device,ZPRT,COLOR)

The current color setting. The three color values are separated by a semicolon delimiter in this order: red;green;blue. This node may be SET to change the color setting.

^$DEVICE(Device,ZPRT,UNITS)

Specifies the units to be used for size and position values.

A value of CHAR specifies characters for horizontal units and lines for vertical units.

A value of PIXEL specifies device units (pixels).

A value of HUNDREDTH specifies hundredths of an inch.

A value of MM specifies millimeters.

^$DEVICE(Device,ZPRT,MARGIN,TOP)

Specifies the size of the top margin for the current page.

^$DEVICE(Device,ZPRT,MARGIN,LEFT)

Specifies the size of the left margin for the current page.

^$DEVICE(Device,ZPRT,MARGIN,BOTTOM)

Specifies the size of the bottom margin for the current page.

^$DEVICE(Device,ZPRT,MARGIN,BOTTOM,WRAP)

Specifies the wrap attribute for the bottom margin. A value of 1 indicates that MSM implicitly is to start a new page to prevent output overflow in the bottom margin. A value of 0 indicates that any output that would overflow into the bottom margin is truncated until the user explicitly begins a new page.

^$DEVICE(Device,ZPRT,MARGIN,RIGHT)

Specifies the size of the right margin for the current page.

^$DEVICE(Device,ZPRT,MARGIN,RIGHT,WRAP)

Specifies the wrap attribute for the right margin. A value of 1 indicates that MSM implicitly is to start a new line to prevent output overflow in the right margin. A value of 0 indicates that any output that would overflow into the right margin is truncated until the user explicitly begins a new line.

$ZA, $ZB, and $ZC Feedback Information

After each Windows printer output command, status information about the printer and the last operation performed is stored in the $ZA, $ZB, and $ZC special variables. The routine that issued the output command interrogate the variables and selects an appropriate programming path based on their contents. For terminal devices, these variable have the following meanings.

Variable	Description
$ZA	The 32-bit value of the printer's device characteristics. The individual bit values are defined in Windows Printer, OPEN and USE Parameters, Device Characteristics to be Set (Opt 5).
$ZB	Contains the current page number.
$ZC	Contains 0 (zero) if the operation completed normally, or 1 if a device error occurred.
The values of $ZA, $ZB, and $ZC are always returned for the current device. A USE command must be issued to specify the current device.

Windows Printer Device Examples

The following examples illustrate how to use the OPEN, USE, and CLOSE commands to access printer devices.

OPEN, USE, and CLOSE Examples for Windows Printer Devices

OPEN/USE Command	Description
O 3:(0:"NETWORK")	Opens the NETWORK printer with no right margin.
O 3:(:::"A4")	Opens the Windows default printer with an A4 form.
C 3:"D"	Closes the device and discards output.


Communications Devices

Communications devices have device numbers in the range of 11 through 18, corresponding to Windows serial ports COM1 to COM8. Workstation only supports these devices under Windows 95 and Windows NT.

Although the following commands are valid for communications devices, some cannot be used with all device types. For example, the attached device may be output-only, rendering READ or ZLOAD commands inapplicable.

OPEN	CLOSE	USE
WRITE	ZPRINT	ZWRITE
READ	ZLOAD	ZUSE
OPEN, USE, and CLOSE Parameters

When a communications device is opened or when output is directed to a device with the USE command, device options can be modified with the USE command. Device options remain in effect until they are changed by a subsequent OPEN or USE command, or until the device is CLOSEd.

The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} Dev{:(Opt1:Opt2:...:Opt9)} {:Time}

USE{:Cond} Dev{:(Opt1:Opt2:...:Opt9)}

CLOSE{:Cond} Dev

In these commands, the Cond operand is a post-conditional statement that is used to control command execution.  If the post-conditional is true, the command is executed. If it is false, the command is not executed. The Time operand on the OPEN command indicates the amount of time (in seconds) to wait for the specified device to become available.

After the OPEN command completes and if the time was specified, the $TEST special variable contains 1 if the OPEN was successful; otherwise, it contains 0. If the timeout option is not specified, $TEST is unchanged.

The options on the OPEN and USE commands are applied in left-to-right order with one exception; Opt6 is applied before Opt5. In other words, the device characteristics specified by Opt6 are reset first, then the characteristics specified by Opt5 are set.

Right Margin - (Opt1)

The right margin setting controls when a carriage return/line feed sequence is inserted automatically by MSM during output operations. When the value of the $X special variable is equal to the right margin, the system inserts a carriage return/line feed before it outputs the next character to the device. Insertion of the carriage return/line feed is suppressed if the character being output is a carriage return. If the right margin is set to 0, automatic insertion of a carriage return/line feed sequence is suppressed.

Reserved for Future Use - (Opt2)

This option is reserved for future use. If a value is present, it is ignored by the system. To ensure compatibility with future MSM releases, this option should not be used.

Fixed-Length Read - (Opt3)

This option is used to set the maximum number of characters to be accepted on the next read operation. The READ command is terminated automatically when the specified number of characters are entered, even if a carriage return was not received. After each READ command completes, the system resets this value to 255. The syntax USE PORT:(::3) READ X is equivalent to USE PORT READ X#3.

Reserved for Future Use - (Opt4)

This option is reserved for future use. If a value is present, it is ignored by the system. To ensure compatibility with future MSM releases, this option should not be used.

Device Characteristics to be Set - (Opt5)

This option is used to set communications device functions. The value of this option (when treated in binary) represents a bit string, in which each bit specifies a characteristic. If the bit is on, the characteristic is set. If the bit is off, the characteristic remains unchanged.

The following table lists the bit numbers, describes their functions, and provides the corresponding decimal values for each bit value. The characteristics associated with Opt6 are applied before the Opt5 values.

Communications Device Functions

Bit #	Characteristic	Description of Characteristic
31	RESERVED	Reserved for future use.
30	RESERVED	Reserved for future use.
29	RESERVED	Reserved for future use.
28	RESERVED	Reserved for future use.
27	PASS ALL FLOW CONTROL	If this bit is set, XON/XOFF is honored when PASS ALL is enabled. If this bit is not set, then XON/XOFF flow control is disabled when PASS ALL is enabled. (Decimal value = 134217728)
26	PROMPTED READ	If this bit is set, a prompted READ operation does not flush (discard) the characters in the input buffer. If this bit is not set, the system flushes the characters in the input buffer each time a prompted read is issued. (Decimal value = 67108864)
25	TYPEAHEAD	If this bit is set, the system flushes the input buffer of all received characters at the start of each READ. If this bit is not set, the system uses any characters that are in the input buffer as a result of typeahead. (Decimal value = 33554432)
24	ZUSE	If this bit is set, all WRITE commands directed to this device by a ZUSE command are ignored. The ZUSE command is used to check the value of $ZA or any other special variable. If this bit is not set, the system allows ZUSE commands to write data to the device. (Decimal value = 16777216)
23	PASS ALL	If this bit is set, the system does not interpret any characters received other than user-specified READ terminators (see Opt9), or ESC if ESCAPE processing is enabled. If this bit is not set, the system-defined control characters are interpreted. (Decimal value = 8388608)
22	RESERVED	Reserved for future use.
21	CTRL/O	If this bit is set, CTRL/O is treated as a normal data character. If this bit is not set, CTRL/O signals the system to discard output data until the system receives another CTRL/O.  (Decimal value = 2097152)
20	CONTROL CHARACTERS	If this bit is set, control characters that are not supported by MSM are ignored (not passed to the program and not echoed). If this bit is not set, control characters are treated as normal input characters. (Decimal value = 1048576)
19	EMPTY LINE DELETE	If this bit is set when the system BACKSPACE character (Backspace or Delete, or both) is received and the input buffer is empty, the READ operation is terminated and the low-order byte of $ZB is set to 127. If this bit is not set, the system ignores the BACKSPACE character that is received when the input buffer is empty. (Decimal value = 524288)
18	DATA LENGTH	If this bit is set, the system allows input of full 8-bit characters. If this bit is not set, the high-order bit of each character is set to 0 as it is read. By not setting this bit, input is restricted to the 7-bit ASCII character set. (Decimal value = 262144)
17	$X and $Y UPDATE	If this bit is set, the system does not update the values of the $X and $Y variables on a WRITE *N operation. If this bit is not set, the values of $X and $Y are updated when a WRITE *N sequence is used. (Decimal value = 131072)
16	TYPE OF CRT	If this bit is set, it indicates that the device supports ANSI-type escape sequences to position the cursor. If this bit is not set, it indicates that the device accepts VT52-type escape sequences to position the cursor.  On output, this bit has meaning only if bit 7 is also set. On input, if this bit is set, it indicates that the system is to recognize VT220 extended function keys for escape processing. Otherwise, only the standard VT100 function keys are recognized. (Decimal value = 65536)
15	INTERRUPT	If this bit is set, it indicates that an interrupt has been received from the device. If this bit is not set, it indicates that a break has not been received from the device. The bit is reset using Opt6 or when BREAK 0 is executed. (Decimal value = 32768)
14	LOWERCASE	If this bit is set, all lowercase characters sent by the device are converted to uppercase. If this bit is not set, lowercase characters are passed through as they are received.  (Decimal value = 16384)
13	LINEFEED	If this bit is set, the system sends a carriage return for the exclamation point (!) format character in WRITE commands. If this bit is not set, a carriage return/line feed sequence is sent. This bit also applies to the control sequence sent for margin processing.  (Decimal value = 8192)
12	TAB CONTROL	If this bit is set, the tab character ($C(9)) is passed directly to the port. If this bit is not set,  the tab character is translated to the number of spaces necessary to move the cursor to the next tab position. Tabs are multiples of eight positions on output. (Decimal value = 4096)
11	LINE CARRIER	If this bit is set, it indicates that the line carrier signal is present. If the bit is not set, either the line is not modem-controlled; or if the line is modem-controlled, the line carrier is not present. This bit can be referenced only via $ZA and cannot be set by the user. (Decimal value = 2048)
10	PRINTER	If this bit is set, it indicates that the device is a printer. If this bit is not set, the device is not a printer. The printer bit is reserved for system use and cannot be set by the user.  (Decimal value = 1024)
9	CONNECT	If this bit is set, the DTR signal is asserted for the device. If this bit is turned off, the DTR signal is turned off. (Decimal value = 512)
8	LOGON	If this bit is set, the device is not permitted to logon to the system. If the bit is not set, the device is allowed to logon.  (Decimal value = 256)
7	CURSOR POSITIONING	If this bit is set, it indicates that a cursor positioning escape sequence is to be sent when the value of $X or $Y is altered or if Opt7 is specified on an OPEN or USE command. If the bit is not set, cursor positioning sequences are not sent. The cursor positioning sequence that is sent is determined by the value of bit 16, Type of CRT. (Decimal value = 128)
6	ESCAPE	If this bit is set, the ESCAPE processing feature is enabled. If this bit is not set, ESCAPE processing is disabled, and the escape character is interpreted as a carriage return. Refer to "Escape Processing" in this document for additional information. (Decimal value = 64)
5	RESERVED	Reserved for future use.
4	CTRL/O	If this bit is set, it indicates that a CTRL/O has been received from the device. All output to the device is discarded until another CTRL/O is received from the device. If this bit is not set, the device is in a normal state and can receive output. This bit is reserved for system use and cannot be set by the user. (Decimal value = 16)
3	MODEM CONTROL	If this bit is set, it indicates that the line is modem-controlled. If this bit is not set, it indicates that the line is not modem-controlled. (Decimal value = 8)
2	CRT	If this bit is set, it indicates that the device in use is a CRT, and characters are to be erased from the screen on backspace. If this bit is not set, it indicates that the device is a hard-copy device, and \ is echoed on backspace.  (Decimal value = 4)
1	OUTPUT ONLY	If this bit is set, it indicates that the device is an output-only device. If the bit is not set, it indicates that the device supports READ operations. (Decimal value = 2)
0	ECHO	If this bit is set, it indicates that characters received from the device are not to be echoed back to the device. If this bit is not set, printable characters received from the device are written back to the device. (Decimal value = 1)
To enable functions, the appropriate bit or bits as indicated by this option field must be turned on with the OPEN or USE command. To turn on the bits, specify the decimal value whose binary representation contains the bits to be turned on. A decimal value or an expression that evaluates to a decimal value can be specified.

Device Characteristics to be Cleared - (Opt6)

This option allows the bits associated with certain device functions to be turned off. The definition for the bits is the same as described for the Device Characteristics to be Set - (Opt5).

To disable functions, the appropriate bit or bits as indicated by this option field must be turned off with the OPEN or USE command. To turn off the bits, specify the decimal value whose binary representation contains the bits to be turned off. A decimal value or an expression that evaluates to a decimal value can be specified.

Value of $X and $Y Special Variables - (Opt7)

This option is used to set the value of the $X and $Y special variables. The new values are specified as a single number that is equal to the new value of $Y, multiplied by 256, and then added to the new value of $X. For example, a value of 3112 is specified if $X is to be set to column 40 and $Y is to be set to row 12.

As an alternative, the user can set the values of $X and $Y by using a normal set command. For additional information, refer to "Special Variables" in the MSM Language Reference Manual.

Initialization Parameters - (Opt8)

This option is used to specify the baud rate, parity, data bits, stop bits, and flow control characteristics for the device. The following table lists each function's value.

Initialization Parameters for Communications Devices

Option Value	Parity Check	Flow Control	Data Bits/ Stop Bits	Baud Rate
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15	- - NONE - - ODD - - - EVEN - - - - - -	XON/XOFF - - CTS/RTS - - - - - - - - - - - -	- - - - - 7 Bit 1 Stop 7 Bit 2 Stop - - 8 Bit 1 Stop 8 Bit 2 Stop - - - - -	- 14400 28800 56000 57600 115200 128000 300 256000 1200 1800 2400 4800 9600 19200 38400
The value is a 16-bit number in which the first 4 bits specify the parity, the second 4 bits specify flow control, the third 4 bits specify the number of data bits and stop bits, and the fourth 4 bits specify the baud rate. The initialization value must be specified using the full 16 bits. For example, if the baud rate is changed, the parity, data bits, and stop bit values must be specified again.

To determine the option's value, multiply the parity check value by 4096; add this total to the value for the data bits; add the new total to the value of the stop bits multiplied by 16; and add this total to the baud rate value. Stated differently:

(Parity*4096)+(Flow*256)+((Data & Stop)*16)+Baud

If this option is omitted or 0 (zero) is used for the value of parity, data bits, or baud rate, the device values for parity, data bits, stop bits, and baud rate are not changed.

READ Terminators - (Opt9)

This option specifies which ASCII control characters (values 0 through 31and 127) are to be recognized as READ terminators. When a READ command is issued to a device and one of the specified characters is encountered, the READ terminates. The value of the termination character is stored in the low byte of $ZB. When the device is opened, RET and ESC characters are set as the default terminators ($C(13,27)).

A maximum of 32 different READ terminator characters can be specified for each communications device. When the null string is specified for this option, no READ terminator characters are in effect for the device. The program then is required to use either fixed-length READs (for example, READ X#80) or single-character READs (for example, READ *X) to process device input.

If the CTRL/S character ($C(19)) is specified as a terminator, it is interpreted as the DEL character ($C(127)) instead. Therefore the 32 possible READ terminator characters consist of ASCII values 0 through 18, 20 through 31, and 127.

Escape Processing

Escape processing in MSM enables programmers to use a minimum of coding in a program to handle input escape sequences that are generated by a device. Most devices transmit an escape sequence when a program function key or arrow key is pressed. An escape sequence generally consists of an escape character ($C(27)), followed by one or more characters.

When escape processing is enabled, the system reads one additional character after the escape character is received, and then terminates the READ. If the character received is another escape (ESC), a question mark (?), a left bracket ( [ ), or a letter O, it is ignored and one more character is read and similarly examined. This character is stored in the high-order byte of the $ZB special variable ($ZB\256). If the READ is not terminated with an escape sequence, the high-order byte of the $ZB special variable is 0 (zero). In either case, the low-order byte of $ZB contains the ASCII value of the character that terminated the READ ($ZB#256 is RETURN or ESCAPE).

If the escape sequence is received while a single-character READ command is active, the value of the variable specified on the READ is 0 (zero).

MSM supports both standard VT100 function keys and VT220 extended function keys. The function key codes are listed in the following table.

Function Key Codes for Communications Devices

Function Key	Escape Sequence	$ZB\256
PF1 PF2 PF3 PF4 F1-F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 HELP DO F17 F18 F19 F20 UP ARROW DOWN ARROW RIGHT ARROW LEFT ARROW FIND INSERT HERE REMOVE SELECT PREVIOUS SCREEN NEXT SCREEN	EscOP EscOQ EscOR EscOS Local Use Only Esc[17~ Esc[18~ Esc[19~ Esc[20~ Esc[21~ Esc[23~ Esc[24~ Esc[25~ Esc[26~ Esc[28~ Esc[29~ Esc[31~ Esc[32~ Esc[33~ Esc[34~ Esc[A Esc[B Esc[C Esc[D Esc[1~ Esc[2~ Esc[3~ Esc[4~ Esc[5~ Esc[6~	32 33 34 35 - 37 38 39 40 41 43 44 45 46 48 49 51 52 53 54 17 18 19 20 21 22 23 24 25 26
$ZA, $ZB, and $ZC Feedback Information

After each device input or output command, status information about the device and the last operation that was performed is stored in the $ZA, $ZB, and $ZC special variables. The routine that issued the input or output command interrogates the variables and selects an appropriate programming path based on their contents.

For communications devices, these variables have the following  meanings.

Variable	Description
$ZA	Indicates the 32-bit value of the device's characteristics. The individual bit values are defined in Communications Devices, OPEN and USE Parameters, Device Characteristics to be Set (Opt 5).
$ZB	Contains information that describes how the input command was terminated. If ESCAPE processing is disabled, the value of $ZB is as follows:
	Value of $ZB	Description
	$ZB=13	The READ command was terminated with a carriage return.
	$ZB=27	The READ command was terminated by an escape character.
	$ZB=nn	The READ command was terminated because a user-specified termination character was received (when $C(nn) is the termination character).
	$ZB=0	The READ command was terminated because the number of characters specified by the field length option was received.
	If ESCAPE processing is enabled, $ZB contains a two-byte value with the low-order byte containing the information described above. The high-order byte contains the escape sequence value shown in the Function Key Codes table.
$ZC	Contains 0 (zero) if the operation completed normally, -1 if end-of-file was reached, or 1 if a device error occurred.
The values of $ZA, $ZB, and $ZC are always returned for the current device. A USE command must be issued to specify the current device.

Communications Device Examples

The following examples illustrate how to use the OPEN, USE, and CLOSE commands to access devices. The # (pound) sign indicates that the value provided is in hexadecimal format.

OPEN, USE, and CLOSE Examples for Communications Devices

OPEN/USE Command	Description
U 0:(0::::64)	Turns on ESCAPE processing for the current device and disables automatic line wrap.
U $I:(::::::::$C(13,27,0))	Sets READ terminators to carriage return, escape, and null.
O 11:(::::#840001):5	OPENs device COM1, turns on pass-all and 8-bit modes, turns off echo, and waits for a maximum of five seconds for the device to become available.
U 0:(:::::::9*4096+(5*16)+13)	Sets the current device to even parity, 7 data bits, 1 stop bit, 9600 baud.
U $I:(::::33554432)	Disables typeahead for the current device.
U $I:(:::::512)	Turns off the DTR signal for the current device (forces the modem to hang-up).
U 0:(::::P:$ZA)	Turns off all Device Characteristics bits, and then turns on the bits specified by the value of variable P.
U $P(::::16385)	Turns off echo and turns on lowercase processing on the current device.
U 11:132	Sets line width to 132 characters. Parentheses are optional if only Opt1 is specified.


Null Device

The Null device provides a mechanism for discarding output from a job that expects to write to a device. The device designator for the null device is 46. When it is the current device, all output to the device is discarded. Any read request is terminated immediately with an empty string as the result. If a timeout value is specified for an input operation, $T is set to 0 to indicate a timeout.

All commands are valid for the Null device:

OPEN	WRITE	READ
CLOSE	ZPRINT	ZLOAD
USE	ZWRITE
Although all parameters on the OPEN, USE, or CLOSE commands are evaluated, their values are ignored.

$ZA and $ZB always have the value 0. $ZC is always -1 to indicate end-of-file.


Magnetic Tape Devices

The magnetic tape device allows the user to access a magnetic tape in sequential mode or random-access mode. Commands support industry-standard, nine-track tape drives, DAT tapes, and cartridge tapes. These devices can be used to create files that are transferred to other systems, read files created by another system, function as a temporary storage device, or backup the MSM database.

The system transfers information to and from these devices in physical blocks and automatically deblocks the information into logical records, if appropriate. The system automatically blocks and unblocks data for the user. It also provides access to the tape in buffer mode, which bypasses the blocking and unblocking operations.

The tape devices are assigned device designators of 47 through 50. Valid commands for the magnetic tape devices are as follows:

OPEN	WRITE	READ
CLOSE	ZPRINT	ZLOAD
USE	ZWRITE
The Windows operating system assigns names (TAPE0, TAPE1, etc.) to installed tape drives. The first four tape drives can be accessed with MSM. Device number 47 accesses TAPE0, device 48 accesses TAPE1, device 49 accesses TAPE2, and device 50 accesses TAPE3.

A magnetic tape device is accessed by OPENing the device and then specifying parameters such as access mode, logical record size, or physical block size. All READ and WRITE accesses to the device are in sequential order unless the device is repositioned with a WRITE *Code command (when Code is a positioning command). The next input or output operation begins at the byte that immediately follows the last byte of the previous input or output operation.

When the magnetic tape device is accessed, input and output operations cannot be intermixed. The first READ or WRITE operation sets the mode. After the mode is set, it can be changed only by repositioning the tape or closing and then re-opening the tape. When the magnetic tape device is CLOSEd, any unwritten data is written to the tape, and a tape mark (end-of-file indicator) is written.

OPEN, USE, and CLOSE Parameters

When the magnetic tape device is opened and when input or output is directed to the device with the USE command, additional information can be specified to the system. This information is used to set the device access mode, logical record size, and physical block size.

The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}{:Time}

USE{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}

CLOSE{:Cond} Dev

In  these commands, the Cond operand is a post-conditional statement that is used to control execution of the command. If the post-conditional is true, the command is executed. If it is false, the command is not executed.

The time operand on the OPEN command indicates the amount of time to wait for the specified device to become available. After  the OPEN command completes, the $TEST special variable contains a 1 if the open was successful, otherwise, it contains a 0. $TEST remains unchanged if a timeout value is not specified. The remaining options are defined below.

Access Mode - (Opt1)

The access mode indicates to the system which method should be used to process the tape. Access modes are single-character identifiers that specify characteristics of the physical data format, character set used to record the data, type of tape labels, recording density, and allowable I/O operations. The following table lists valid access modes and provides a description of each mode.

Magnetic Tape Access Modes

Code	Mode	Description of Mode
A	ASCII Character Set	This character set is used for all input and output operations.
B	Buffer Mode	All tape transfers are performed using the VIEW buffer. When this mode is specified, all other access modes except T, 3, 4, and 5 are ignored, and only WRITE * type commands are allowed.
E	EBCDIC Character Set	This character set is used for all input and output operations. On output, ASCII characters are translated to EBCDIC, and on input, EBCDIC characters are translated to ASCII.
F	Fixed Length Records	All input operations assume a fixed length for the data, and all output operations are performed in stream mode. When this mode is selected, the Opt2 parameter (logical record length) must be specified, and the Opt3 parameter (physical block size) may be specified.
L	Standard Labels	The system processes standard labels for the tape. In ASCII mode, it processes ANSI labels; in EBCDIC mode, it processes IBM labels.
N	Null Data	This mode indicates to the system that the null character (X'00') can appear as part of the data in stream mode. If this mode is not specified, a null character indicates the end of a block, and processing continues with the next block.
R	READ Only	This mode indicates to the system that only input commands are allowed for the tape. The system generates a <MODER> error if an output command is attempted. If this option is omitted, the system assumes that both READ and WRITE operations are allowed.
S	Stream Format	During output in stream mode, the system automatically blocks information into the buffer up to the buffer's specified size (Opt3 parameter). If necessary, the system splits the logical record across a block boundary. For input, data is unblocked into logical records using either a fixed length or the delimiter string.
T	Inhibit Tape Mark Errors	Normally, MSM generates an error condition (<MTERR>) when a tape mark is encountered. The error condition can be suppressed by including this code in the OPEN command. $ZA then can be interrogated to determine if an error occurred.
U	Unlabeled	This mode indicates that the system is not to perform label processing.
V	Variable Length Records	If this format is specified, the ANSI variable format is used when the character set is ASCII, and the IBM variable length format is used for the EBCDIC character set. Each operand on a WRITE command is treated as a separate logical record.
3	800 BPI	This mode specifies that the tape drive is to be accessed at 800 bits per inch.
2	1600 BPI	This mode indicates that the tape drive is to be accessed at 1600 bits per inch.
1	6250 BPI	This mode indicates that the tape drive is to be accessed at 6250 bits per inch.
The value of this option can be any combination of characters enclosed in quotation marks (for example, "ASU"), and either uppercase or lowercase characters can be used. This option is ignored on the USE command because the access mode can be set only when the device is first opened. The density options are ignored for cartridge tape devices.  A <NOPEN> error occurs if you specify buffer mode without first opening the VIEW device.

To change the access mode, the device must be CLOSEd and then opened with the new values. If this option is omitted, a value of "ASU" is assumed by MSM.

Logical Record Length - (Opt2)

The logical record length parameter allows the user to specify the fixed size of each record that is read from or written to the tape device. If the access mode is not F (fixed-length records), this option must not be specified or must be zero. Fixed-length records can have a length of 1 to 32767 characters.

Physical Block Size - (Opt3)

The physical block size parameter allows the user to specify the actual size of each physical block that is read from or written to the tape device. The physical block size can be from 14 to 32767 characters in length. For cartridge tape devices, this value must be a multiple of 512K. When fixed-length records are used, the block size must be a multiple of the record length.

Delimiter String - (Opt4)

The delimiter string is used to separate logical records on the magnetic tape device in stream mode. The user can specify a string consisting of one to three ASCII characters (for example, $C(13,10)) as the delimiter. If this option is specified, it is the only string recognized as the delimiter.

If this option is not specified, all carriage returns ($C(13)) are ignored, and line feeds ($C(10)), vertical tabs ($C(11)), and form feeds ($C(12)) terminate a READ operation. $C(13,10) is the default delimiter string for output.

If this option is specified as a null string (""), there is no delimiter, and fixed-length READs must be used (for example, READ X#100) to process the data.

Caution should be used when selecting a delimiter character other than the default character. If the specified delimiter character normally appears as part of the data, unexpected results can occur when data is read from the magnetic tape device.

Buffer Offset- (Opt5)

This option indicates the location in the buffer where the next READ or WRITE operation is to occur. This option is valid only when the tape device is opened in buffer mode. The value of this option can range from zero to the size of the VIEW buffer.

WRITE Commands

A special series of WRITE commands are used to control tape processing, including tape motion, reading and writing labels, and determining tape status. These commands are issued using the WRITE *Code notation of MSM in which Code is the action to be performed.

Some commands can be used only in buffer mode when the tape device shares the buffer with the VIEW device (device 63). In this mode, only block type READ and WRITE operations are allowed.

The following table defines the *Code commands that are used for magnetic tape from MSM. Except for commands that specifically are identified as buffer mode-only commands, all of the commands can be used regardless of the tape mode that was specified when the device was OPENed.

Magnetic Tape WRITE Commands

Code	Action	Description of Action
1	Backspace	The tape is backspaced on a physical block, and the READ/WRITE switch is reset.
2	Forward Space	The tape is forward-spaced one physical block and the READ/WRITE switch is reset. If the tape is at the beginning of tape and label processing is enabled, the tape label is skipped before the forward space.
3	Write Tape Mark	A tape mark is written. If the last operation was a write, the output buffer is written first.
4	Write Block	A block is written from the VIEW buffer. If the tape is at the beginning of tape and label processing is enabled, the label is written before the block is written. This operation is valid only if the device was opened in buffer mode.
5	Rewind Tape	The tape is rewound to beginning of tape. If the last operation was a write, the output buffer and EOF label (if enabled) are written before rewinding.
6	Read Block	A block is read into the VIEW buffer. If the tape is at the beginning of tape and label processing is enabled, the label is skipped. This operation is valid only if the device was opened in buffer mode.
7	Read Label	If the tape is positioned at a label, the label is read; otherwise the next block is read.
8	Write Header Label	If the tape was opened with label processing enabled, the header label is written. For EBCDIC labels, if the tape is positioned at beginning of tape, a volume label is written first. If label processing is not enabled, this operation is ignored.
9	Write EOF Label	If label processing is enabled, the end-of-file label is written. If label processing is not enabled, this operation is ignored.
10	Tape Status	The $ZA special variable is updated with the actual tape status. Use this command before examining the status flags after a successful operation.  This command is not necessary after an error has occurred.
11	Backward Space	The tape is backward-spaced to the previous tape mark, and the READ/WRITE switch is reset.
12	Forward Space	The tape is forward-spaced to the next tape mark, and the READ/WRITE switch is reset.
13	Erase Tape	The tape is erased, and the READ/WRITE switch is reset. This operation is not supported by all tape devices.
14	Retension Tape	The tape is retensioned, and the READ/WRITE switch is reset. This operation is valid only for cartridge tape devices and is ignored for other types of tape devices.
15	Forward Space	The tape is forward-spaced to the end of the last data written on the tape (tape marks are skipped), and the READ/WRITE switch is reset. This operation is valid for cartridge tape devices only.
16	Rewind and Unload Tape	The tape is rewound and then unloaded from the device. If the last operation was a write, the output buffer and EOF label (if enabled) are written before rewinding.
Any attempt to issue a buffer mode Read command (*6) or Write command (*4) when the device is not open for buffer mode, results in a <MODER> error.

Generally, when a tape error occurs, the system updates the status information in the $ZA special variable and then continues processing. But if the $ETRAP or $ZTRAP special variable is set to an error trapping routine, MSM takes the trap with $ZERROR set to <MTERR>. Errors that occur when a tape mark is encountered can be suppressed by opening the device with the 'T' option.

$ZA, $ZB, and $ZC Feedback Information

After each magnetic tape input or output command, status information about the results of the command is stored in the $ZA, $ZB, and $ZC special variables. The routine that issued the input or output command interrogates the variables and then selects an appropriate programming path based on their contents.

For the magnetic tape device, the meaning of each variable is as follows:

Variable	Description
$ZA	Contains status information about the last operation to the device. $ZA is updated when a device is opened, when an error occurs, or on a successful operation when the previous operation had an error. $ZA is a two-byte number (16 bits, in which the bits from left-to-right are 15, 14, ... 1, 0).
The bits are defined as follows:

0	Beginning of tape (not valid for cartridge tape)

1	End of tape (physical)

2	End of recorded data

3	Tape positioning in progress

4	Tape unit is online

5	Tape unit is ready

6	Tape medium has changed

7	Tape mark detected

8	Logical tape error

9	Block length error

10	Tape media error

11	Tape is write-protected

12	BUS error

13	Data overrun

14	Hardware error

15	Reserved for future use

Variable	Description
$ZB	Contains a value that indicates the number of physical bytes transferred on the last READ or WRITE operation. This value generally is the same as the block size specified by Opt3 on the OPEN command, although MSM processes short blocks correctly.
$ZC	Contains 0 if the operation completed normally, -1 if end-of-file (tape mark) was reached, or 1 if a device error occurred.
The status conditions associated with bits 0 through 6 of $ZA do not cause an error condition when they are set, and the error trap is not invoked. The error conditions associated with bits 7 through 15 of $ZA do cause the error trap to be invoked. If the tape is opened with an access mode of T (Tape Mark Inhibit), the error condition associated with bit 7 of $ZA does not invoke the error trap.

The values of $ZA $ZB, and $ZC are always returned for the current device. A USE command must be issued to specify the tape device as the current device.

Magnetic Tape Device Examples

The following examples illustrate how to use the OPEN and USE commands to access  magnetic tape devices.

OPEN, USE, and CLOSE Command Examples for Magnetic Tape Devices

OPEN/USE Command	Description
O 47:("ASU4"):60	OPENs the magnetic tape device in ASCII stream format, unlabeled, at 1600 BPI, and waits up to 60 seconds for the device to become available.
O 47:("EFL5":80:4000)	OPENs the magnetic tape device in EBCDIC format, fixed-block format, IBM standard labels, 6250 BPI, with 80 byte logical records and 4000 byte physical blocks.
O 47:("B")	OPENs the magnetic tape device in buffer mode. All operations to tape are performed from the VIEW buffer.
U 47:(:::$C(127))	Changes the stream delimiter to the DEL character.
U 47:("T")	Inhibits tape mark errors on the magnetic tape device.


Host File Server Devices

The Host File Server (HFS) allows the user to create, read, write, and modify files stored by the host operating system. The files created by the HFS are fully compatible with the host operating system file structure.

The HFS transfers information to and from a file on a logical record basis. Each  time a WRITE command is issued, information is placed in the file, and each time a READ command is issued, information up to the next line delimiter (or until a fixed-length READ is satisfied) is removed from the file. HFS devices are assigned device designators 51 through 54.

The combination of multiple devices per user and multiple files per device allows an unlimited number of files to be accessed concurrently. The only restriction on the number of open files is the limit imposed by the host operating system.

The following commands are valid for HFS devices:

OPEN	WRITE	READ
CLOSE	ZPRINT	ZLOAD
USE	ZWRITE
An HFS device is accessed by OPENing the device and specifying a file name and the mode in which the file is to accessed (for example: read, write, both read and write, or append). Optionally, a byte offset in the file can be specified. Except for buffer mode, all subsequent accesses to the file are in sequential order.

Each input or output operation begins at the byte that immediately follows the last byte of the previous input or output operation. The byte location in the file for the next read or write operation can be altered by specifying an optional parameter on the USE command before the file is accessed.

When HFS devices are accessed, input/output operations can be intermixed if the file was opened for both READ and WRITE. Data can be addressed in random-access mode. If data is accessed randomly, the location (offset) of the next data transfer must be specified prior to each I/O operation. This is done by specifying a new byte location on the USE command. When an HFS device is CLOSEd, all modified data is written back to the file at the appropriate locations.

Information sent to HFS devices is stored as a stream of logical data. Lines are terminated with the normal operating system delimiter (carriage return, line feed). Null lines are stored as the delimiter. When a READ is issued to an HFS device, the system transfers information starting at the current location. The transfer continues either until a delimiter character is encountered or the maximum number of characters specified on the READ command is reached. If necessary, the system will span blocks to satisfy the READ operation.

OPEN, USE, and CLOSE Parameters

When an HFS device is opened or when the USE command directs input or output to the device, information can be specified to indicate the file to be accessed or to position the device at a particular location.

The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} Dev{:{(Opt1:...:Opt6)}{:Time}}

USE{:Cond} Dev{:(Opt1:...:Opt6)}

CLOSE{:Cond} Dev{:(Opt1)}

In each command, the Cond operand is a post-conditional statement that is used to control execution of the command. If the post-conditional is true, the command is executed. If it is false, the command is not executed.

The Time operand on the OPEN command indicates the maximum amount of time (in seconds) to wait for the specified device to become available. After the OPEN command completes and if the time was specified, the $TEST special variable contains 1 if the OPEN was successful; otherwise, it contains 0. $TEST remains unchanged if a timeout value is not specified. The other OPEN and USE parameters are described in the following sections.

File Name - (Opt1)

This option is the name of the host operating system file to be accessed. File Name includes an optional drive and path specification (for example, D:\MDC\MSM\) and a file name (for example, MYFILE.TXT). If the name is omitted when a file is OPENed, the job owns the device, but no file is opened until Opt1 is specified in a subsequent USE command.

When an OPEN command is issued for an HFS device which is already open, the currently open file is CLOSEd before the new file is OPENed. The Opt2 parameter enables the user to specify that the old file is not to be closed, thereby allowing a single HFS device to have more than one file open. By issuing USE commands with the appropriate file name, the user can switch between the open files.

Access Mode - (Opt2)

The access mode specifies how a file is used. The following modes are valid:

R	READ-only (file must exist)
W	WRITE-only
M	Mixed access (both READ and WRITE)
A	Append to the end of the file
B	Buffer mode (shares VIEW buffer)
C	Control mode (block READ and WRITE commands)
N	No close (files previously opened using this device are not to be closed)
The value of this option can be uppercase or lowercase and must be enclosed in quotation marks (for example, "R" or "WN"). This option is ignored on the USE command (the access mode of an open file cannot be changed). If this option is omitted, READ is assumed.

In buffer mode, the HFS shares the buffer with the VIEW device (device 63). It also assumes control mode so that only block READ and WRITE commands are allowed. A block number must be specified in Opt4 of each USE command when in buffer mode.  In control mode, either of the following WRITE commands can be used:

W *4 = write buffer to current block location

W *6 = read block at current location into view buffer

A <NOPEN> error occurs if the user opens the device in buffer mode without first opening the VIEW device. An attempt to use buffer mode commands when the device is not opened for buffer mode results in a <MODER> error.

Note that the host file is always opened in a mode that allows read-share and write-share by other Windows applications. This is done in order to maintain operating compatibility with other versions of MSM.

File Offset - (Opt3)

The file offset indicates the starting byte in the file where the HFS is to be positioned. The value is relative to the location specified by Opt4. A signed value
(-5) is specified on the USE command to move forward or backward from the current position in the file. This value need not be within the file's physical bounds. For READ operations, a null is returned if the offset is not in the file. For WRITE operations, the file is expanded to the offset using the ASCII NULL character ($C(0)) as a filler. If this option is omitted, an offset of 0 (zero) is assumed for OPEN, and the offset is unchanged for USE.

Block Number / Offset Type - (Opt4)

The block number/offset type is used to provide additional positioning information to the system.

When a file is opened in buffer or control mode, the file is treated as logically contiguous 1-K blocks, with the first block being block 0. This option specifies the block number which will be used for all subsequent I/O operations. If this option is omitted, block 0 is assumed.

In any other mode, this field specifies the type of offset used in Opt3. If this option is omitted, a value of 0 is assumed. The following types are valid:

0	Indicates offsets from the beginning of the file.

1	Indicates offsets from the current position in the file.

2	Indicates offsets from the end of the file.

Record Format - (Opt5)

The record format option is used to specify the method of recording data in a block. Valid record formats are S for stream mode and V for variable-length mode. Formats must be enclosed in quotes (for example, "S"). In stream mode, the system uses the READ terminator character specified by Opt6 to separate records. When a WRITE ! is issued to the device, the READ terminator character is inserted.

In variable-length mode, the system prefixes each record with a four-byte ASCII character field that contains the length. For null records, the value of the length field is four. A length field of zero indicates an end-of-file condition. If a file recorded in variable-length format is incorrectly positioned by the USE command, unpredictable results can occur. If this option is omitted, stream format is assumed.

READ Terminator - (Opt6)

The READ terminator is used to specify the sequence of characters that separate records recorded in stream format. When a WRITE ! is issued to the device, this sequence is inserted. When a READ is issued and the sequence is encountered, an end-of-record condition occurs.

A READ terminator sequence has a length of 1 to 3 characters and can contain any ASCII character. If no READ terminator is desired, this parameter is specified as the null string (""). If this option is omitted, a READ terminator of carriage return/line feed is assumed.

$ZA, $ZB, and $ZC Feedback Information

After each HFS input or output command, status information about the results of the command are stored in the $ZA, $ZB, and $ZC special variables. The routine that issued the command interrogates the variables and then selects an appropriate programming path based on their contents.

For the HFS device, the variables have the following meanings:

Variable	Description
$ZA	Contains the number of bytes transferred to or from the file. To test for an end-of-file condition, the value of $ZA is compared to the number of bytes that should have been transferred. If they differ, the end of file was reached. If an error occurs on the transfer, this field contains a -1. Immediately after the HFS device is opened to a file, $ZA contains a -1 if the open failed (the file was not found or access was denied). Otherwise, it contains a zero (0).
$ZB	Contains the current block number if the file was opened in buffer or control mode. In any other mode, this field contains the current byte offset into the file.
$ZC	Contains 0 (zero) if the operation completed normally, -1 if end-of-file was reached, or 1 if a device error occurred.
The values of $ZA, $ZB, and $ZC are always returned for the current device. A USE command must be issued to make the HFS device the current device.

Host File Server Device Examples

The following examples illustrate how to use the OPEN, USE, and CLOSE commands to access the Host File Server devices.

OPEN, USE, and CLOSE Command Examples for Host File Servers

OPEN/USE Command	Description
O 51:("A:\GLOBAL.SAV")	Opens file GLOBAL.SAV on drive A in READ mode.
O 51:("\msm\data":"R")	Opens file DATA in the MSM directory for read-only.
O 51:("TEXT":::::$C(127))	Opens file TEXT in the current directory with a read terminator of $C(127).
O 51:("CUSTOMER":"RN")	Opens file CUSTOMER and does not close any previously open files.
U 51:(::2048)	Positions the file to byte 2048.
U 51:(::-100:1)	Moves the file offset 100 bytes back from the current position.
U 51:(:::3) WRITE *6	Reads block 3 (the 4th 1K block) from the currently OPENed file and places the data in the VIEW buffer.
U 51:("text":"w")	Closes the currently open file and opens file text in the current directory for write-only.


TCP/IP Socket Device

The TCP/IP socket device is used to establish and maintain "point-to-point" connections between two network nodes that use the TCP/IP socket protocol. It enables a Workstation process to communicate with any other process (including MSM processes), such as a client or a server, that uses the TCP/IP stream mode protocol.

The TCP/IP socket device is assigned a device designator of 56.

The following commands are valid for the TCP/IP socket device:

OPEN	CLOSE	USE
WRITE	ZPRINT	ZWRITE
READ	ZLOAD	ZUSE
To access the TCP/IP device, first OPEN and then USE device 56. The $KEY special variable will then be set with a connection identifier value. This value can be used in subsequent USE and CLOSE commands to select the specific connection for the operation. After device 56 is acquired (OPENed, then USEd), allocate a socket using a /SOCKET device mnemonic that specifies the connection address.

A connection address consists of an Internet address (Inetaddr) and a port identifier (Portid). Server processes use an Inetaddr of "" (the empty string). Client processes must specify a valid and non-null Inetaddr. Immediately after a successful call to /SOCKET, $KEY is set to the connection address value and the hostname, if known, of the system at the other end of the connection. Because subsequent OPEN or USE commands affect the value of $KEY, the value after the /SOCKET call should be saved into an MSM variable.

After a connection is established, use standard READ and WRITE commands to receive and send data. Because the TCP/IP protocol is a buffered and reliable stream protocol, the system automatically manages the network transmission for the application. Data arrival is determined by the underlying network, and there are no record boundaries. A string such as "ABCDE" may be received as the string "ABC" followed by the string "DE" (the data may require two separate READ commands). A READ without a length specifier will terminate when a complete buffer is received from the network.  A READ with a length specifier will not terminate until the specified number of characters is received, regardless of buffer boundaries. A timeout value may be used on any READ to limit the time to wait for data.

The format characters # and ! may be used with the socket device, but they do not specify record boundaries.  WRITE # will cause the network output buffer to be sent immediately.  Other actions of these format characters are controlled by the current setting of the socket characteristics.  For complete information see "Socket Characteristics to be Set - (Opt 2)".

After a connection is established, another concurrent connection may be started by issuing another OPEN and USE command sequence. The $KEY special variable will be assigned a new connection identifier.  The existing connection will not be affected and can be accessed by specifying its connection identifier on subsequent USE and CLOSE commands.

OPEN, USE, and CLOSE Parameters

When the TCP/IP socket device is opened, or input or output is directed to the device with the USE command, additional information can be specified to the system.

The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} 56{:{(:Opt2:Opt3)}{:Time}}

USE{:Cond} 56{:{(Opt1:Opt2:Opt3)}{:Domain}}

CLOSE{:Cond} 56{:Opt1}

In each command, the Cond operand is a post-conditional statement that is used to control command execution. If the post-conditional is true, the command is executed. If it is false, the command is not executed.

The Time operand on the OPEN command indicates the maximum amount of time (in seconds) to wait for the specified device to become available. After the command completes and if Time was specified, the $TEST special variable contains 1 if the OPEN was successful; otherwise, it contains 0. $TEST is unchanged if a timeout value is not specified.

Note that every Workstation application has its own private socket device, so an OPEN command should always succeed.

Connection – (Opt1)

When specified with the USE and CLOSE commands, this option selects which connection is to be USEd or CLOSEd. The value is obtained from $KEY after the initial OPEN and USE. If Connection is omitted on the USE command, the last USEd or OPENed socket connection becomes the current connection. If Connection is omitted on the CLOSE command, all existing socket connections for the application are closed.

Socket Characteristics to be Set - (Opt2)

When specified with the OPEN and USE commands, this option selects one or more characteristics that are to be enabled for all subsequent I/O to the socket.  The value of this option, when evaluated in binary, represents a bit string in which each bit specifies a characteristic to be enabled.  If the bit is on, then the characteristic is set.  If the bit is off, the characteristic is unchanged.  If any characteristcs are specified in Opt3 they will be turned off before characteristics specified in Opt2 are turned on.

The following table lists the bit numbers and describes the functions associated with each bit value. All bit values not listed are reserved for future use.

Bit	Description
5	If this bit is set, WRITE ! will send the network output buffer immediately, and WRITE # will insert a carriage return-form feed sequence, $C(13,12), into the output stream. This bit provides compatibility with version 4.2 of MSM. If this bit is not set, WRITE ! does not cause the output buffer to be sent, and WRITE # does not add any data to the output stream. (Decimal value = 32)
1	If this bit is set, each WRITE argument causes the network output buffer to be sent immediately.  If this bit is not set, the output buffer is sent when it becomes full.  (Decimal value = 2)
0	If this bit is set, WRITE ! will insert a carriage return-line feed sequence, $C(13,10), into the output stream.  If this bit is not set, WRITE ! does not add any data to the output stream.  (Decimal value = 1)
Socket Characteristics to be Cleared - (Opt3)

When specified with the OPEN and USE commands, this option selects one or more characteristics that will be disabled for all subsequent I/O to the socket. The value of this option, when evaluated in binary, represents a bit string in which each bit specifies a characteristic to be disabled.  If the bit is on, then the characteristic is disabled.  If the bit is off, the characteristic is unchanged.  The definition for the bits is the same as described for the Socket Characteristics to be Set - (Opt2).

Domain

The Domain operand on the USE command specifies the mnemonic namespace to be used. If this optional parameter is included on the USE command, it must be an expression that evaluates to "TCP", which is the only domain currently supported.


Socket Control Mnemonics

Sockets are accessed via the mnemonic namespace of "TCP".  In this namespace, the following two control mnemonics are provided:

/SOCKET(Inetaddr,Portid)

/URGENT

/SOCKET(Inetaddr,Portid)

Use the /SOCKET control mnemonic to establish a connection. The Inetaddr parameter must be either the null string (""), a Hostname, or a string that contains a valid IP address in the form N.N.N.N, in which each N is an unsigned integer value in the range 0 through 255, inclusive. The Portid parameter must be an integer value in the range 0 through 65535, inclusive.

If the Inetaddr parameter is the null string, then the Workstation application becomes a server and listens for a connection request on the specified Portid. After a connection is established, the $KEY special system variable contains a string in the form Inetaddr,Hostname, in which Inetaddr is the client's network address and Hostname is the client's host name. If the client's host name is not known, this field and the preceding comma are omitted. This form of the mnemonic generally only terminates when a connection request is received, or if a keyboard interrupt occurs on the principal device (enabled with BREAK 1).

If the Inetaddr parameter is not the null string, the Workstation application initiates a client connection to the server which is listening on Portid at Inetaddr. After a connection is established, $ZB equals zero and $KEY contains the Inetaddr of the server. Connection failure (for example, no server found at the specified address and port) returns a non-zero value in $ZB. See below for details.

/URGENT

Use this control mnemonic to set the urgent bit, as defined by the TCP/IP protocol. The urgent bit is automatically reset after each transmission.


Record Boundaries

The TCP/IP protocol does not provide for record boundaries within the data. The application must use special characters or another technique to delimit records. Timed READ commands and fixed-length READ commands are often used by client/server applications.

Because TCP/IP guarantees reliable (non-corrupted) transmissions, an application can send and receive fixed-length records by using fixed-length READ commands. Another approach is to use variable-length records. For variable-length records, the application can send the length field as a fixed-length record, followed by the actual data as a variable-length record. The receiving process uses a fixed-length READ command to read the length field. Then it uses the value of the length field to issue a fixed-length READ command for the actual data.

For example, the client may encode the length as a two-byte, fixed-length field:

U 56 W $C($L(str)\256,$L(str)#256),str

The server can read the encoded length followed by the string:

U 56 R hi#1,lo#1 S len=$A(hi)*256+$A(lo) R str#len


$ZA, $ZB, and $ZC Feedback Information

After each TCP/IP Socket device command, status information about the results are stored in the $ZA, $ZB, and $ZC special variables. The routine that issued the command can interrogate these variables and perform actions based on their contents. For the TCP/IP Socket, variables have the following meanings.

$ZA	Contains the number of characters remaining in the input buffer after the last READ operation.
$ZB	Contains zero if the operation completed normally, or
	Contains one of the following coded error types:
	-1	End of input
	-2	No socket allocated
	-3	Operation timed-out
	-4	Operation interrupted by BREAK key
	-5	No server allocated (not applicable to MSM-Workstation)
	-6	A connection already exists
	-7	No resources to create socket
	-8	License limit exceeded
	-9	The operating system socket operation failed
	-10	Variable-length READ timed out
	n	Positive integer indicates WinSock error code
$ZC	Contains 0 (zero) if the operation completed normally, 1 if an error occurred, or -1 on end-of-file (the remote system closed the connection).
The values of $ZA $ZB, and $ZC are always returned for the current device.

TCP/IP Socket Device Examples

The following examples illustrate how to access the TCP/IP Socket device by using the OPEN, USE, and CLOSE commands.

1.	OPEN 56 USE 56:(:3)

Opens the TCP/IP Socket device and enables the socket characteristics for Bits 0 and 1.  Therefore, each WRITE ! will output a carriage return-line feed string, and each WRITE argument will be send the output buffer immediately.

2.	WRITE /SOCKET("",20850)

Becomes a server and listens for an incoming connection on port 20850.

3.	WRITE /SOCKET("127.1.79.139",20850)

Establishes a client connection to the server at 127.1.79.139.

4.	The following code illustrates using two sockets concurrently, reading from one, and writing to the other. Complete application code generally includes more elaborate error handling.

O 56 U 56 SET DEVIN=$KEY ; get input socket
U 56:DEVIN W /SOCKET("",INPORT) ; wait for connect

O 56 U 56 S DEVOUT=$KEY ; get output socket

U 56:DEVOUT W /SOCKET(ADDR,PORT) ; call another server
FOR  DO  QUIT:$DATA(QUIT)
. U 56:DEVIN READ X I $ZC S QUIT=1 Q ; read from caller
. U 56:DEVOUT W X ; write to server


VIEW Device

The MSM system includes one VIEW device, which is used to read or modify information stored on disk. The VIEW device is assigned a designator of 63.

The following commands and functions are valid for the VIEW device:

OPEN	USE	CLOSE
$VIEW	VIEW
To use the forms of the VIEW command or $VIEW function that access the VIEW buffer, the VIEW device needs to be OPENed. However it need not be the current device.

OPEN, USE, and CLOSE Parameters

Before accessing the VIEW buffer the user must obtain ownership of the VIEW device by issuing it an OPEN command.

The format of the OPEN, USE, and CLOSE commands is as follows:

OPEN{:Cond} 63{:(Opt1:Opt2:Opt3:Opt4)}{:Time}

USE{:Cond} 63{:(Opt1:Opt2:Opt3:Opt4)}

CLOSE{:Cond} 63

In this command, the Cond operand is a post-conditional statement that is used to control command execution. If the post-conditional is true, the command is executed. If it is false, the command is not executed. The Time operand on the OPEN command indicates the amount of time (in seconds) to wait for the specified device to become available. After the OPEN command completes and if the time was specified, the $TEST special variable contains 1 if the OPEN was successful. Otherwise, it contains 0 (zero). $TEST is unchanged if a timeout value is not specified.

Note that every Workstation application has its own private VIEW device, so an OPEN command should always succeed.

Before disk data can be modified, the VIEW device must be owned. When the VIEW device is opened, a buffer is assigned to the device. This area in memory is the VIEW buffer.

The size of the VIEW buffer is set to 1K bytes, matching a disk block size. Disk data is read into or written from this area. When device 63 is CLOSEd, modified data in the VIEW buffer is not automatically written to disk.

Reserved for Future Use - (Opt1)

This option is reserved for future use, and should be left empty.

Reserved for Future Use - (Opt2)

This option is reserved for future use, and should be left empty.

Reserved for Future Use - (Opt3)

This option is reserved for future use, and should be left empty.

Mode Switches - (Opt4)

This option is used to specify the mode in which the VIEW device is used.

The following options are valid:

P	Protected mode access (provides exclusive access to referenced blocks)

T	Test mode (inhibits <DKHER> errors)

C	Clear mode (resets all switches)

Z	Block zero access (allows block 0 to be written).

The value of this option can be uppercase or lowercase and must be enclosed in quotation marks (for example,  "P").

$ZA, $ZB, and $ZC Feedback Information

After each input or output operation using the VIEW device to disk, the $ZA special variable contains the block number of the disk block contained in the VIEW buffer. Because the $ZB and $ZC special variables are not used with the VIEW device, their contents are unspecified.

VIEW Device Examples

The following examples illustrate how to use the OPEN, USE, and CLOSE commands to access the VIEW device.

OPEN, USE, and CLOSE Commands Examples for VIEW Devices

OPEN/USE Command	Description
O 63::60	OPENs the VIEW device and waits up to 60 seconds for the device to become available.
O 63:(:::"Z")	Allows the user to WRITE block 0 (zero) of any volume group. If this switch is not set, block 0 can only be read.


Console Windows and MWAPI

MSM-Workstation's console windows are integrated into MWAPI. Whenever a console window device is open, a corresponding structure exists in the ssvn ^$WINDOW. The initial subscript is equal to the device number, 1 or 31 to 37. By default the window type is ZMTERM and the windows support capabilities that differ from or enhance those defined for the standard MTERM type.

A console window's settings can be pre-defined in advance of the OPEN command by MERGEing a suitable MWAPI structure into the corresponding ^$WINDOW subtree. When this is done, the definition persists in ^$WINDOW after the device has been CLOSEd.

Such pre-creation of the definition is necessary in the case of certain advanced window attributes which can only be applied when the device is first opened, but which are not accessible through OPEN command parameters.

One example is the ZNOCLOSE attribute that can be used to suppress the close-button on a ZMTERM.  This must be defined in ^$WINDOW before opening the ZMTERM window. For example:

K w

S w("TYPE")="ZMTERM"

S w("ZNOCLOSE")=1

C 31

K ^$W(31)

M ^$W(31)=w

O 31

Another is the ZVTAREA attribute, which dictates the area of the window over which VT cursor addressing can operate. This defaults to 80,24 but if a fully-addressable 25-line 80-column display is required, use the following:

K w

S w("TYPE")="ZMTERM"

S w("SIZE")="80,25,CHAR"

S w("ZVTAREA")="80,25"

C 31

K ^$W(31)

M ^$W(31)=w

O 31

Many attributes in ^$WINDOW can be altered after the window has been opened. For example, to display the toolbar on device 31:

SET ^$WINDOW(31,"ZTBVISIBLE")=1


Console Window User Interface Elements

MSM-Workstation console windows support clipboard operations and font size selection. As part of the user interface for these features, a toolbar can be shown on the console window.

To access the features, select the window's System menu (click on the top left corner) and then select the Edit option.

The Extended System Menu

The same menu appears as a pop-up if you right-click on the window surface or press the Windows 95 menu key.

See Also:

Using the System Menu Commands

Selecting and Copying Text in Mark-Mode


Using the System Menu Commands

Toolbar Command

The Toolbar command shows or hides a tool bar on the window. The menu entry is checked when the toolbar is visible.

The Toolbar

The toolbar provides a drop-down list for font selection as well as buttons that correspond to the Mark, Copy, and Paste commands.  Tooltips are provided for these controls.

Mark Command

The Mark command puts the window into mark-mode. The command is disabled when the window is in scroll-mode (see below).  In mark-mode, the window title is prefixed with the word "Mark," the Mark menu entry is checked, and the Mark button on the toolbar is depressed.  On entry to mark-mode, the cursor is enlarged to be one character high, and is positioned at the top-left corner of the viewport.  Mark-mode allows use of the keyboard or mouse to select text for copying to the clipboard.

To cancel mark-mode, press ESC. Mark-mode is automatically canceled as a side-effect of the Copy command.

Copy Command

The Copy command is disabled on the menu and toolbar unless part of the text in the window is selected.  When enabled, it can be used to copy the selected text to the clipboard.

Paste Command

The Paste command is disabled on the menu and toolbar unless the clipboard contains text and the window is in a state that accepts input.  The command causes the text in the clipboard to be inserted into the keyboard buffer as though it had been typed at that point.  The characters being pasted are buffered separately, so the amount pasted is not limited by the size of the keyboard buffer.  Only one paste buffer is provided per console window.

The Paste command is ignored if previously pasted text has not been completely read or flushed from the buffer.  When pasting, the final CR/LF is removed from the clipboard text, allowing pasted commands to be edited if required before final entry.

Scroll Command

The Scroll command is disabled except when the window has scrollbars present and is not in mark-mode.  Scroll puts the window into scroll-mode.  In scroll-mode, the window caption is prefixed with the word "Scroll," and the Scroll menu entry is checked. While in scroll-mode the application's output is paused, and the keys listed below can be used to scroll the viewport around the content of the window's screen buffer. The window keeps track of the right-most and bottom-most position used in its screen buffer since the last time it was cleared, and uses these limits to define the viewable area.

Scroll-Mode Keys

Key	Action
RIGHT	Moves the viewport one character right.
CTRL+RIGHT	Moves the viewport several characters right.
LEFT	Moves the viewport one character left.
CTRL+LEFT	Moves the viewport several characters left.
UP	Moves the viewport one character up.
PAGE UP	Moves the viewport several characters up.
DOWN	Moves the viewport one character down.
PAGE DOWN	Moves the viewport several characters down.
HOME	Moves the viewport to the left of the display.
END	Moves the viewport to the right of the viewable display.
CTRL+HOME	Moves the viewport to the top of the display.
CTRL+END	Moves the viewport to the bottom of the viewable display.
To cancel scroll-mode, press ESC or any other key that is not in the Scroll-Mode Keys table.  If scroll-mode is canceled with any key other than ESC, the key press is treated as part of normal input.

Font Command

As the Font List figure in this section illustrates, the Font command displays a list of available fonts).  If the command is used while the toolbar is hidden, the toolbar is shown and remains visible until a font is selected.

The fonts are listed in order of width (and in order of height within width) and are measured in pixels.  The list shows all the available sizes of the Terminal font, which is a raster font.  If suitably configured, the list provides a set of sizes for a TrueType font, marked by the TrueType symbol to the left of each listed size.

Selecting an entry in the list changes the font in the window to match the size selected.  If the resulting window display size is smaller than the viewport, the  window size is adjusted to match. Otherwise, scrollbars are shown/hidden as appropriate.

The Font List


Selecting and Copying Text in Mark-Mode

The window keeps track of the right-most and bottom-most position used in its screen buffer since the last time the display was cleared, and uses these limits to define the boundaries of the viewable display.  Only text within the viewable area can be selected.

In mark-mode, a large cursor is displayed.  The cursor can be moved anywhere within the viewable area using the keyboard or the mouse.  Clicking the mouse moves the cursor to the character nearest the point clicked.  The keyboard interface is as follows.

Mark-Mode Keys

Key	Action
LEFT ARROW	Moves the cursor one character left.
RIGHT ARROW	Moves the cursor one character right.
UP ARROW	Moves the cursor one character up.
DOWN ARROW	Moves the cursor one character down.
HOME	Moves the cursor to the start of the current line.
CTRL+HOME	Moves the cursor to the top left corner of the viewable area.
END	Moves the cursor to the end of the current line.
CTRL+END	Moves the cursor to the bottom right corner of the viewable area.
PAGE UP	Moves the cursor up by the height of the viewport.
PAGE DOWN	Moves the cursor down by the height of the viewport.
To select a rectangle of the viewable area, move the cursor to the start of the area, and then press SHIFT while moving the cursor to the end of the area, using the keyboard and/or a left-mouse click. You also can select an area by pressing the left mouse button at the start point of the area and moving the mouse with the button held down.

Note   On wide-character versions of MSM-Workstation (for example, Japanese) each character on the window can occupy either one or two screen positions.  The left or right edge of the selection rectangle may split characters, with only half of a character being completely within the rectangle.  If this happens, the entire character is considered to be selected and is highlighted accordingly.

The selected area is highlighted, and the Copy command is enabled.  Any additional cursor movement clears or extends the selection, depending on whether SHIFT is pressed at the time. When enabled, the Copy command can be invoked from the toolbar or the System menu; by pressing ENTER; or by a right-mouse click.

The Copy command copies the selected text to the clipboard.  Each line of text in the selection is copied with trailing spaces removed and a CR/LF added.  The Copy command also deselects the text and cancels mark-mode, returning the window to its normal state.


Terminal Emulation Features of Console Window Devices

This section defines the terminal emulation features that MSM-Workstation provides for the Console Window devices.

The ANSI sequences described in this document are supported by MSM-Workstation. Desired functions sometimes may not be achieved due to hardware characteristics or limitations. For example, if you request underlining on a color system, the character is displayed in blue. This is not an emulation error, but simply the hardware's operating limitation.

The following sections provide definitions and examples of the terminal emulation features that are supported by MSM-Workstation. To enable the mnemonics listed, a USE command must previously have been issued, specifying the domain "X3.64-1979".

See Also:

ANSI Escape Abbreviations

ASCII Control Characters

Cursor Movement Sequences

Screen Erase Sequences

Insert and Delete Sequences

Keyboard Mapping and Translation

Program Function Keys

Reprogramming the Function Keys

Video Character Attributes

Establish Scrolling Region

Graphics Character Sets

Hebrew Language Support

Miscellaneous Sequences

Display Control Characters

ANSI Escape Sequence Examples

Reports

VT Keyboard Escape Processing

MSM-PC/PLUS Compatibility


ANSI Escape Abbreviations

The following table defines the abbreviations that are used in the ANSI escape sequence descriptions.

ANSI Escape Abbreviations

Abbreviation	Description
ESC	The ASCII escape control character (the character with a decimal value of 27).
0xNN	Indicates that the characters represented by NN express a hexadecimal value.
Pn	A numeric value expressed as a string of ASCII digits  (for example, 12, 1, and so on).
Pl	A line number (row number) on the display. The first line is 1, the second 2, and so on.
Pc	A column number on the display. The first column is 1, the second is 2, and so on.
Pt	The starting line number of a box expressed in the same form as Pl.
Pb	The ending line number of a box expressed in the same form as Pl.
Ps	The starting column number of a box expressed in the same form as Pc.
Pr	The ending column number of a box expressed in the same form as Pc.
Pa	An attribute character that is used to modify display characteristics.
The maximum line number is 24, and the maximum column number is 80, unless increased using the ZVTAREA attribute of the device's ^$WINDOW structure.


ASCII Control Characters

ASCII control characters perform the same basic functions on all terminals. The tables in this section list the ASCII control characters supported by Workstation console devices and describe the control characters' basic functions.

ASCII Control Characters: 7-bit

Character	Name	Description	Mnemonic
7	BEL	Rings the bell.	/BEL
8	BS	Backspaces one character.	/BS
9	HT	Tabs horizontally to the next tab position.	/HT
10	LF	Performs a line feed (next line, same column).	/LF
11	VT	Performs a vertical tab (same as line feed).	/VT
12	FF	Performs a form feed.	/FF
13	CR	Inserts a carriage return (RETURN or ENTER key).	/CR
24	CAN	Cancels an escape sequence.
26	SUB	Cancels an escape sequence.
27	ESC	Introduces an escape sequence.
127	DEL	Displays the character located at this point in the current character set.
The following control characters are also recognized once the appropriate DECSCL sequence has enabled 8-bit controls.

ASCII Control Characters: 8-bit

Character	Two-character Equivalent	Name	Description
132 0x84	ESC D	IND	Moves cursor down in same column with scroll.
133 0x85	ESC E	NEL	Moves cursor down to next line in column one.
141 0x8D	ESC M	RI	Moves cursor up in same column with scroll.
144 0x90	ESC P	DCS	Introduces a device control string.
155 0x9B	ESC [	CSI	Introduces a control sequence.
156 0x9C	ESC \	ST	Ends a device control string.


Cursor Movement Sequences

Cursor movement sequences allow an application to position the cursor at a specific screen location before reading or writing data. The following table lists the escape sequences that control cursor movement on the console device.

Cursor Movement Sequences

Name	Description	Escape Sequence	Mnemonic
CUP HVP	Cursor position.	CSI Pl ; Pc H CSI Pl ; Pc f	/CUP[(Pl,Pc)] /HVP[(Pl,Pc)]
CUP HVP	Cursor home (default Pl,Pc = 1).	CSI H CSI f	/CUP /HVP
CUU	Cursor up (in same column, no scroll).	CSI Pn A or CSI A	/CUU[(Pn)]
CUD	Cursor down (in same column, no scroll).	CSI Pn B or CSI B	/CUD[(Pn)]
CUF	Cursor forward (right).	CSI Pn C or CSI C	/CUF[(Pn)]
CUB	Cursor backward (left).	CSI Pn D or CSI D	/CUB[(Pn)]
IND	Index (in same column, with scroll).	IND or ESC D	/IND
RI	Cursor up one row (in same column, with scroll).	RI or ESC M	/RI
NEL	Next line.	NEL or ESC E	/NEL
DECBI	Cursor backward (left) one column.	ESC 6
DECSC	Saves cursor and attributes.	ESC 7
DECRC	Restores cursor and attributes.	ESC 8
DECFI	Cursor forward (right) one column.	ESC 9


Screen Erase Sequences

Screen erase sequences allow an application program to erase (clear to blank) all or selected portions of a screen.  Screen erasing generally is performed prior to reading data from or writing data to the screen.  The following table lists the sequences that control screen erasing on the console device.

Screen Erase Sequences

Name	Description	Escape Sequence	Mnemonic
ED	Erases in display:	CSI Ps J	/ED
	Cursor to end of display	CSI 0 J or CSI J	/ED(0)
	Beginning through cursor	CSI 1 J	/ED(1)
	Complete display	CSI 2 J	/ED(2)
EL	Erases in line:	CSI Ps K	/EL
	Cursor to end of line	CSI 0 K or CSI K	/EL(0)
	Beginning through cursor	CSI 1 K	/EL(1)
	Complete line	CSI 2 K	/EL(2)


Insert and Delete Sequences

The insert and delete sequences allow an application to add or delete lines to the screen, add or delete characters to a line, or change characters in a line to blanks.  The following table lists the sequences that are used to perform the insert and delete functions.

Insert and Delete Sequences

Name	Description	Escape Sequence	Mnemonic
IL	Inserts blank lines.	CSI Pn L	/IL[(Pn)]
DL	Deletes lines.	CSI Pn M	/DL[(Pn)]
ICH	Inserts blank characters.	CSI Pn @	/ICH[(Pn)]
DCH	Deletes characters.	CSI Pn P	/DCH[(Pn)]
ECH	Erases characters (changes to blanks).	CSI Pn X	/ECH[(Pn)]
IRM	Insert/replace mode:
	Insert mode	CSI 4 h
	Replace mode	CSI 4 l


Keyboard Mapping and Translation

The tables in this section map the translation of certain keys on the PC keyboard to keys on VT-type terminals, and include the generated characters and escape sequences.

The Modes table lists the supported emulation modes for the MSM-Workstation console window devices.

Modes

Name	Description	Sequence
DECSCL	VT 420 mode, 8-bit controls	CSI 6 4 ; 0 " p   or CSI 6 4 ; 2 " p
DECSCL	VT 420 mode, 7-bit controls (default)	CSI 6 4 ; 1 " p
DECKPAM	Keypad sends application sequences	ESC =
DECKPNM	Keypad sends character(s) shown on key	ESC >
DECCKM	Cursor key mode:
	Application mode	CSI ? 1 h
	Cursor key	CSI ? 1 l
DECBKM	Backspace key redefinition:
	8 (default)	CSI ? 6 7 h
	127	CSI ? 6 7 l
Main Keyboard Mapping

PC Key	Emulation Mode VT Keyboard
BACKSPACE	DECBKM set DECBKM reset	0x08 0x7F
TAB	Tab	0x09
SHIFT+TAB	Shift+Tab	CSI Z
DEL (On NumKeyPad, NUM LOCK off)	Delete	0x7F
Edit and Cursor Keypads

PC Key	VT Keyboard	Characters (DECCKM Mode)	Characters (not DECCKM)
HOME	Find	CSI 1 ~	CSI 1 ~
INSERT	Insert	CSI 2 ~	CSI 2 ~
DELETE	Remove	CSI 3 ~	CSI 3 ~
END	Select	CSI 4 ~	CSI 4 ~
PGUP	PrevScr	CSI 5 ~	CSI 5 ~
PGDN	NextScr	CSI 6 ~	CSI 6 ~
↑	↑	CSI A	ESC O A
↓	↓	CSI B	ESC O B
→	→	CSI C	ESC O C
←	←	CSI D	ESC O D
Numeric Keypad

PC Key	VT Keyboard	Characters DECKPNM Mode     (Num Lock) ON                OFF	Characters DECKPAM Mode
0  (Insert)	0	0	CSI 2	ESC O p
1  (End)	1	1	CSI 4	ESC O q
2  ( ↓ )	2	2	CSI B	ESC O  r
3  (PgDn)	3	3	CSI 6	ESC O s
4  ( ← )	4	4	CSI D	ESC O t
5	5	5		ESC O u
6  ( → )	6	6	CSI C	ESC O v
7  (Home)	7	7	CSI H	ESC O w
8  ( ↑ )	8	8	CSI A	ESC O x
9  (PgUp)	9	9	CSI 5	ESC O y
.  (Del)	.	.	Delete (0x7F)	ESC O n
Num Lock	(PF1)			ESC O P
/	(PF2)	/	/	ESC O Q
*	(PF3)	*	*	ESC O R
-	(PF4)	-	-	ESC O S
+	,	+	+	ESC O l
ALT -	-			ESC O m
ENTER	ENTER	CR (0x0D)	CR (0x0D)	ESC O M


Program Function Keys

Program function keys allow you to enter information in an application by using a single key stroke. These keys generally terminate a READ operation.

The following table lists the input sequences that are received when you press the corresponding program function key.

Non-Shifted Function Key Sequences

PC Keyboard Key	VT Keyboard Key and Sequence
F1	F1	CSI 1 1 ~
F2	F2	CSI 1 2 ~
F3	F3	CSI 1 3 ~
F4	F4	CSI 1 4 ~
F5	F5	CSI 1 5 ~
F6	F6	CSI 1 7 ~
F7	F7	CSI 1 8 ~
F8	F8	CSI 1 9 ~
F9	F9	CSI 2 0 ~
F10	F10	CSI 2 1 ~
F11	F11	CSI 2 3 ~
F12	F12	CSI 2 4 ~
ALT - F1	F11	CSI 2 3 ~
ALT - F2	F12	CSI 2 4 ~
ALT - F3	F13	CSI 2 5 ~
ALT - F4	F14	CSI 2 6 ~
ALT - F5	F15	CSI 2 8 ~
ALT - F6	F16	CSI 2 9 ~
ALT - F7	F17	CSI 3 1 ~
ALT - F8	F18	CSI 3 2 ~
ALT - F9	F19	CSI 3 3 ~
ALT - F10	F20	CSI 3 4 ~
ALT - F11		CSI 3 5 ~
ALT - F12		CSI 3 6 ~
Shifted Function Key Sequences

PC Keyboard Key	VT Keyboard Key and Sequence
SHIFT - F1	SHIFT-F1	CSI 1 1 ; 2 ~
SHIFT - F2	SHIFT - F2	CSI 1 2 ; 2 ~
SHIFT - F3	SHIFT - F3	CSI 1 3 ; 2 ~
SHIFT - F4	SHIFT - F4	CSI 1 4 ; 2 ~
SHIFT - F5	SHIFT - F5	CSI 1 5 ; 2 ~
SHIFT - F6	SHIFT - F6	CSI 1 7 ; 2 ~
SHIFT - F7	SHIFT - F7	CSI 1 8 ; 2 ~
SHIFT - F8	SHIFT - F8	CSI 1 9 ; 2 ~
SHIFT - F9	SHIFT - F9	CSI 2 0 ; 2 ~
SHIFT - F10	SHIFT - F10	CSI 2 1 ; 2 ~
SHIFT - F11	SHIFT - F11	CSI 2 3 ; 2 ~
SHIFT - F12	SHIFT - F12	CSI 2 4 ; 2 ~
SHIFT ALT - F1	SHIFT - F11	CSI 2 3 ; 2 ~
SHIFT ALT - F2	SHIFT - F12	CSI 2 4 ; 2 ~
SHIFT ALT - F3	SHIFT - F13	CSI 2 5 ; 2 ~
SHIFT ALT - F4	SHIFT - F14	CSI 2 6 ; 2 ~
SHIFT ALT - F5	SHIFT - F15	CSI 2 8 ; 2 ~
SHIFT ALT - F6	SHIFT - F16	CSI 2 9 ; 2 ~
SHIFT ALT - F7	SHIFT - F17	CSI 3 1 ; 2 ~
SHIFT ALT - F8	SHIFT - F18	CSI 3 2 ; 2 ~
SHIFT ALT - F9	SHIFT - F19	CSI 3 3 ; 2 ~
SHIFT ALT - F10	SHIFT - F20	CSI 3 4 ; 2 ~
SHIFT ALT - F11		CSI 3 5 ; 2 ~
SHIFT ALT - F12		CSI 3 6 ; 2 ~
When escape processing is turned on, these escape sequences do not appear in READ input, but alter the $ZB variable instead. More information about this can be found later in this section, and in the "Console Window Devices" section.


Reprogramming the Function Keys

You can reprogram the twelve program function keys on the console keyboard to generate any string of ASCII characters.  This process generally is compatible with the DEC VT 420 terminal. You can program the keys in four modes:  non-shifted, ALT, shifted, and ALT-shifted.  The value generated by a function key can differ depending on whether you press SHIFT or ALT.

The service routine entry-point CHGKEY^%msc provides a convenient way of reprogramming these keys. Alternatively, use the escape-sequence described below.

The following text illustrates the format of the escape sequence used to re-program the function keys:

Esc P Clear;Lock;Modifier|Key1/Val1;Key2/Val2;…Keyn/Valn Esc\

The meaning attributed to the Clear, Lock, and Modifier parameters in this sequence is described in the following three tables.

Clear Flag

Value	Meaning
0 or none	Clears all keys before loading the new values.
1	Clear one key at a time before loading a new value. The terminal clears only the keys you load.
Lock Flag

Value	Meaning
0 or none	Locks the specified keys so they cannot be reprogrammed.
1	Does not prevent reprogramming of the specified keys.
Modifier Flag

Value	Meaning
0, 2, or none	Defines the shifted function key.
1	Defines the non-shifted function key.
3	Defines the alternate non-shifted function key.
4	Defines the alternate shifted function key.
Each function key is identified by a unique code (Keyn). Refer to the Function Key Codes table for a list of these codes. The new string value for a key (Valn) is specified as a hexadecimal number. To change the shifted value of F6 to the letter A, Key1 is 17, and Val1 is 41 ($ZHEX($ASCII("A"))).

You can list an unlimited number of keys on the escape sequence, as long as the total length of all the re-programmed characters does not exceed 768. For example, you can reprogram F6 to generate a string of 512 Xs, or you can program F6 to send a 200-character string and F7 to send a 312-character string. Any combination is possible if the total number of characters reprogrammed into all of the keys does not exceed the 768-character limit.

 Function Key Codes

Keyn	Modifier Value
	1	None, 0, or 2	3	4
11	F1	SHIFT – F1	ALT – F1	ALT – SHIFT – F1
12	F2	SHIFT – F2	ALT – F2	ALT – SHIFT – F2
13	F3	SHIFT – F3	ALT – F3	ALT – SHIFT – F3
14	F4	SHIFT – F4	ALT – F4	ALT – SHIFT – F4
15	F5	SHIFT – F5	ALT – F5	ALT – SHIFT – F5
17	F6	SHIFT – F6	ALT – F6	ALT – SHIFT – F6
18	F7	SHIFT – F7	ALT – F7	ALT – SHIFT – F7
19	F8	SHIFT – F8	ALT – F8	ALT – SHIFT – F8
20	F9	SHIFT – F9	ALT – F9	ALT – SHIFT – F9
21	F10	SHIFT – F10	ALT – F10	ALT – SHIFT – F10
23	F11	SHIFT – F11	ALT – F11	ALT – SHIFT – F11
24	F12	SHIFT – F12	ALT – F12	ALT – SHIFT – F12
25	ALT – F3	ALT – SHIFT – F3
26	ALT – F4	ALT – SHIFT – F4
28	ALT – F5	ALT – SHIFT – F5
29	ALT – F6	ALT – SHIFT – F6
31	ALT – F7	ALT – SHIFT – F7
32	ALT – F8	ALT – SHIFT – F8
33	ALT – F9	ALT – SHIFT – F9
34	ALT – F10	ALT – SHIFT – F10
35	ALT – F11	ALT – SHIFT – F11
36	ALT – F12	ALT – SHIFT – F12
The following example illustrates a programming sequence that loads a new set of escape sequences into the F6 and  F7 program function keys without altering the value of other keys.  After the sequence completes, the program function keys are locked to prevent additional reprogramming.

W *27,"P1;0;1|17/1B41;18/1B42",*27,"\"

In this example, F6 returns an ESC A (1B41 in hexadecimal) string, and F7 returns an ESC B (1B42 in hexadecimal) string.


Video Character Attributes

Video character attributes allow an application to highlight a portion of the screen with colors, bold characters, or reverse-video characters.  The following table lists the sequences that control video attributes on the console device.

Video Attribute Sequences

Name	Description	Escape Sequence	Mnemonic
SGR	Sets character attribute.	CSI Pa ; Pa ; … ; Pa m	/SGR[(Pa,Pa…)]
		Pa is one of the following:
		0 = All attributes off
		1 = Bold on
		2 = Bold off
		4 = Underline on
		7 = Reverse-video on
		8 = Canceled on (invisible)
		22 = Bold off
		24 = Underline off
		27 = Reverse-video off
		28 = Invisible off
		30 = Black foreground
		31 = Red foreground
		32 = Green foreground
		33 = Yellow foreground
		34 = Blue foreground
		35 = Magenta foreground
		36 = Cyan foreground
		37 = White foreground
		40 = Black background
		41 = Red background
		42 = Green background
		43 = Yellow background
		44 = Blue background
		45 = Magenta background
		46 = Cyan background
		47 = White background
		Invalid parameters are ignored.


Establish Scrolling Region

Use the sequence listed in the following table to construct a scrolling region on the console device. The default scrolling region is 80 columns and 24 rows. The top row is row one.

Scrolling Region Sequences

Name	Description	Escape Sequence	Mnemonic
DECSTBM	Sets top and bottom margins.	CSI Pt ; Pb r


Graphics Character Sets

Standard ANSI terminals can display certain graphics characters. Standard Windows character sets can display a limited subset of ANSI terminal graphics characters. Although DEC VT terminals support four character set designations, MSM-Workstation supports only the G0 character set designation.

Use the following sequences to switch between the graphics character set and the standard character set.

Character Set Sequences

Name	Description	Escape Sequence
SCS	Select ASCII characters.	ESC ( B
SCS	Select graphics characters.	ESC ( 0
When the graphics character set is selected, some characters sent to the device are displayed as graphics characters.  The following table lists the graphics characters and the ASCII characters that generate them.

Graphics Characters

$A(n)	$C(n)	Graphic	Description
102	F	°	Degree symbol
103	G	±	Plus/minus sign
106	J	+	Lower-right corner
107	K	+	Upper-right corner
108	L	Ú	Upper-left corner
109	M	+	Lower-left corner
110	N	+	Box intersection
113	Q	-	Box line
116	T	Ã	Horizontal left-end meets vertical
117	U	´	Horizontal right-end meets vertical
118	V	Á	Inverted connector
119	W	Â	Regular connector
120	X	|	Vertical line
123	{	π	Pi
125	}	£	United Kingdom currency sign
126	~	•	Bullet


Hebrew Language Support

The following MSM-specific escape sequences are provided to support applications using the Hebrew language.

Hebrew Language Sequences

Description	Escape Sequence
Select 7-bit Hebrew character set	ESC ) J
Select 8-bit Hebrew character set	ESC ) K
Select DEC Hebrew character set	ESC ) D
Deselect Hebrew character set	ESC ) L
Set cursor direction right-to-left	ESC ) I
Set cursor direction left-to-right	ESC ) B


Miscellaneous Sequences

Miscellaneous escape sequences enable an applications program to perform useful functions. The following table lists these escape sequences and their functions.

Miscellaneous Sequences

Name	Description	Escape Sequence
DECAWM	Turns on wrap at column 80 (inserts carriage return).	CSI ? 7 h
DECAWM	Turns off wrap at column 80 (does not insert carriage return).	CSI ? 7 l
DECSCNM	Turns on monochrome background reverse-video.	CSI ? 5 h
DECSCNM	Turns off monochrome background reverse-video (default).	CSI ? 5 l
DECTCEM	Show cursor (default).	CSI ? 2 5 h
DECTCEM	Hide cursor.	CSI ? 2 5 l


Display Control Characters

On the console device, special characters can be displayed for the standard ASCII control characters (decimal values 0 through 31).  For example, the ASCII character 2 ($C(2) character) displays a symbol that resembles a smiling face. MSM generally interceptss all control characters that are sent to the console.

A special escape sequence supports users who require these characters. The following format is used for this escape sequence:

ESC ) C Pn

In this sequence, Pn is a number between 0 and 31. When this sequence is sent to the console, the symbol corresponding to $CHAR(Pn) is displayed.

For example, the following sequence displays a heart symbol:

WRITE *27,")C",*3

Refer to Microsoft's DOS documentation for information on symbols that correspond to the control characters.


ANSI Escape Sequence Examples

The following examples illustrate some of the ANSI control sequences that are supported by MSM. Sample M code illustrates the escape sequences, and the result of the escape sequence is described.

ANSI Escape Sequence Examples

Escape Sequence	M Code	Mnemonic	Result
ESC [ Pt ; Pb r	W *27,"[1;24r"	W /MSMRGN(1,24)	Sets 24-line scrolling region.
ESC [ Pa ; ... ; Pa m	W *27,"[0m"	W /SGR(0)	Turns off attributes.
ESC [ Pa ; ... ; Pa m	W *27,"[31;42m"	W /SGR(31,42)	Sets red foreground and green background.
ESC [ Pn A	W *27,"[4A"	W /CUU(4)	Moves cursor up four lines.
ESC [ Pl ; Pc H	W *27,"[14;8H"	W /CUP(14,8)	Moves cursor to row 14, column 8.


Reports

When the console receives a report sequence, it returns a response. The following table lists examples of report sequences.

Report Sequence Examples

Description	Name	Escape Sequence
Requests cursor location     Returned report: Cursor location in line Pl, column Pc	CPR	CSI 6 n CSI Pl ; Pc R
Request emulation     Returned report: VT100, user-defined keys	DA	CSI c CSI ? 6 1 ; 8 c


VT Keyboard Escape Processing

When escape processing is enabled in VT-keyboard mode, use the function keys on the PC console to terminate READ commands. A value that identifies the selected key is stored in the $ZB special variable. In application mode (DECKPAM), the numeric keypad acts only as a group of function keys.

PC Function Keys

VT Keyboard	PC Key	$ZB\256 ($ZB#256=27)
NumKeyPad 0	NumKeyPad 0	0
NumKeypad 1	NumKeyPad 1	1
NumKeyPad 2	NumKeyPad 2	2
NumKeyPad 3	NumKeyPad 3	3
NumKeyPad 4	NumKeyPad 4	4
NumKeyPad 5	NumKeyPad 5	5
NumKeyPad 6	NumKeyPad 6	6
NumKeyPad 7	NumKeyPad 7	7
NumKeyPad 8	NumKeyPad 8	8
NumKeyPad 9	NumKeyPad 9	9
↑	↑	17
↓	↓	18
→	→	19
←	←	20
Find	HOME	21
Insert Here	INS	22
Remove	DEL	23
Select	END	24
Prev Screen	PGUP	25
Next Screen	PGDN	26
NumKeyPad ENTER	↵	29
PF1*	Num Lock	32
PF2*	NumKeyPad /	33
PF3*	NumKeyPad *	34
PF4*	NumKeyPad -	35
F1*	F1	31
F2*	F2	32
F3*	F3	33
F4*	F4	34
F5*	F5	35
F6	F6	37
F7	F7	38
F8	F8	39
F9	F9	40
F10	F10	41
F11	F11	43
F12	F12	44
F13	ALT + F3	45
F14	ALT + F4	46
Help	ALT + F5	48
Do	ALT + F6	49
F17	ALT + F7	51
F18	ALT + F8	52
F19	ALT + F9	53
F20	ALT + F10	54
NumKeyPad ,	NumKeyPad +	60
NumKeyPad -	ALT + NumKeyPad -	61
NumKeyPad .	NumKeyPad .	62
*Sequences  PF1-PF4 overlap sequences F1-F5 for escape processing. F1-F5 are correct for VT4xx, and PF1-PF4 are provided for backward compatibility. Refer to "Console Window Devices" in this documentation for additional information.


MSM-PC/PLUS Compatibility

The following tables list display and keyboard emulation features that are implemented in MSM-PC/PLUS, but are not implemented in MSM-Workstation.

Display Emulation Features

Name	Description	Escape Sequence
HTS	Sets a horizontal tab stop at the current column.	ESC H
TBC	Tab clear:     At cursor position     Clears all tabs	CSI g CSI 3 g
DECSED	Selective erase in display:      Cursor to end of display      Beginning through cursor      Complete display	CSI ? Ps J CSI ? 0 J or CSI ? J CSI ? 1 J CSI ? 2 J
DECSEL	Erases in line:      Cursor to end of line      Beginning through cursor      Complete line	CSI ? PS K CSI ? 0 K or CSI ? K CSI ? 1 K CSI ? 2 K
DECCARA	Changes attributes in rectangular area.	CSI Pt ; Ps ; Pb ; Pr ; Pa;…;Pa $ r
DECRARA	Reverses attributes in rectangular area.	CSI Pt ; Ps ; Pb ; Pr ; Pa;…;Pa $ t
DECCRA	Copies area.	CSI Pt ; Ps ; Pb ; Pr ; ; Pt ; Ps $ v
DECFRA	Fills area.	CSI Pch ; Pt ; Ps ; Pb ; Pr $ x
DECERA	Erases area.	CSI Pt ; Ps ; Pb ; Pr $ z
LNM	Turns on automatic linefeed on return (inserts line feed after carriage return).	CSI 2 0 h
LNM	Turns off automatic linefeed on return (does not insert line feed after carriage return).	CSI 2 0 l
Description	Name	Escape Sequence
Requests Device Status Report Returned reports:     No malfunction	DSR	CSI 5 n CSI 0 n
Keyboard Emulation Features

Description	Name	Escape Sequence
Selects character-protection attribute:     Not protected     Protected	DECSCA	CSI 0 " q CSI 1 " q


Startup switches

If executables are started from the command-line, the following parameters can be added to control the configuration.

Parameter	Purpose
+BUFFERS nn	Specifies the disk cache size (in number of blocks).
+CHUIDEBUG	Allows running a debug executeable with the CHUI debugger (not GUI).
+NODEBUG	Allows running a debug-build of an executable in non-debug mode.
+PARTSIZE nn	Specifies the partition size (in kilobytes).
+REBIND	Allows respecifying the network database mounted by a client at startup.
+STACKSIZE nn	Specifies the stack size (in kilobytes).
+STAPSIZE nn	Specifies the stap size (in kilobytes).


System Limits and Settings

The following table lists system limits and default settings for MSM-Workstation.

Description	Setting
BIJ maximum generation time	4 seconds
Default buffer pool size	1024 1K buffers
Default partition size	256K
Default STAK	64K
Default STAP	64K
DKRES size	10% of the database size or 200 blocks, whichever is smaller
Local variable default size	32K
Local variable maximum size	32K
Maximum database size	16 GB
Maximum partition size	16 MB


This section contains various reference information relating to the MSM-GUI layer underlying MSM-Workstation.


Modules

Properties	Events

Modules are used to group their members in order to produce a hierarchy which can be used in structural decomposition.   Members may be sources, routines, globals, windows, host files and other modules.

Members are not contained within their respective modules. Rather, they are components of the module, but can be opened and manipulated in their own right. A member can be a component of many modules, or of none.

Application modules are a special case in that they may be used to create Windows executables.

Module names are restricted to 20 characters. They are case sensitive, allow only alphabetic or numeric characters and must start with an initial alphabetic character.

Host file components act as references to files held in the Windows file system. Being a component of a module allows the host file to be opened within the Workstation editor. This feature is only useful if the file's contents are text. Host file components play no part in the Make-EXE process.


Application	CompNameRtn	CompPrefixGbl	CompPrefixRtn
CompTrace	PrincipalModule


CommonCode	Enter	Error	Exit


Windows

Properties	Events	See also

A GUI window is a window that runs in graphical mode on the PC console.  Window names are restricted to 20 characters. They are case sensitive, allow only alphabetic or numeric characters and must start with an initial alphabetic character.

Normal GUI windows are used to build Single-Document Interface (SDI) applications, modal dialog boxes, and non-modal windows.  Multiple-Document Interface (MDI) windows are also supported.

See Also:

Window Event Notes

Window Sizing

MDI Parent Windows

MDI Child Windows


Window Event Notes

If a %%Do or %%DoWin macro occuring during event-processing finds that the window has already been created (for example, by an %%OpenWin) but is not APPLICATION-modal it will first delete the window, causing a Destroy event. The window will then be re-created APPLICATION-modal. If the existing window is already APPLICATION-modal then the create-phase of %%Do or %%DoWin is skipped, in the same way as happens when a window is re-invoked after previously having been exited with a %%Return or %%Cancel on which the hide-parameter was set.

Action logic executed during window Exit or Destroy should not execute a %%Return or %%Cancel macro.

Avoid executing a %%SetFocus in the course of window creation. There should be no %%SetFocus in window Create, or in the control Creates that occur during window Create, or in any CommonCode called during this. When a window is called with %%Do or %%DoWin, focus is automatically placed onto the window, and if possible onto the control indicated by the window's NextControl property.


Window Sizing

There are two sets of properties that control the size of a window. SizeWidth and SizeHeight (together with SizeUnits) form the MWAPI window attribute SIZE. WinWidth and WinHeight (together with WinUnits) form the MWAPI window attribute SIZEWIN. The MWAPI standard states that if both attributes are present it is not defined which takes precedence.

While a window is being designed, Workstation attempts to keep the two sets of properties synchronised. A change to a property in one set, using the Property Bar, applies the change and then updates the other set. Resizing the window using the mouse updates both sets. The size information shown on the right of the Property Bar is WinWidth and WinHeight.

The Win* set give the full window size, including border, menu bar and title bar. The Size* set give the viewport size, the dimensions of the visible region of the application area on which controls are placed. Where viewport scrolling is permitted by the Scrollbars property and required (i.e. controls placed so that they fall outside the viewport when the viewport is positioned at the origin of the application area) then Size* includes the area(s) used by the scrollbar(s).


Active	AlwaysOnTop	BackColor	CancelButton	Color
CompNameRtn	CompPrefixGbl	CompPrefixRtn	CompTrace	DefaultButton
DevMode	Display	FontBold	FontFace	FontItalic
FontSize	FontUline	ForeColor	GridHeight	GridOn
GridSnap	GridUnits	GridWidth	HelpID	Hwnd
Icon	IconTitle	Maximized	MenuBar	Message
MinButton	MinHeight	Minimized	MinUnits	MinWidth
Modal	MVersion	NextControl	Parent	Pointer
PosJustifyH	PosJustifyV	PosLeft	PosRecall	PosTop
PosUnits	PrincipalModule	Resizable	ScrollBars	SizeHeight
SizeRecall	SizeUnits	SizeWidth	TBackColor	TForeColor
Tied	Title	Type	Units	Visible
WinHeight	WinUnits	WinWidth


Create	Destroy	Enter	Error	Exit
char	click	close	dblClick	gotFocus
help	keyDown	keyUp	lostFocus	maximize
minimize	move	ptrDown	ptrDrag	ptrMove
ptrUp	resize	restore


Macros for Windows


MDI Parent Windows

Properties	Events	See also

Multiple-Document Interface (MDI) parents are windows which serve as containers for MDI child windows. A typical MDI application has a single MDI parent window.

The menubar and descendant menus defined on the MDI Parent only appear when no MDI children are active. Otherwise, the menubar which appears on the MDI Parent is the one defined by the currently active MDI Child. When a menu event arises from user selection from this child window's menu structure, %%EvWindow will report the event occurring for the parent's window but %%CurrWin will report that the action logic belongs to the child window.


Active	AlwaysOnTop	AreaColor	BackColor	Color
CompNameRtn	CompPrefixGbl	CompPrefixRtn	CompTrace	DevMode
Display	FontBold	FontFace	FontItalic	FontSize
FontUline	ForeColor	GridHeight	GridOn	GridSnap
GridUnits	GridWidth	HelpID	Hwnd	Icon
IconTitle	Maximized	MenuBar	Message	MinButton
MinHeight	Minimized	MinUnits	MinWidth	Modal
MVersion	Pointer	PosJustifyH	PosJustifyV	PosLeft
PosRecall	PosTop	PosUnits	PrincipalModule	Resizable
SizeHeight	SizeRecall	SizeUnits	SizeWidth	TBackColor
TForeColor	Title	Type	Units	Visible
WinHeight	WinUnits	WinWidth


Create	Destroy	Enter	Error	Exit
char	click	close	dblClick	gotFocus
help	keyDown	keyUp	lostFocus	maximize
minimize	move	ptrDown	ptrDrag	ptrMove
ptrUp	resize	restore


Macros for MDI	Macros for Windows


MDI Child Windows

Properties	Events	See also

Multiple-Document Interface (MDI) child windows are displayed within an MDI parent window. They are generally presented at runtime using the %%OpenWin macro, where a suffix is used to produce multiple instances.

An MDI Child window's Parent property must identify an MDI Parent window. If no Parent property is set, the first open MDI Parent will be selected when the child is opened at run-time. The menubar and descendant menus defined on the MDI Parent only appear when no MDI children are active. Otherwise, the menubar which appears on the MDI Parent is the one defined by the currently active MDI Child. When a menu event arises from user selection from this child window's menu structure, %%EvWindow will report the event occurring for the parent's window but %%CurrWin will report that the action logic belongs to the child window.


Active	BackColor	CancelButton	Color	CompNameRtn
CompPrefixGbl	CompPrefixRtn	CompTrace	DefaultButton	DevMode
FontBold	FontFace	FontItalic	FontSize	FontUline
ForeColor	GridHeight	GridOn	GridSnap	GridUnits
GridWidth	HelpID	Hwnd	Icon	IconTitle
Maximized	MenuBar	Message	MinButton	MinHeight
Minimized	MinUnits	MinWidth	Modal	MVersion
NextControl	Parent	Pointer	PosJustifyH	PosJustifyV
PosLeft	PosRecall	PosTop	PosUnits	PrincipalModule
Resizable	ScrollBars	SizeHeight	SizeRecall	SizeUnits
SizeWidth	TBackColor	TForeColor	Title	Type
Units	Visible	WinHeight	WinUnits	WinWidth


Create	Destroy	Enter	Error	Exit
char	click	close	dblClick	gotFocus
help	keyDown	keyUp	lostFocus	maximize
minimize	move	ptrDown	ptrDrag	ptrMove
ptrUp	resize	restore


Macros for MDI	Macros for Windows


Menus

Properties 	Events	See also

Menus are used to provide groups of commands that may be accessed from the main menubar or as popup menus.

See Also:

Menu Choices


Active	PosLeft	PosTop	PosUnits	Units
Visible


select


Macros for Menus


Menu Choices

Properties 	Events	See also

Menu Choices are commands that are accessed directly, or identify groups of commands.


Accelerator	Active	AppId	Marker	MarkerOn
Message	Separator	Submenu	Title


select


Macros for Menus


Toolbars

Properties

Toolbars are button groups that make frequently used commands more accessible. They appear along a window edge, commonly the top edge beneath a menubar if one is present.

See Also:

Toolbar Choices


BarSite	BarSize	ButtonHeight	ButtonWidth	Picture
PictureHeight	PictureWidth	Visible


Toolbar Choices

Properties 	Events

Toolbar Choices specify the buttons that appear on a toolbar.


Accelerator	Active	AppId	PictureIndex	SepWidth
Style	ToolTip	Value


deselect	select


About Controls

A control is an object that can be placed on a window. It has a set of properties and events that it triggers. Controls can be used to get user input; display output, static text, graphics; control data etc. Some controls are interactive (responsive to user actions) while others are static (accessible only using code). Some controls have no run time representation and are only visible at design time.

Properties of controls are typically manipulated using macros such as %%Set, %%Get and %%Prop.  If a macro parameter does not specify the property to be manipulated, the Default Property of the control is used.


Controls A-Z

ActiveX Controls

Button Control

Checkbox Control

Combo Box Control

Date Control

Document Control

Drop-down Combo Control

Drop-down List Control

Generic Control

Group Box Control

Label Control

List Box Control

List Choice

Long List Control

Picture Control

Radio Button Control

Scroll Bar Control

Spin Button Control

SQL Data Control

Tabbed Group Control

Text Box Control

Timer Control


ActiveX Controls

Properties	Events

MSM-Workstation is able to use many of the ActiveX controls that are available. Such controls are typically developed by software companies, and are designed to fulfill certain needs. For example, one control might present data in a tabular format. Another might display HTML files. A third might have no visual representation but serve instead as an interface to networking protocols.

Virtually all ActiveX controls are designed to operate within Microsoft's Visual Basic development environment. However, so long as they conform to the published ActiveX control standards and do not rely on Visual Basic private interfaces, they stand a good chance of working within MSM-Workstation.

Within Workstation an ActiveX control's set of properties divides into two categories:

•	Common properties. These properties are available on all ActiveX controls. They appear on the Property Bar list at design-time.

•	Control-specific properties. The names and functions of these properties are established by the developer of the control. Many of them will appear on the Property Bar list at design-time. Some will be accessible at design-time only through the control's property sheet, which appears when Element/Definition or an equivalent command is used. Control documentation will give details of them. Note however that some control documentation does not differentiate well between true control-specific properies and Visual Basic's extended control properties. The latter will not be present when the control is used in MSM-Workstation. Their role is replaced by the common properties, though these cannot be accessed using object-notation but via the normal %%Set, %%Get and %%Prop macros.

A similar distinction arises for events. As well as the low-level and high-level events similar to those applicable to other control types, a third set of custom events typically exists. Consult the ActiveX control's documentation for details of these events. The %%Ev macro provides access to event-specific parameters.


Active	Cancel	Container	HelpID	Hwnd
Message	Name	NextControl	PosLeft	PosTop
PosUnits	SizeHeight	SizeUnits	SizeWidth	Type
Units	Visible


Create	Destroy	Enter	Exit	gotFocus
help	lostFocus


Button Control

Properties	Events

A Button control is a rectangular button with associated text.  It is normally used to generate an event. When selected, the button appears to depress and is said to be "pushed".  It then returns to its normal unpressed appearance.

A default button can be selected by pressing Enter if the window's DefaultButton property is set appropriately.   A cancel button can be specified by setting the window's CancelButton property. It is then selected using the ESC key.

This control has a Type property value equal to BUTTON and is equivalent to the MWAPI BUTTON gadget.


Active	CanContain	Cancel	Container	HelpID
Hwnd	Message	Name	NextControl	Picture
Pointer	PosLeft	PosTop	PosUnits	SizeHeight
SizeUnits	SizeWidth	TFontBold	TFontFace	TFontItalic
TFontSize	TFontUline	Title	Type	Units
Visible


Create	Destroy	Enter	Exit	Push
gotFocus	help	lostFocus	select


Checkbox Control

Properties	Events

A CheckBox is a control that consists of a label and a square box with which the user can indicate if something is true or false. The box contains an X when the value is True, otherwise it is empty.

Check boxes can be used in groups to display multiple choices from which the user can select zero or more options.  If a single choice from a group of options is desired, use a Radio Button.

This control has a Type property value equal to CHECK and is equivalent to the MWAPI CHECK gadget.


Active	BackColor	Cancel	Changed	Container
DataField	DisplayOnly	ForeColor	HelpID	Hwnd
Message	Name	NextControl	Pointer	PosLeft
PosTop	PosUnits	SizeHeight	SizeUnits	SizeWidth
TFontBold	TFontFace	TFontItalic	TFontSize	TFontUline
Title	Type	Units	Value	VarName
VarPermanent	Visible


Check	Create	Destroy	Enter	Exit
change	deselect	gotFocus	help	lostFocus
select


Combo Box Control

Properties	Events

A Combo Box is a control that combines a text entry box and a list box.

An item selected from the list is displayed in the text box and may be modified if required; or text may be entered directly into the text box. The resulting value need not be present in the list area.

Simple text editing facilities are present.  Text in the text box can be scrolled horizontally, and scrolling mechanisms are provided for the list area if needed.

Manipulating the choices presented by a Combo Box is typically done using Macros for Choices.

This control has a Type property value equal to LISTENTRY and is equivalent to the MWAPI LISTENTRY gadget.


Active	BackColor	Cancel	Changed	ChoiceField
ChoiceVar	Container	DataField	DisplayOnly	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	MaxLength	Message	Name
NextControl	Pointer	PosLeft	PosTop	PosUnits
SelStartLength	SelText	SizeHeight	SizeUnits	SizeWidth
TBackColor	TFontBold	TFontFace	TFontItalic	TFontSize
TFontUline	TForeColor	TabStops	Title	TitlePos
TopRow	Type	Units	Value	VarName
VarPermanent	Visible


Create	Destroy	Enter	Exit	Modified
change	char	dblClick	deselect	gotFocus
help	keyDown	keyUp	lostFocus	select


Date Control

Properties	Events

A Date control enables the user to view, enter, and modify a single date.

The date control has internal validation allowing only valid dates to be entered. Spin buttons are used to increment or decrement each of the three fields (day, month, year).  Keyboard arrow keys may be used as an alternative, and the day and year components may be edited directly.

This control has a Type property value equal to ZDATE and is an MSM-specific extension to MWAPI standard.

For more sophisticated date-entry facilities, consider using an ActiveX control.


Active	BackColor	Cancel	Changed	Container
DataField	DateFormat	DisplayOnly	FontBold	FontFace
FontItalic	FontSize	FontUline	ForeColor	HelpID
Hwnd	Message	MonthFormat	Name	NextControl
Pointer	PosLeft	PosTop	PosUnits	SizeHeight
SizeUnits	SizeWidth	TBackColor	TFontBold	TFontFace
TFontItalic	TFontSize	TFontUline	TForeColor	Title
TitlePos	Type	Units	Value	VarName
VarPermanent	Visible


Create	Destroy	Enter	Exit	Modified
change	gotFocus	help	lostFocus	select


Document Control

Properties	Events

A Document control enables the entry, display and modification of one or more lines of text.

Simple text editing capabilities are provided by Windows, including the standard cut, copy, paste and undo keys. If there is too much text for display in the size specified for the control, horizontal and vertical scrolling mechanisms can be specified using property settings established at design-time.

Maximum capacity of the control is 32K characters. For larger documents, use a suitable ActiveX control.

This control has a Type property value equal to DOCUMENT and is equivalent to the MWAPI DOCUMENT gadget.


Active	BackColor	Border	Cancel	Changed
Container	DataField	DisplayOnly	FontBold	FontFace
FontItalic	FontSize	FontUline	ForeColor	HelpID
Hwnd	MaxLength	Message	Name	NextControl
Pointer	PosLeft	PosTop	PosUnits	ScrollHeight
ScrollHorz	ScrollUnits	ScrollVert	ScrollWidth	SelStartLength
SelText	SizeHeight	SizeUnits	SizeWidth	TBackColor
TFontBold	TFontFace	TFontItalic	TFontSize	TFontUline
TForeColor	TabStops	Title	TitlePos	Type
Units	Value	VarName	VarPermanent	Visible


Create	Destroy	Enter	Exit	Modified
change	char	gotFocus	help	keyDown
keyUp	lostFocus


Drop-down Combo Control

Properties	Events

A Drop-down Combo is a control that combines a text box and a drop-down list.  It provides the editing properties of the Combo Box with the space-saving properties of the Drop-down List.

The list is normally invisible, but when the button is pushed, it becomes visible.  An item selected from the list is displayed in the text box and may be modified if required; or text may be entered directly into the text box. The resulting value need not be present in the list area.

Simple text editing facilities are present.  Text in the text box can be scrolled horizontally, and scrolling mechanisms are provided for the list area if needed.

Manipulating the choices presented by a Drop-down Combo is typically done using Macros for Choices.

To set the depth of the dropped-down list at design-time, use the list's button to toggle between expanded and contracted states.

This control has a Type property value equal to ZLISTCOMBO and is an MSM specific extension to MWAPI.


Active	BackColor	Cancel	Changed	ChoiceField
ChoiceVar	Container	DataField	DisplayOnly	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	MaxLength	Message	Name
NextControl	Pointer	PosLeft	PosTop	PosUnits
SelStartLength	SelText	SizeHeight	SizeUnits	SizeWidth
TBackColor	TFontBold	TFontFace	TFontItalic	TFontSize
TFontUline	TForeColor	TabStops	Title	TitlePos
Type	Units	Value	VarName	VarPermanent
Visible


Create	Destroy	Enter	Exit	Modified
change	char	deselect	gotFocus	help
keyDown	keyUp	lostFocus	select


Drop-down List Control

Properties	Events

A Drop-down List is a box and an associated button.  When the button is pushed, a list box appears with more items.  When an item from the list is selected, the list box disappears, leaving the selected item in the remaining box.

Manipulating the choices presented by a Drop-down List is typically done using Macros for Choices.

To set the depth of the dropped-down list at design-time, use the list's button to toggle between expanded and contracted states.

This control has a Type property value equal to LISTBUTTON and is equivalent to the MWAPI LISTBUTTON gadget.


Active	BackColor	Cancel	Changed	ChoiceField
ChoiceVar	Container	DataField	DisplayOnly	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	Message	Name	NextControl
Pointer	PosLeft	PosTop	PosUnits	SizeHeight
SizeUnits	SizeWidth	TBackColor	TFontBold	TFontFace
TFontItalic	TFontSize	TFontUline	TForeColor	TabStops
Title	TitlePos	Type	Units	Value
VarName	VarPermanent	Visible


Choose	Create	Destroy	Enter	Exit
change	deselect	gotFocus	help	lostFocus
select


Generic Control

Properties	Events

A Generic is a control in which an application can draw graphics, text and geometrical figures, using draw commands.

This control has a Type property value equal to GENERIC and is equivalent to the MWAPI GENERIC gadget.

See Also:

Drawing

Scrollable Drawings

Drawing to a File

Draw Commands


Drawing

A drawing on an MWAPI GENERIC gadget is composed of a series of draw commands. The drawing produced is the result of applying each draw command in turn, using the sequence implied by the draw command numbers.

Commands that draw lines and figures, such as LINE, use the current foreground color and pen-size for the line itself, and use the current background color, mode, and fill-pattern settings when applicable.

In Workstation action logic, prepare a series of draw commands in a local array, or a global, and apply them using %%MergeCtl. For example:

NEW d,ctl

SET d(1)="BCOLOR,32768,32768,65535,OPAQUE"

SET d(2)="FCOLOR,0,0,0"

SET d(3)="PENSIZE,1"

SET d(4.1)="FFACE,MS Sans Serif"

SET d(4.2)="FSIZE,12"

SET d(4.3)="FSTYLE,ITALIC"

SET d(5)="UNITS,REL"

SET d(10)="OVAL,0,25,100,75"

SET d(20)="FILLPAT,DCROSSHATCH"

SET d(20.1)="PENSIZE,2"

SET d(21)="PIE,50,50,30,315,225"

SET d(40)="UNITS,CHAR"

SET d(40.1)="BCOLOR,65535,65535,65535,TRANSPARENT"

SET d(40.2)="FCOLOR,65535,0,0"

SET d(41)="DRAWTEXT,1,1,A Title, With comma"

M ctl("DRAW")=d

; Clear existing drawing

%%Reset(genPlot.DRAW)

; Apply new drawing

%%MergeCtl(genPlot,ctl)

The draw command sequence numbers need not be consecutive integers. If existing draw commands are not cleared before new ones are applied, the result is as if the two combined sets of commands had been applied to a pre-cleared control.


Scrollable Drawings

An MSM specific attribute ZVIEWPORT allows the drawing produced by the DRAW commands to be panned around the control. It takes a comma-separated pair of integer values representing the pixel offset to be applied to the drawing origin when determining where the top left corner of the control lies over the drawing. By placing suitable action logic onto a pair of Scroll Bar controls placed adjacent to the edges of the Generic control, this attribute can be manipulated by the user.


Drawing to a File

An MSM specific extension to the DRAWTYPE attribute of the underlying MWAPI gadget allows draw commands to result in a bitmap file.

The DRAWTYPE attribute can be set at control creation time to:

"ZBITMAP,"_filename

If this is done, no visible representation of the control appears in the window. Instead, the drawing will be placed in the named BMP-format file.

Continuing the previous example:

; Remove existing file-creation control

%%KillCtl(genFile)

S ctl("TYPE")="GENERIC"

S ctl("POS")="0,0",ctl("SIZE")=%%Prop(genPlot.SIZE)

S ctl("DRAWTYPE")="ZBITMAP,"_filename

; Create the control and write the file

%%MergeCtl(genFile,ctl)


Draw Commands

The following table defines the available draw commands. See Notes below for units of measure.

Draw Commands

Command	Domain	Description
ARC	hpos,vpos,radius, startangle,endangle	Draw part or all of a circle. Its center is at hpos,vpos; its radius is radius; the arc is drawn between startangle and endangle.
BCOLOR	color,fillmode	Set background color for subsequent draw commands. See note 1.
BITMAP	hpos,vpos, extresource	Display the bitmap specified by extresource, with its origin at hpos,vpos using the current palette. See also PICTURE.
BOX	hpos1,vpos1,hpos2,vpos2	Draw a rectangle. See note 2.
DMODE	"SOLID" "XOR"	Determine whether certain subsequent draw commands overlay a pixel's previous contents or blend with it. The default is "SOLID. See note 3.
DRAWTEXT	hpos,vpos,string	Draw the characters in string, using the current foreground color and font. hpos,vpos sets the position of the upper left hand corner of the string. If BCOLOR has set fillmode OPAQUE, background color is used around characters.
FCOLOR	color	Set foreground color for subsequent draw commands.
FFACE	fface	Set font face for subsequent DRAWTEXT commands. See note 4.
FILLPAT	pattern	Set fill pattern. See note 5.
FSIZE	fsize	Set font size for subsequent DRAWTEXT commands. See note 4.
FSTYLE	fstyle	Set font style for subsequent DRAWTEXT commands. See note 4.
LINE	hpos1,vpos1,hpos2,vpos2	Draw a line from hpos1,vpos1 up to, but not including, hpos2,vpos2.
OVAL	hpos1,vpos1,hpos2,vpos2	Draw an ellipse. See note 6.
PENSIZE	pensize	Set pen diameter in pixels.  See note 8.
PICTURE	hpos,vpos, extresource	Display the bitmap specified by extresource, with its origin at hpos,vpos manipulating the current palette to suit the bitmap. See also BITMAP.
PIE	hpos,vpos,radius, startangle,endangle	Draw an ARC with lines joining the center to the ends of the arc. Its center is at hpos,vpos; its radius is radius; the arc drawn lies between startangle and endangle. The enclosed region is filled using the current fill-pattern.
POINT	hpos,vpos	Draw a point using current pen-size.
UNITS	units	Specify the units of positioning and sizing in subsequent commands. See note 1.
Notes for draw commands:

1.	Units of measure

Except for angles, the position and size measurements used for drawings are by default in the units set in the generic box's UNITS attribute. The UNITS draw command allows this to be altered within the drawing.

When the unit is REL, the basis is the size of the generic box at creation. When the unit is CHAR, the basis font varies as the font is altered by the FFACE, FSIZE, and FSTYLE commands.

Angles are always measured in degrees, counter-clockwise from the positive horizontal axis.

2.	BCOLOR

fillmode is OPAQUE or TRANSPARENT. If OPAQUE, existing elements of the drawing cannot be seen through the background. If TRANSPARENT, they can.

Prior to the first BCOLOR command, the background color is that of the gadget's BCOLOR attribute, and the fill mode is TRANSPARENT.

3.	BOX

BOX draws a rectangle. hpos1,vpos1 and hpos2,vpos2 specify two diagonally opposite corners of the rectangle. The rectangle is filled using the current FILLPAT settings.

4.	DMODE

DMODE determines the effect of color changes on pixels in the drawing area.

SOLID changes the pixels to the current FCOLOR or BCOLOR, as appropriate.

XOR does an exclusive-or on the value of each element (red, green, and blue) of the color, producing a blend.

5.	FFACE, FSIZE, FSTYLE

Unlike the process of setting these as gadget, window or display attributes, the selection of a matching font on the platform only takes place when that font is needed. For example, this may be the first DRAWTEXT command after the FFACE, FSIZE, and FSTYLE commands, or the first use of a CHAR-unit position or size. Retrieving the commands from the "DRAW" subscripts always returns the value specified, not the value obtained by platform font-matching.

Prior to the first occurrence of each of these commands, the corresponding font-parameter is obtained from that attribute of the generic box.

6.	FILLPAT

FILLPAT sets the fill pattern for subsequent OVAL, BOX, and PIE commands to one of the following patterns. The pattern uses the current foreground color (FCOLOR) for its lines. If fillmode (see BCOLOR) is OPAQUE, the rest of the filled region is painted with the current background color (BCOLOR). Colors are applied according to the current mode (DMODE). Prior to any FILLPAT command, the behavior is as if set to NONE.

Fill Patterns

Value	Description
BDIAGONAL	Lines from lower right to upper left.
CROSSHATCH	Vertical and horizontal lines.
DCROSSHATCH	BDIAGONAL plus FDIAGONAL.
FDIAGONAL	Lines from lower left to upper right.
HORIZONTAL	Horizontal lines.
NONE	No filling occurs.
SOLID	Solid filling.
VERTICAL	Vertical lines.
7.	OVAL

OVAL draws an ellipse inside an invisible rectangle. hpos1,vpos1 and hpos2,vpos2 specify two diagonally opposite corners of the rectangle. The oval is filled using the current FILLPAT settings.

8.	PENSIZE

PENSIZE sets the pen diameter in pixels for subsequent commands. For ARC, POINT, and LINE, the parameters of those commands specify the locus of the pen's center. For BOX, OVAL, and PIE, the parameters dictate the locus of the pen's outermost edge.


Active	BackColor	Border	CanContain	Cancel
Container	DrawType	FontBold	FontFace	FontItalic
FontSize	FontUline	ForeColor	HelpID	Hwnd
Message	Name	NextControl	Pointer	PosLeft
PosTop	PosUnits	SizeHeight	SizeUnits	SizeWidth
Type	Units	Visible


Create	Destroy	Enter	Exit	char
click	dblClick	gotFocus	help	keyDown
keyUp	lostFocus	ptrDown	ptrDrag	ptrMove
ptrUp


Group Box Control

Properties	Events

A Group Box control provides a rectangular outline that can be used to group other controls visually in order to provide a graphical or functional grouping.  It also operates as a container, allowing controls placed within it at design-time to be moved as a group when window layout is being altered.

A Group Box can also be used to provide a horizontal or vertical line. It cannot receive the focus.

This control has a Type property value equal to FRAME and is equivalent to the MWAPI FRAME gadget.


BackColor	Container	ForeColor	Hwnd	Message
Name	NextControl	Pointer	PosLeft	PosTop
PosUnits	SizeHeight	SizeUnits	SizeWidth	TFontBold
TFontFace	TFontItalic	TFontSize	TFontUline	Title
Type	Units	Visible


Create	Destroy


Label Control

Properties	Events

A Label is a control used to specify static text.

A label control cannot get focus and events do not occur for it. It is used to specify text that you do not want the user to change, such as a caption under a graphic.

This control has a Type property value equal to LABEL and is equivalent to the MWAPI LABEL gadget.


AutoSize	BackColor	Border	Container	ForeColor
Hwnd	Name	NextControl	Pointer	PosLeft
PosTop	PosUnits	SizeHeight	SizeUnits	SizeWidth
TFontBold	TFontFace	TFontItalic	TFontSize	TFontUline
Title	Type	Units	Visible


Create	Destroy


List Box Control

Properties	Events

A List Box control displays a list of items and allows selection of one or more, depending on property settings.

If the list is too long for the control size specified, scroll bars are provided to enable navigation of the list.

Manipulating the choices presented by a List Box, and the selections made by the user, is typically done using Macros for Choices.

This control has a Type property value equal to LIST and is equivalent to the MWAPI LIST gadget.


Active	BackColor	Cancel	Changed	ChoiceField
ChoiceVar	Container	DataField	DisplayOnly	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	MaxSelect	Message	Name
NextControl	Pointer	PosLeft	PosTop	PosUnits
SizeHeight	SizeUnits	SizeWidth	TBackColor	TFontBold
TFontFace	TFontItalic	TFontSize	TFontUline	TForeColor
TabStops	Title	TitlePos	TopRow	Type
Units	Value	VarName	VarPermanent	Visible


Choose	Create	Destroy	Enter	Exit
change	dblClick	deselect	gotFocus	help
lostFocus	select


List Choice

Properties

List choices specify the contents of controls of the list types and radio buttons.  They are typically manipulated using Macros for Choices.  Choices can also be individually enabled and disabled using the %%Enable macro.


Active	AppId	Title


Long List Control

Properties	Events

A Long List is a control that provides facilities to manage many list items  (choices), such as the display of an M global.

The Long List has extra event types to help the scrolling and displaying of items in the list.  The application controls navigation through the list by means of these events.  The events may be generated by pressing the keyboard keys Home, End, PgUp, PgDn, Up or Down, or by clicking the six navigation buttons.  This provides for navigating to the top or bottom of the list, or scrolling up and down by pages or by lines.  If the control's height is insufficient, the navigation buttons disappear in pairs, outermost first.

This control has a Type property value equal to LONGLIST and is equivalent to the MWAPI LONGLIST gadget.

See Also:

Automatic Long List Management


Automatic Long List Management

If a Long List control's choices are defined using the choice editor, or are declared as being contained in a variable (which can include subscripts, and is generally though not always a global), then the compiler automatically supplies logic for the six list-scrolling events. Any low-level event action logic supplied by the developer is invoked after the compiler logic has altered the visible list. This is followed by any high-level Scroll logic. If no alteration took place (e.g. the user attempts to scroll upwards from the first entry) then neither the low-level nor high-level event action logic is executed.

Automatic long list management is not available where the choices are sourced from a data dictionary field.

Where the developer supplies the long-list choices in a global or local variable the structure is as follows. Suppose the control's ChoiceVar property is set to ^MYLIST("Books"). Then the value (if any) at this subscript is used as an indication of the number of items in the list. The more accurate this is, the more accurate the behaviour of the scroll-indicator on the control. If no value is supplied, or an inaccurate one is there, the scroll-indicator range self-adjusts on the basis of what it finds as the user scrolls. This can lead to the user thinking that they are nearly at the end, then seeing the scrollbar thumb suddenly jump towards the middle of its range.

 The descendants of ^MYLIST("Books") one subscript lower hold the choices. The subscript is the choice, and the data is the value displayed. For example ^MYLIST("Books",1)="Genesis", ^(2)="Exodus". If any such choice has descendent subscripts ACTIVE and/or AID these are loaded as the corresponding MWAPI attributes.

Maintenance of a user selection during scrolling of an automatically-managed Long List requires a variable to be associated with the control by means of the VarName property.


Active	BackColor	Cancel	Changed	ChoiceField
ChoiceVar	Container	DataField	DisplayOnly	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	MaxSelect	Message	Name
NextControl	Pointer	PosLeft	PosTop	PosUnits
ScrollMax	ScrollMin	ScrollPosition	SizeHeight	SizeUnits
SizeWidth	TBackColor	TFontBold	TFontFace	TFontItalic
TFontSize	TFontUline	TForeColor	TabStops	Title
TitlePos	TopRow	Type	Units	Value
VarName	VarPermanent	Visible


Choose	Create	Destroy	Enter	Exit
Scroll	change	dblClick	deselect	goBottom
goDown	goDownBig	goTop	goUp	goUpBig
gotFocus	help	lostFocus	select


Picture Control

Properties	Events

A Picture is a control that allows display of an image such as an icon or a bitmap.

Several built-in images are available, such as warning and information icons. Picture controls cannot get focus and events do not occur for them.

This control has a Type property value equal to SYMBOL and is equivalent to the MWAPI SYMBOL gadget.


CanContain	Container	Hwnd	Name	NextControl
Picture	Pointer	PosLeft	PosTop	PosUnits
SizeHeight	SizeUnits	SizeWidth	Type	Units
Visible


Create	Destroy


Radio Button Control

Properties	Events

A Radio Button control consists of a set of two or more round buttons (choices), of which only one can be selected at any time. Unlike some other GUI development tools, MSM-Workstation treats a set of radio buttons as a single control.

Selecting an item causes automatic deselection of the previously selected item. Usually radio buttons are used to display multiple choices from which a user can select only one.  If multiple selections from a group of choices are desired, a group of Checkbox controls should be used.

The arrangement of the choices is controlled by the RowCol, RowColSize, and FillDirection properties.  All columns are the same width, and the buttons with their choice texts are left-aligned, with a small margin.  All rows are the same height, and the buttons with their choice texts are vertically centered within the rows.

Run-time manipulation of the choices presented by a Radio Button is typically performed using Macros for Choices.

This control has a Type property value equal to RADIO and is equivalent to the MWAPI RADIO gadget.


Active	BackColor	Border	Cancel	Changed
Container	DataField	DisplayOnly	FillDirection	FontBold
FontFace	FontItalic	FontSize	FontUline	ForeColor
HelpID	Hwnd	Message	Name	NextControl
Pointer	PosLeft	PosTop	PosUnits	RowCol
RowColSize	SizeHeight	SizeUnits	SizeWidth	TBackColor
TFontBold	TFontFace	TFontItalic	TFontSize	TFontUline
TForeColor	Title	TitlePos	Type	Units
Value	VarName	VarPermanent	Visible


Create	Destroy	Enter	Exit	Push
change	deselect	gotFocus	help	lostFocus
select


Scroll Bar Control

Properties	Events

The Scroll Bar control allows the visual representation of a numeric value on a scroll bar using a position indicator called a thumb.

The user can modify the value by moving the position indicator (dragging the thumb). A Scroll control does not directly cause anything to scroll, but applications may use them to do so.  A scroll control can be either horizontally or vertically oriented.

This control has a Type property value equal to SCROLL and is equivalent to the MWAPI SCROLL gadget.


Active	BackColor	Changed	Container	DataField
DisplayOnly	ForeColor	HelpID	Hwnd	Message
Name	NextControl	Pointer	PosLeft	PosTop
PosUnits	ScrollDir	ScrollLarge	ScrollMax	ScrollMin
ScrollSmall	SizeHeight	SizeUnits	SizeWidth	TBackColor
TFontBold	TFontFace	TFontItalic	TFontSize	TFontUline
TForeColor	Title	TitlePos	Type	Units
Value	VarName	VarPermanent	Visible


Create	Destroy	Scroll	help	ptrDrag
select


Spin Button Control

Properties	Events

A Spin Button control enables the user to enter, modify or view a numeric value within a specified range.

Spin buttons are used to increment or decrement the number by a specified step size. Keyboard arrow keys may be used as an alternative, and the value may be edited directly.  Simple text editing is provided.

This control has a Type property value equal to ZDATE and is an MSM specific extension to MWAPI.


Active	BackColor	Cancel	Changed	Container
DataField	DisplayOnly	FontBold	FontFace	FontItalic
FontSize	FontUline	ForeColor	HelpID	Hwnd
Max	Message	Min	Name	NextControl
Pointer	PosLeft	PosTop	PosUnits	SizeHeight
SizeUnits	SizeWidth	SpinStep	TBackColor	TFontBold
TFontFace	TFontItalic	TFontSize	TFontUline	TForeColor
Title	TitlePos	Type	Units	Value
VarName	VarPermanent	Visible
 Visible Property


Create	Destroy	Enter	Exit	Modified
change	gotFocus	help	lostFocus	select


SQL Data Control

Properties	Events

The SQL Data control provides an MSM specific link to the MSM-SQL data dictionary.

At design time, the control is linked to a schema and table in the data dictionary and enables suitable controls within the same window to be linked to individual columns. The data control only has a visual representation at design time. This control has a Type property value equal to Data and has no MWAPI equivalent. It is manipulated at run time by causing events using the %%Perform macro in the action logic of other objects.

See Also:

Data Control Usage

Binding

Run-time


Data Control Usage

The data control allows you to link (bind) certain other types of MSM-Workstation control (so-called data-aware controls) to a database via the MSM-SQL product, Version 3 or later. You can have up to 26 data controls per window. Each data control allows selection (using the DataFilter property) and sorting (using the DataSort property) of a set of rows from a single MSM-SQL table, index or view (hereafter referred to as table). It allows data-aware controls to bind to any column (also known as a field) on that table, or to any column that can be reached from that table by means of MSM-SQL foreign key links, or to an SQL expression formed from one or more such columns.

The Data Control only has a visual representation at design-time. Its PosLeft, PosTop and PosUnits define where on the window that representation appears. These properties have no meaning at run-time.

The RecordSource property specifies which table in which schema the data control operates on. It is of the form schema.table and is set using the Data Control Definition dialog.

The optional DataFilter property can take an SQL WHERE-clause, but may only operate on columns that are either in the table specified in the RecordSource or are foreign-key-linked to it. You cannot use the DataFilter property to join tables. If necessary, define a view that performs the join, and then use that view in the RecordSource of your data control. The property may be set from the Property Bar or from the Data Control Definition dialog.

The optional DataSort property can take an SQL ORDER BY-clause. It may only operate on the columns made accessible by the RecordSource or foreign-key links. The property may be set from the Property Bar or from the Data Control Definition dialog.

The ReadOnly property may be set if the data control is not to permit updates to the columns it manages. In some cases, given the nature of the table that is used as a RecordSource, MSM-SQL may be unable to support updates and the ReadOnly property will be preset to Yes. Otherwise the property may be set from from the Data Control Definition dialog.

The DataDistinct property can be set if duplicates are to be avoided. It has the effect of adding the DISTINCT keyword to the generated SQL SELECT clause.

The Message property may be used to provide the application user with information about progress when the data control first accesses the database.

The Changed property of the data control is the only one that can be accessed at run-time by action logic. It is set true when the value of a bound control is changed by user interaction or by the %%SetVar macro, and affects whether the Move-events cause record update.


Binding

Binding the value of a data-aware control to a field made available by a data control is performed by setting the binding control's DataField property. The DataField property is of the format datacontrol.field or datacontrol.foreignkey@field or datacontrol.foreignkey1@foreignkey2@...foreignkeyN@field. This can be set using the Property Bar, or using the Field textbox on the control's definition window, or using a dialog accessed by the Field button on the control's definition window. That dialog also permits a new data control to be defined. Note that the final component of the reference may also be an SQL expression such as field1|CHR(9)|field2 but in this case updates to the bound control will not be applied to the database.

All binding occurs at compile-time. If the data control is not set ReadOnly compilation will attempt to provide for updates of all fields bound to controls, unless the bound control is defined DisplayOnly. MSM-SQL cannot support updates to all fields - primary keys for example - so it may be necessary to set the DisplayOnly property on certain bound controls. The Create logic for the control can clear the property at run-time and so allow the user to alter the control's value, though the changes will not be applied to the database.

In the case of list-type controls (excluding the Long List) the list choices can also be bound to a data control field. The ChoiceField property achieves this. It is only settable using the control definition window; on the Property Bar it may be viewed but not altered. The Create event for the data control loads the list control's choices with the values found for the field; the choice is the record number (1 to n) and the text displayed on the list is the value found in the field. The Message property of the data control can be used to report the progress of the load. Loading of such choice-bound lists occurs before any action logic supplied for the data control's Create event is executed. Whether the Create action logic for the list being loaded is executed before the load or after the load depends on whether the name of the list control collates before or after the name of the data control.


Run-time

A data control has no low-level events, since it has no visual representation with which the user can interact. Data control events occur under program control by use of the %%Perform macro. For example, a window containing a data control and some bound data-aware controls might also contain a Button control titled Next. The Push event of this control would be given action logic that executed a %%Perform of the MoveNext action on the data control.

In order to access the database at run-time a data control requires a connection. Unless a connection has been opened using the %%SqlConnect macro, the first window requiring a connection attempts to log in to MSM-SQL using the username DEFAULT and password DEFAULT. The Workstation application's current UCI must contain an MSM-SQL installation on which the username and password are valid for login. Note however that apart from the initial login, all SQL privilege checks are performed at compile-time, using the SQL user identity set by the developer in Tools/SQL Settings.

If an SQL operation performed by a data control gives rise to an SQL error, a <ZESQL> error will occur with information in the local array SQLDIAG. The first opportunity to handle such an error is in the Error action logic for the data control. If that action logic does not exist or signals %%NotOK before exit an Error event occurs for the window.


Changed	Connection	Container	DataDistinct	DataFilter
DataSort	Name	PosLeft	PosTop	PosUnits
ReadOnly	RecordSource	Type


AddNew	Create	DeleteRecord	Destroy	Error
MoveFirst	MoveLast	MoveNext	MovePrevious	MoveTo
UpdateControls	UpdateRecord	Validate


Tabbed Group Control

Properties	Events

A Tabbed Group control allows multiple sets of controls to occupy the same region of a window, each set on a separate tabbed page. The user chooses the desired page and interacts with the controls upon it.


Active	Cancel	Container	HelpID	Hwnd
Message	Name	NextControl	Page	PosLeft
PosTop	PosUnits	SizeHeight	SizeUnits	SizeWidth
Type	Units	Visible


Create	Destroy	Enter	Exit
gotFocus	help	lostFocus


Text Box Control

Properties	Events

A Text Box control permits the entry, display and modification of a single line of text.

Simple text editing capabilities are provided by Windows, including the standard cut, copy, paste and undo keys. If the text is longer than the box, the text can be scrolled horizontally.

This control has a Type property value equal to TEXT and is equivalent to the MWAPI TEXT gadget.


Active	BackColor	Border	Cancel	Changed
Container	DataField	DisplayOnly	FontBold	FontFace
FontItalic	FontSize	FontUline	ForeColor	HelpID
Hwnd	MaxLength	Message	Name	NextControl
PasswordChar	Pointer	PosLeft	PosTop	PosUnits
SelStartLength	SelText	SizeHeight	SizeUnits	SizeWidth
TBackColor	TFontBold	TFontFace	TFontItalic	TFontSize
TFontUline	TForeColor	Title	TitlePos	Type
Units	Value	VarName	VarPermanent	Visible


Create	Destroy	Enter	Exit	Modified
change	char	gotFocus	help	keyDown
keyUp	lostFocus


Timer Control

Properties	Events

A Timer control generates an event after the expiration of a specified time interval.  It has no visible run-time representation.

Starting a Timer

A timer will start as soon as all of the following are true:

•	The timer's Active property is True.

•	The Active property of the timer's parent window is True.

•	All ancestors of the timer's parent window have an Active property with a value of True.

Canceling a Timer

If any one of the following occurs before the expiration of the specified Interval then the timer is canceled:

•	The timer is destroyed.

•	The timer's Active property is set to False.

•	The timer's parent window, or one of that window's ancestors has its Active property set to False.

Restarting a Timer

If, before the expiration of the specified interval, a timer attribute is assigned a value or is killed, and the result does not cancel the timer, then the timer restarts without causing an event.

Additionally, a timer is implicitly restarted on completion of the action logic processing caused by an event for that timer, so long as the timer has not been canceled during that action logic processing.


Active	Container	Interval	Name	PosLeft
PosTop	PosUnits	Type


Create	Destroy	timer


About Properties and Attributes

A property is a name for some aspect of a window, intrinsic control, menu, toolbar, or other object in MSM-Workstation.  The names of properties are mixed-case, e.g. SizeHeight, and case-sensitive.  The values of properties may be viewed and set in the Workstation environment using the Property Bar, and in code using %%Set, %%Get, and %%Prop macros.

The term attribute is not synonymous.  This term is used to refer to some aspect of an MWAPI control.  The names of attributes are all upper case, e.g. SIZE.  The values of attributes can usually be viewed and set by specifying attribute names rather than property names within %%Set, %%Get and %%Prop. Occasionally the MWAPI structured system variables may need to be addressed directly, but this is discouraged unless no suitable macros exist.

The use of case to distinguish MSM-Workstation names from MWAPI names is extended to the naming of events as well, for instance keyDown vs. KEYDOWN.

There is generally a simple mapping between MSM-Workstation names and MWAPI names.

Note that the properties of ActiveX controls also used a mixed-case naming convention, but are frequently manipulated using object dot-notation syntax rather than %% macros. These names are not case-sensitive, so when used in %% macros they can be specified entirely lowercase if there are conflicts with standard Workstation property names.

Data types are used to keep the definition of the property values brief. These shorthand terms can be reduced to string and integer definitions.  Each property, as well as values passed to and returned from %% macros, has a data type.

See Also:

Default Properties

Y-Attributes


Default Properties

When the property of an object is not specified, for instance when used as a macro argument, the default property used depends on the object type as follows.

Object Type	Default Property
ActiveX	Visible
Button	Title
Checkbox	Value
Combo Box	Value
Date	Value
Document	Value
Drop-down Combo	Value
Drop-down List	Value
Generic	Title
Group Box	Title
Label	Title
List Box	Value
Long List	Value
Menu Bar	Visible
Menu Choice	Title
Picture	Picture
Radio Button	Value
Scroll Bar	Value
Spin Button	Value
SQL Data	None
Tabbed Group	Visible
Text Box	Value
Timer	Active
Toolbar	Visible
Toolbar Button	Value
Window	Title


Y-Attributes

Any object (window, control, choice, menus) can be given application-specific attributes that begin with Y so long as the name forms a legal M subscript.

Y-attribute names must be all uppercase if they are to work with %% macros -- they'll work with %%Set, %%Get and %%Prop – because this distinguishes them from Workstation properties. Using direct MWAPI access (which is not encouraged), mixed case Y-attribute names are allowed, so long as the initial Y is uppercase.

Y-attributes can be a convenient way of attaching application-specific information to graphical interface objects, especially when multiple instances of an object may occur. They are stored in memory as true attributes of the (MWAPI) object with which they are associated, and are destroyed when the object is. However, a Y-attribute cannot have a descendent subscript structure. The #%Declare macro provide a more flexible alternative way to obtain instance-specific window-private storage in local variables.


Properties A-Z

Accelerator Property

Active Property

AlwaysOnTop Property

Appld Property

Application Property

AreaColor Property

AutoSize Property

BackColor Property

BarSite Property

BarSize Property

Border Property

ButtonHeight Property

ButtonWidth Property

Cancel Property

CancelButton Property

CanContain Property

Changed Property

ChoiceField Property

ChoiceVar Property

Color Property

CompNameRtn Property

CompPrefixGbl Property

CompPrefixRtn Property

CompTrace Property

Connection Property

Container Property

DataDistinct Property

DataField Property

DataFilter Property

DataSort Property

DateFormat Property

DefaultButton Property

DevMode Property

Display Property

DisplayOnly Property

DrawType Property

Enable Property

FillDirection Property

FilterIn Property

FontBold Property

FontFace Property

FontItalic Property

FontSize Property

FontUline Property

ForeColor Property

GridHeight Property

GridOn Property

GridSnap Property

GridUnits Property

GridWidth Property

HelpID Property

Hwnd Property

Icon Property

IconTitle Property

Interval Property

Marker Property

MarkerOn Property

Max Property

Maximized Property

MaxLength Property

MaxSelect Property

MenuBar Property

Message Property

Min Property

MinButton Property

MinHeight Property

Minimized Property

MinUnits Property

MinWidth Property

Modal Property

MonthFormat Property

MVersion Property

Name Property

NextControl Property

Page Property

Parent Property

PasswordChar Property

Picture Property

PictureHeight Property

PictureIndex Property

PictureWidth Property

Pointer Property

PosJustifyH Property

PosJustifyV Property

PosLeft Property

PosRecall Property

PosTop Property

PosUnits Property

PrincipalModule Property

ReadOnly Property

RecordSource Property

Resizable Property

RowCol Property

RowColSize Property

ScrollBars Property

ScrollDir Property

ScrollHeight Property

ScrollHorz Property

ScrollLarge Property

ScrollMax Property

ScrollMin Property

ScrollPosition Property

ScrollSmall Property

ScrollUnits Property

ScrollVert Property

ScrollWidth Property

SelStartLength Property

SelText Property

Separator Property

SepWidth Property

SizeHeight Property

SizeRecall Property

SizeUnits Property

SizeWidth Property

SpinStep Property

Style Property

Submenu Property

TabStops Property

TBackColor Property

TFontBold Property

TFontFace Property

TFontItalic Property

TFontSize Property

TFontUline Property

TForeColor Property

Tied Property

Title Property

TitlePos Property

ToolTip Property

TopRow Property

Type Property

Units Property

Value Property

VarName Property

VarPermanent Property

Visible Property

WinHeight Property

WinUnits Property

WinWidth Property


Accelerator Property

Applies to

The Accelerator property is a keycode value that specifies a key combination which can be used to select a menu choice without having to use the menu structure.

This property is equivalent to the MWAPI ACCELERATOR attribute.


Menu Choice	Toolbar Choice


Active Property

Applies to

The Active property is a truefalse value that specifies the state of an object. Just as an object can be visible or invisible, it can also be active or inactive (grayed-out). If the object's Active property is set true, the item is active and is ready to receive focus if appropriate.

This property is equivalent to the MWAPI ACTIVE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	List Choice	Long List
MDI Child	MDI Parent	Menu	Menu Choice
Radio Button	Scroll Bar	Spin Button	Tabbed Group
Text Box	Timer	Toolbar Choice	Window


AlwaysOnTop Property

Applies to

The AlwaysOnTop property is a truefalse value that specifies the state of the "always on top" flag on a window. This flag controls the appearance of the window in the z-order. If set to true the window will appear in front of all other windows on the display, unless they also have the "always on top" flag set. This window will remain at the front of the z-order until you turn this flag off or kill the window.

This property should be used with care. Setting it to true generally forces your window in front of the windows of other applications, obstructing the user.


MDI Parent	Window


Appld Property

Applies to

The Appld property is a string value that serves as an "application identifier" for use by the application programmer.

This property is equivalent to the MWAPI AID attribute

When used with menu choices, it is recommended that you do not begin a value with @ or include the period (.) in it, as these may interfere with your use of certain menu-related macros.


List Choice	Menu Choice	Toolbar Choice


Application Property

Applies to

The Application property is a truefalse truefalsevalue that specifies whether or not a module is capable of generating a standalone Workstation application.


Module


AreaColor Property

Applies to

The AreaColor property is a colorvalue that specifies the color of the viewport of a parent window in the context of a Multiple Document Interface (MDI) environment.


MDI Parent


AutoSize Property

Applies to

The AutoSize property is a truefalse value that specifies whether or not a control's size is to be automatically computed at design-time. For example, if this property is set on a Label control its size will alter as other properties such as Title or TFontSize are changed.


Label


BackColor Property

Applies to

The BackColor property is a colorvalue that specifies the background color of a control. For a window BackColor is used to specify the default background color for controls placed on the window. Colors can be chosen using the color palette or by explicitly entering the value.

This property is equivalent to the MWAPI BCOLOR attribute.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	Generic	Group Box
Label	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Text Box	Window


BarSite Property

Applies to

The BarSite property determines whether a toolbar is located at the TOP, BOTTOM, LEFT or RIGHT edge of its window. It cannot be changed at run-time.


Toolbar


BarSize Property

Applies to

The BarSize property sets the height of a horizontal toolbar, or the width of a vertical one.


Toolbar


Border Property

Applies to

The Border property is truefalse value that is set to Yes to display a frame at the perimeter of a control.

This property is equivalent to the MWAPI FRAMED attribute.


Document	Generic	Label	Radio Button
Text Box


ButtonHeight Property

Applies to

The ButtonHeight property sets the height in pixels of all the buttons on a toolbar.


Toolbar


ButtonWidth Property

Applies to

The ButtonWidth property sets the width in pixels of all the buttons on a toolbar.


Toolbar


Cancel Property

Applies to

The Cancel property is a truefalse value. Setting it true on a control causes suppression of any low-level change events that might otherwise occur when the user moves focus to the control. It is commonly set on a button control used to cancel a dialog without processing any changes.

This property is equivalent to the MWAPI CANCEL attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	Radio Button
Spin Button	Tabbed Group	Text Box


CancelButton Property

Applies to

The CancelButton property specifies the controlname of the cancel button. Setting this property to the name of a button control causes that button to be pushed when the <ESC> key is pressed.

The value must be the name of a component that is a button in the current window.

This property is equivalent to the MSM specific ZCANCELBUTTON attribute.


MDI Child	Window


CanContain Property

Applies to

The CanContain property is a truefalse property used at design-time to indicate that a control is able to have other controls placed on top of it. Those contained controls will move in step with the container at design-time. At run-time, when the container is hidden or disabled the components will be similarly affected.


Button	Generic	Group Box	Picture


Changed Property

Applies to

The Changed property is a truefalse value that is set true whenever the user causes the Value property of a control to change. It indicates that the changed event should occur instead of the lostFocus, when the user leaves the control. It is automatically becomes false on exit from the control if the VarName property has been specified.

This property is equivalent to the MWAPI CHANGED attribute


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	SQL Data
Text Box


ChoiceField Property

Applies to

When a control's choices are loaded by a Data Control, the ChoiceField property holds the datafield reference to be used. The data control must be defined on the current window.


Combo Box	Drop-down Combo	Drop-down List	List Box
Long List


ChoiceVar Property

Applies to

Where a control's choices are loaded from a local or global variable, the ChoiceVar property holds the reference. This may include subscripts, and these may include variables in their expressions so long as they can be evaluated at the time of the control's Create event and before any user-supplied Create action logic has been executed.


Combo Box	Drop-down Combo	Drop-down List	List Box
Long List


Color Property

Applies to

The Color property is a colorvalue used to specify the window application area color. Colors can be chosen using the color palette or by explicitly entering the value.

This property is equivalent to the MWAPI COLOR attribute


MDI Child	MDI Parent	Window


CompNameRtn Property

Applies to

The CompNameRtn property overrides the effect of the CompPrefixRtn property and defines the name used by the compiler when creating the run-time routines for a window or module. The generated routines are named by adding suffixes to this name: g* for GUI, m* for module, s* for SQL.

The value of this property must meet the syntax of a name (possibly starting with a percent sign), and may not exceed 6 characters. In addition, names that start with the characters Vi, %Vi or SQL are prohibited.


MDI Child	MDI Parent	Window	Module


CompPrefixGbl Property

Applies to

The CompPrefixGbl property defines the prefix used by the compiler when creating the run-time global structures for a window or module. It is established when the object is first defined using the New File dialog, loading from the default property sets in the normal way (these can be changed using the Window Defaults dialog). If no default is specified it is set to XXX.

The value of this property must meet the syntax of a name (possibly starting with a percent sign), and may not exceed 5 characters. In addition, names must be uppercase only, and names that start with the characters %MDS, %BLD  or BLD are prohibited.


MDI Child	MDI Parent	Window	Module


CompPrefixRtn Property

Applies to

The CompPrefixRtn property defines the prefix used by the compiler when creating the run-time routines for a window or module. It is established when the object is first defined using the New File dialog, loading from the default property sets in the normal way (these can be changed using the Window Defaults dialog). If no default is specified it is set to XXX.

The value of this property must meet the syntax of a name (possibly starting with a percent sign), and must have a length of exactly 3 characters. In addition, names that start with the characters Vi, %Vi or SQL are prohibited.


MDI Child	MDI Parent	Window	Module


CompTrace Property

Applies to

The CompTrace property is a truefalse value that indicates whether a window or module is to be compiled with additional trace logic for use during testing. Setting this true yields additional output on the Test Progress report but increases routine size.


MDI Child	MDI Parent	Window	Module


Connection Property

Applies to

The Connection property is an alphanumeric value that specifies the name of the MSM-SQL connection to be used. See the %%SqlConnect macro for more information.


SQL Data


Container Property

Applies to

The Container property identifies the container (typically a Group Box or Tabbed Group) onto which the control was placed at design-time. In the case of a Tabbed Group container, the tab number is appended after a #.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	Picture	Radio Button	Scroll Bar
Spin Button	SQL Data	Tabbed Group	Text Box
Timer


DataDistinct Property

Applies to

The DataDistinct property is a truefalse value that specifies whether or not all data records must be distinct. In the case of a Data Control accessing an SQL database it corresponds to the DISTINCT keyword on the SELECT clause in SQL.


SQL Data


DataField Property

Applies to

The DataField property of a data-aware control binds the control to a Data Control by specifying the datafield reference. The data control must be defined on the current window.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	Text Box


DataFilter Property

Applies to

The DataFilter property is a string that specifies the filter criteria to be used on data access. In the case of a Data Control accessing an SQL database it corresponds to a WHERE clause in SQL.


SQL Data


DataSort Property

Applies to

The DataSort property is a string that specifies the sort criteria to be used on data access. In the case of a Data Control accessing an SQL database it corresponds to a ORDER BY clause in SQL.


SQL Data


DateFormat Property

Applies to

The DateFormat property is a dateformat value used to specify the format in which a date will be displayed in a Date control.

This property is equivalent to the MSM specific ZDATEFORMAT attribute.


Date


DefaultButton Property

Applies to

The DefaultButton property is a controlname that specifies the default button. Setting this property to the name of a button control allows that button to be navigated to and pushed when the <RETURN> key is pressed.

The value must be the name of a component that is a button in the current window.

This property is equivalent to the MWAPI DEFBUTTON attribute


MDI Child	Window


DevMode Property

Applies to

The DevMode property specifies the window development mode.  Its read-only value is always "GUI".


MDI Child	MDI Parent	Window


Display Property

Applies to

The Display property specifies the displayname on which the window is to appear. Since MSM-Workstation supports a single display, the property is read-only.

This property is equivalent to the MWAPI DISPLAY attribute


MDI Parent	Window


DisplayOnly Property

Applies to

The DisplayOnly property is a truefalse value that is set true to stop user actions from being able to change the Value property of a control.

This property is equivalent to the MWAPI CANCHANGE attribute


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	Text Box


DrawType Property

Applies to

The DrawType property specifies the type of draw commands allowed on a Generic control. Only one value, MDRAW, is currently settable at design-time. Another value, ZBITMAP, can be set on controls created at run-time using %%MergeCtl. See the Generic Control section for more information.

This property is equivalent to the MWAPI DRAWTYPE attribute.


Generic


Enable Property

The Enable property is a truefalse value that specifies whether an event is enabled.  It applies to all events.

For a low-level event, this property is equivalent to the MWAPI ENABLE attribute

For a high-level event, this property governs whether or not the action logic for the event is executed. Additionally, in the case of the Create and Destroy events for controls, if this property is false at compile-time the corresponding event is not included in the chain arising from the window Create event.


FillDirection Property

Applies to

The FillDirection property specifies whether rows or columns are filled first for a Radio Button set.

Possible values are "H" = Horizontal and "V" = Vertical

This property is derived from the MWAPI ROWCOL attribute.


Radio Button


FilterIn Property

Applies to

The FilterIn property specifies a list of keys or mouse-buttons to generate key or pointer events for and is applicable to these events. It is set using the Filter option from the popup menu on the event within the Window Browser tree.

This property is equivalent to the MWAPI FILTERIN attribute.


char	keyDown	keyUp


FontBold Property

Applies to

The FontBold property is a truefalse value that specifies whether or not value-text should be bold.

This property corresponds to the presence or absence of BOLD in the MWAPI FONTSTYLE attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	Generic	List Box	Long List
MDI Child	MDI Parent	Radio Button	Spin Button
Text Box	Window


FontFace Property

Applies to

The FontFace property is a fontface value that specifies the font face used for text in the data area of controls.

This property is equivalent to the MWAPI FFACE attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	Generic	List Box	Long List
MDI Child	MDI Parent	Radio Button	Spin Button
Text Box	Window


FontItalic Property

Applies to

The FontItalic property is a truefalse value that specifies whether or not value-text should be italicized.

This property corresponds to the presence or absence of ITALIC in the MWAPI FONTSTYLE attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	Generic	List Box	Long List
MDI Child	MDI Parent	Radio Button	Spin Button
Text Box	Window


FontSize Property

Applies to

The FontSize property is a fontsize value that specifies the point-size for value-text.

This property corresponds to the MWAPI FONTSIZE attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	Generic	List Box	Long List
MDI Child	MDI Parent	Radio Button	Spin Button
Text Box	Window


FontUline Property

Applies to

The FontUline property is a truefalse value that specifies whether or not value-text should be underlined.

This property corresponds to the presence or absence of ULINE in the MWAPI FONTSTYLE attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	Generic	List Box	Long List
MDI Child	MDI Parent	Radio Button	Spin Button
Text Box	Window


ForeColor Property

Applies to

The ForeColor property is a colorvalue that specifies the foreground color of a control. For a window ForeColor is used to specify the default foreground color for controls placed on the window. Colors can be chosen using the color palette or by explicitly entering the value.

This property is equivalent to the MWAPI FCOLOR attribute.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	Generic	Group Box
Label	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Text Box	Window


GridHeight Property

Applies to

The GridHeight property is a positive number that specifies the height of grid used on a window at design-time, in the units of measurement specified by GridUnits. It is manipulated using the Grid Options dialog and is not accessible from the Property Bar.


MDI Child	MDI Parent	Window


GridOn Property

Applies to

The GridOn property is a truefalse value that specifies whether or not to display a grid on a window at design-time. It is manipulated using the Grid Options dialog and is not accessible from the Property Bar.


MDI Child	MDI Parent	Window


GridSnap Property

Applies to

The GridSnap property is a truefalse value that specifies whether or not moved and resized controls should snap to a window's grid at design-time. It is manipulated using the Grid Options dialog and is not accessible from the Property Bar.


MDI Child	MDI Parent	Window


GridUnits Property

Applies to

The GridUnits property specifies the unittype of measurement for the GridHeight and GridWidth properties. It is manipulated using the Grid Options dialog and is not accessible from the Property Bar.

Possible values are:
"CHAR" = Character
"PIXEL" = Pixel
"POINT" = Point
"REL" = Relative or
"ZDLG" = Dialog Units


MDI Child	MDI Parent	Window


GridWidth Property

Applies to

The GridWidth property is a positive numeric value that specifies the width of grid used on a window at design-time, in the units of measurement specified by GridUnits. It is manipulated using the Grid Options dialog and is not accessible from the Property Bar.


MDI Child	MDI Parent	Window


HelpID Property

Applies to

The HelpID property is a positive integer that specifies the "help context identifier". This identifier applies to Microsoft Help structures, and is defined in the "[MAP]" section of the xxx.HPJ file of a help project structure.

The actual help-information is displayed by executing an "external call" to

&MWAPI.WinHelp(FileName,Command,Data).

Special meanings are assigned if the value of the property HelpID is negative or zero, as follows:

If a HelpID property is defined at design-time and no Action Logic is given for the Help event, then that window or control will respond to a runtime help request by submitting the HelpID as the Data parameter in the call to &MWAPI.WinHelp.

The Command parameter depends on the value of the HelpID, as follows:

Data value	Command submitted
negative	ContextPopup
zero	Contents
positive	Context
The FileName parameter is the name of the Help file.  It is sought first in the registry as entry FileName in section %Help, using

$$VALUE^%mprof("%Help","FileName")

Unless the path is absolute it is taken as relative to the installation directory, found using $$APPEXE^%msc.

If no name is found in the registry, the fallback helpfile name is derived by taking the application name and path, using $$APPEXE^%msc, and switching the extension to .HLP.

A HelpID property may be defined on a window or control, including ActiveX controls.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Tabbed Group	Text Box	Window


Hwnd Property

Applies to

The Microsoft Windows operating environment identifies each window and control in an application by assigning it a handle, or Hwnd. The Hwnd property returns this value. It is used with Windows API calls. Many Windows operating environment functions require the Hwnd of the active window as an argument.

Note: Use of this property is at your own risk and is not supported. If you make Windows system calls using the Hwnd of an MSM-Workstation window or control we can not guarentee the result will be what you would expect. MSM-Workstation assumes it has complete control of the controls so if your program makes changes to them without calling a Workstation function it may believe they are in one state when they are in fact in another. This could result in MSM-Workstation crashing.

Because the value of this property can change while a program is running, never store the Hwnd value in a variable.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	Tabbed Group
Text Box	Window


Icon Property

Applies to

The Icon property is an externalresource that specifies the icon to display if a window is iconified.

This property is equivalent to the MWAPI ICON attribute.


MDI Child	MDI Parent	Window


IconTitle Property

Applies to

The Icon property is a string that specifies the title text to appear with the icon when a window is iconified.

This property is equivalent to the MWAPI ITITLE attribute.

Usage with MDI windows:

A window uses property IconTitle when it's minimized, and Title when it's maximized or restored. Under the MDI environment, IconTitle is also used under the Windows menu when listing existing child windows. At window creation time, IconTitle defaults to Title. Therefore, if Title is reset at run time, the IconTitle must also be reset to re-establish the default.  For example this may be done with:

%%Set(Title,"("_New Title_")")

%%Reset(IconTitle)


MDI Child	MDI Parent	Window


Interval Property

Applies to

The Interval property is a positive numeric value that specifies the time, in seconds, that a timer runs following initiation before generating a timer event. It can be fractional.

This property is equivalent to the MWAPI INTERVAL.


Timer


Marker Property

Applies to

The Marker property is a markervalue that specifies a marker (Check, Bullet, Diamond or a custom file or resource) to place next to a menu entry.

This property is equivalent to the MWAPI MARKER attribute.


Menu Choice


MarkerOn Property

Applies to

The MarkerOn property is a truefalse value that specifies whether a menu item is to have its marker set when initially created.


Menu Choice


Max Property

Applies to

The Max property is an integer that specifies the maximum value enterable in a Spin control.

This property is equivalent to the second piece of the SCROLLRANGE attribute on this MSM specific gadget.


Spin Button


Maximized Property

Applies to

The Maximized property is a truefalse value that is true if a window is currently maximized.


MDI Child	MDI Parent	Window


MaxLength Property

Applies to

The MaxLength property is a positive integer that specifies the maximum number of characters which the text value of a control can have as a result of user entry or modification of text.

This property is equivalent to the MWAPI CHARMAX attribute.


Combo Box	Document	Drop-down Combo	Text Box


MaxSelect Property

Applies to

The MaxSelect property is an integer that specifies the maximum number of choices of a control that can be concurrently selected.

A value of 0 (zero) indicates that no limit is imposed.

This property is equivalent to the MWAPI SELECTMAX attribute.


List Box	Long List


MenuBar Property

Applies to

The MenuBar property is a menuname that specifies the name of the window menu structure. This property is automatically set when the Menu Editor dialog is used to define a menu structure and cannot be altered using the Property Bar.

This property is equivalent to the MWAPI MENUBAR attribute.


MDI Child	MDI Parent	Window


Message Property

Applies to

This property is a string to be displayed in the status bar of a window.

If at design time you set the Message property for a window or for any control on it, a simple status bar will be added to the window.

This property is equivalent to the MSM specific ZMESSAGE attribute.

The Message property of a SQL Data control has a special purpose. It is displayed during the Create event.  If the message contains a # character this is replaced with the number of the record being loaded. When the database is first queried the record number will be 0. A data control that is referred to by the ChoiceField property of another control will then step through all records during creation. If a positive integer is placed immediately following the # in the message then this indicates after how many records the status message is to be refreshed. Otherwise the message is refreshed after each record. If a # character is required in the message before the position at which the record number is to appear, use ##.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu Choice
Radio Button	Scroll Bar	Spin Button	SQL Data
Tabbed Group	Text Box	Window


Min Property

Applies to

The Min property is an integer that specifies the minimum value enterable in a Spin control.

This property is equivalent to the first piece of the SCROLLRANGE attribute on this MSM specific gadget.


Spin Button


MinButton Property

Applies to

The MinButton property is a truefalse value that specifies whether a window will contain a button on the window frame to enable the user to iconify the window.

This property is equivalent to the MWAPI ICONIFY attribute.


MDI Child	MDI Parent	Window


MinHeight Property

Applies to

The MinHeight property is is a positive numeric value used to specify the minimum height to which a user can resize a window. The units used depend on the setting of the MinUnits property.

This property is derived from the MWAPI SIZEMIN attribute.


MDI Child	MDI Parent	Window


Minimized Property

Applies to

The Minimized property is a truefalse value that is true if a window is in the iconic state.

This property is equivalent to the MWAPI MIN attribute.


MDI Child	MDI Parent	Window


MinUnits Property

Applies to

The MinUnits property is a unittype value used to specify the units used for the MinHeight and MinWidth properties of a window.

This property is derived from the MWAPI SIZEMIN attribute.


MDI Child	MDI Parent	Window


MinWidth Property

Applies to

The MinWidth property is a positive numeric value used to specify the minimum width to which a user can resize a window. The units used depend on the setting of the MinUnits property.

This property is derived from the MWAPI SIZEMIN attribute.


MDI Child	MDI Parent	Window


Modal Property

Applies to

The Modal property specifies the modal state of a window.

Possible values:

"ANCESTORS"
"APPLICATION"
"PARENT"

When a modal window is visible, other windows may be disabled. A Modal value equal to PARENT indicates that the modal window disables only its parent window. A Modal value equal to ANCESTORS indicates that the modal window disables all of its ancestor windows. A Modal value equal to APPLICATION indicates that the modal window disables all active MSM-Workstation windows except itself.

When the value of this property is non-empty, access to certain windows is restricted while the window with this property has focus.

This property is equivalent to the MWAPI MODAL attribute.


MDI Parent	Window


MonthFormat Property

Applies to

The MonthFormat property is a string that specifies the formatting used by the Date control.

The format is a string consisting of 12 substrings, separated by the character "#", where each substring represents the name of one month in the year.  Abbreviations for the names of the months are created by taking the first three letters of the names of the months.

It is equivalent to the ZMONTHS attribute.

Examples

Set abr="jan#feb#mrt#apr#mei#jun#jul#aug#sep#okt#nov#dec"

%%Set(MonthFormat,abr)

would load the definitions of the Dutch appreviations of the names of the months.

Set full="januari#februari#maart#april#mei#juni"#juli#augustus#september#oktober#november#december"

%%Set(MonthFormat,full)

would load the defintions of the full Dutch names of the months.


Date


MVersion Property

Applies to

The MVersion property specifies what version of M a window is targetted for.

Possible values are:
"MSM"
"X11"

A window with the property set to X11 does not have access to MSM-specific enhancements. This particularly affects the availability of MSM extensions to MWAPI when creating windows.


MDI Child	MDI Parent	Window


Name Property

Applies to

The Name property is an identifier that records the name of an object. It may be altered using the Name field on the definition windows, but care should be exercised since macros in action logic may subsequently refer to incorrect or absent objects.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	Picture	Radio Button	Scroll Bar
Spin Button	SQL Data	Tabbed Group	Text Box
Timer


NextControl Property

Applies to

The NextControl property is a controlname that specifies the name of the next control to get focus when the <TAB> key is pressed. For a window it specifies the first control to get focus when the window is created and focussed on without focussing on a specific control in the window. If the control named cannot get focus (if it is a Label for example) then the control specified in that control's NextControl property is given focus, and so on.

This property is equivalent to the MWAPI NEXTG attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	Picture	Radio Button
Scroll Bar	Spin Button	Tabbed Group	Text Box
Window


Page Property

Applies to

The Page property is a positive integer that specifies the current tab of a Tabbed Group control.


Tabbed Group


Parent Property

Applies to

The Parent property is a windowname that specifies the name of the parent of a window.

This property is equivalent to the MWAPI PARENT attribute.


MDI Child	Window


PasswordChar Property

Applies to

The PasswordChar property specifies the single character to be displayed in place of each character entered into a Text control.

The value may be any single printable character. A typical value is the asterisk ("*").

This property is equivalent to the MSM specific ZPASWORDCHAR attribute.


Text Box


Picture Property

Applies to

The Picture property is used to specify a picture resource for display in a Button or Picture control or on a Toolbar.

In the context of a button component, the value of this property is an externalresource which must be of type .BMP.

In the context of a picture component, the data type for this property is an externalresource, and may be one of the following standard symbols for identifying errors, information, questions, and warnings:

"M,ERROR"
"M,INFO"
"M,QUEST"
"M,WARN"

In the context of a toolbar component, the value of this property is an externalresource which must be of type .BMP.  The picture is treated as a set of one or more horizontally-adjacent images of equal size.

This property is equivalent to the MWAPI RESOURCE attribute.


Button	Picture	Toolbar


PictureHeight Property

Applies to

The PictureHeight property specifies the height in pixels of each image within a Toolbar's image-strip bitmap. It is normally equal to the height of the bitmap.


Toolbar


PictureIndex Property

Applies to

The PictureIndex property selects the button's image from the image-strip specified in the Toolbar's Picture property. The picture is treated as a set of one or more horizontally-adjacent images of equal size. The leftmost image is index zero.


Toolbar Choice


PictureWidth Property

Applies to

The PictureHeight property specifies the width in pixels of each image within a Toolbar's image-strip bitmap. It is normally equal to the width of the bitmap divided by the number of adjacent images it contains.


Toolbar


Pointer Property

Applies to

The Pointer property is a pointertype value used to specify a pointer to be displayed when over a window or control.  The Pointer property of a control takes precedence over the Pointer property for the window, but is overridden by a PTYPE attribute set on the display (^$DISPLAY).

This property is equivalent to the MWAPI PTYPE attribute


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Generic
Group Box	Label	List Box	Long List
MDI Child	MDI Parent	Picture	Radio Button
Scroll Bar	Spin Button	Text Box	Window


PosJustifyH Property

Applies to

The PosJustifyH property specifies whether on creation at run-time a window should be justified left or right on the display, or centered horizontally, or not justified in the horizontal plane.

Possible values are:

"C"	Center
"L"	Left
"R"	Right


MDI Child	MDI Parent	Window


PosJustifyV Property

Applies to

The PosJustifyV property specifies whether on creation at run-time a window should be justified to the top or bottom of the display, or centered vertically, or not justified in the vertical plane.

Possible values are:

"C"	Center
"T"	Top
"B"	Bottom


MDI Child	MDI Parent	Window


PosLeft Property

Applies to

The PosLeft property is a numeric value that specifies the left position of an object. It may be negative.  The units used depend on the setting of the PosUnits property.

This property is derived from the MWAPI POS attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu
Picture	Radio Button	Scroll Bar	Spin Button
SQL Data	Tabbed Group	Text Box	Timer
Window


PosRecall Property

Applies to

The PosRecall property is a truefalse value that specifies whether on creation at run-time a window should be positioned to the location it had when previously destroyed.


MDI Child	MDI Parent	Window


PosTop Property

Applies to

The PosTop property is a numeric value that specifies the top position of an object.  It may be negative.  The units used depend on the setting of the PosUnits property.

This property is derived from the MWAPI POS attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu
Picture	Radio Button	Scroll Bar	Spin Button
SQL Data	Tabbed Group	Text Box	Timer
Window


PosUnits Property

Applies to

The PosUnits property is a unittype used to specify the units used for the PosLeft and PosTop properties of a window.

This property is derived from the MWAPI POS attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu
Picture	Radio Button	Scroll Bar	Spin Button
SQL Data	Tabbed Group	Text Box	Timer
Window


PrincipalModule Property

Applies to

The PrincipalModule property of an object is the name of the module used to apply module-specific default-sets to the properties of a newly created child object. For example, when a new control is placed on a window, default values for the control's properties are sought from a default-set belonging to the window's principal module. Any control properties that have not been loaded after this step are then sought from a default-set belonging to the principal module's principal module. When the principal module chain is exhausted, the <all> default-set is considered. Finally Workstation's own fallback defaults are used.

The current window must be registered as a component of the module in question.


MDI Child	MDI Parent	Window	Module


ReadOnly Property

Applies to

The ReadOnly property is a truefalse value that indicates whether or not a Data Control is to support updates to the table it accesses.


SQL Data


RecordSource Property

Applies to

The RecordSource property is a string value that defines the source of the data managed by a Data Control. In the case of access to an MSM-SQL database it is in the form schema.table.


SQL Data


Resizable Property

Applies to

The Resize property is a truefalse value that specifies whether the user can alter the size of the window at run time.

This property is equivalent to the MWAPI RESIZE attribute.


MDI Child	MDI Parent	Window


RowCol Property

Applies to

The RowCol property determines whether the RowColSize property of a Radio Button set refers to the number of rows or columns.

Possible values:

"COL" 	for columns
"ROW" 	for rows.

This property is derived from the MWAPI ROWCOL attribute.


Radio Button


RowColSize Property

Applies to

The RowColSize property is a positive integer that specifies the number of rows or columns (depending on the value of the RowCol property) in a Radio Button set.

This property is derived from the MWAPI ROWCOL attribute.


Radio Button


ScrollBars Property

Applies to

The ScrollBars property is a truefalse value that determines whether scroll bars are enabled on a window.  If true, and the application area is bigger than the viewport, scroll bars are provided.

This property corresponds to the MWAPI SCROLL window attribute.


MDI Child	Window


ScrollDir Property

Applies to

The ScrollDir property specifies whether a Scroll control is oriented horizontally or vertically.

Possible values:

"H" for horizontal
"V" for vertical.

This property is equivalent to the MWAPI SCROLLDIR attribute.


Scroll Bar


ScrollHeight Property

Applies to

The ScrollHeight property is a positive numeric value that specifies the maximum scrolling height when the ScrollVert property is true. The units used depend on the setting of the ScrollUnits property.

This property is derived from the MWAPI SCROLL attribute.


Document


ScrollHorz Property

Applies to

The ScrollHorz property is a truefalse value that specifies whether horizontal scrolling is provided.  If set to true, horizontal scrolling is permitted and the ScrollWidth property is applied.  Otherwise no horizontal scrolling is permitted.

This property is derived from the MWAPI SCROLL attribute.


Document


ScrollLarge Property

Applies to

The ScrollLarge property is a positive numeric value that specifies the amount by which the Value increases or decreases when the user clicks between the thumb and an arrow on a Scroll control.

This property is derived from the MWAPI SCROLLBY attribute.


Scroll Bar


ScrollMax Property

Applies to

The ScrollMax property is a positive numeric value that specifies the maximum Value of the scrollbar range for a Long List or Scroll control.

This property is derived from the MWAPI SCROLLRANGE attribute.


Long List	Scroll Bar


ScrollMin Property

Applies to

The ScrollMin property is a positive numeric value that specifies the minimum Value of the scrollbar range for a Long List or Scroll control.

This property is derived from the MWAPI SCROLLRANGE attribute.


Long List	Scroll Bar


ScrollPosition Property

Applies to

The ScrollPosition property is a positive numeric value that specifies the position of the scroll indicator in a Long List control, relative to the scale specified by the ScrollMax and ScrollMin property.

This property is equivalent to the MWAPI SCROLLPOS attribute.


Long List


ScrollSmall Property

Applies to

The ScrollSmall property is a positive numeric value that specifies the amount by which the Value increases or decreases when the user presses an arrow on a Scroll control.

This property is derived from the MWAPI SCROLLBY attribute.


Scroll Bar


ScrollUnits Property

Applies to

The ScrollUnits property is a unittype used to specify the units used for the ScrollHeight and ScrollWidth properties of an object.

This property is derived from the MWAPI SCROLL attribute.


Document


ScrollVert Property

Applies to

The ScrollVert property is a truefalse value that specifies whether vertical scrolling is provided.  If set to true, vertical scrolling is permitted and the ScrollHeight property is applied.  Otherwise no vertical scrolling is permitted

This property is derived from the MWAPI SCROLL attribute.


Document


ScrollWidth Property

Applies to

The ScrollWidth property is a positive numeric value that specifies the maximum scrolling width when the ScrollHorz property is true. The units used depend on the setting of the ScrollUnits property.

This property is derived from the MWAPI SCROLL attribute.


Document


SelStartLength Property

Applies to

The SelStartLength property is a string with the format:

start,length

The start indicates the starting point of the selection; the length indicates the length of the selection (forward if positive, backward if negative).

This property is equivalent to the MWAPI INSELECT attribute.


Combo Box	Document	Drop-down Combo	Text Box


SelText Property

Applies to

The SelText property is a string that specifies the text currently selected within the control.


Combo Box	Document	Drop-down Combo	Text Box


Separator Property

Applies to

The Separator property, if defined, indicates that a separator bar is to follow the menu selection to which the property is attached. It is set using the Menu Editor.

This property is equivalent to the MWAPI SEPARATOR attribute.


Menu Choice


SepWidth Property

Applies to

The SepWidth property records at toolbar design-time the number of pixels spacing to precede the button.


Toolbar Choice


SizeHeight Property

Applies to

The SizeHeight property is a positive numeric value used to specify the height of an object. The units used depend on the setting of the SizeUnits property.

This property is derived from the MWAPI SIZE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	Tabbed Group
Text Box	Window


SizeRecall Property

Applies to

The SizeRecall property is a truefalse value that specifies whether on creation at run-time a window should be set to the size it had when previously destroyed.


MDI Child	MDI Parent	Window


SizeUnits Property

Applies to

The SizeUnits property is a unittype value used to specify the units used for the SizeHeight and SizeWidth properties of an object.

This property is derived from the MWAPI SIZE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	Tabbed Group
Text Box	Window


SizeWidth Property

Applies to

The SizeWidth property is a positive numeric value used to specify the width of an object. The units used depend on the setting of the SizeUnits property.

This property is derived from the MWAPI SIZE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	Tabbed Group
Text Box	Window


SpinStep Property

Applies to

The SpinStep property is a positive numeric value that specifies the step size when the spin buttons are used in a Spin control.

This property is equivalent to the SCROLLBY attribute of this MSM specific gadget.


Spin Button


Style Property

Applies to

The Style property specifies the style of a toolbar button.

Possible values:

Value	Description
"CHECK"	Generates a select event when pushed in. Remains depressed until released by user, when it generates a deselect. State can be altered under program control using the Value property.
"PUSH"	Generates a select event when pushed. Returns to unpushed state automatically.
"RADIO"	Generates a select event when pushed in. Remains depressed until its Value property is set to false under program control. May also be set into depressed state by setting Value property true.


Toolbar Choice


Submenu Property

Applies to

The Submenu property identifies the menu to be presented when this choice is selected. It is established using the Menu Editor to define a menu hierarchy.

This property is equivalent to the MWAPI SUBMENU attribute.


Menu Choice


TabStops Property

Applies to

The TabStops property is a string that defines the tab stop positions within a control.

The format is a string of positive integer numbers, separated by commas, in ascending order. The numbers define the positions within the width of a control at which tab-stops are to be set. The unit of measure is one-eighth (1/8) of the average character width in the control's font. Consequently, as the font is altered, the tab-stops vary.

This property is equivalent to the MSM specific ZTABSTOPS attribute.


Combo Box	Document	Drop-down Combo	Drop-down List
List Box	Long List


TBackColor Property

Applies to

The TBackColor property is a colorvalue that specifies the background color of a control's label text. For a window TBackColor is used to specify the default background color for the labels of controls placed on the window. Colors can be chosen using the color palette or by explicitly entering the value.

This property is equivalent to the MWAPI TBCOLOR attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Text Box	Window


TFontBold Property

Applies to

The TFontBold property is a truefalse value that specifies whether or not a control's label text should be bold.

This property corresponds to the presence or absence of BOLD in the MWAPI TFONTSTYLE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


TFontFace Property

Applies to

The TFontFace property is a fontface value that specifies the font face used for the labels of certain controls.

This property is equivalent to the MWAPI TFFACE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


TFontItalic Property

Applies to

The TFontItalic property is a truefalse value that specifies whether or not a control's label text should be italicized.

This property corresponds to the presence or absence of ITALIC in the MWAPI TFONTSTYLE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


TFontSize Property

Applies to

The TFontSize property is a fontsize value that specifies the point-size for a control's label text.

This property corresponds to the MWAPI FONTSIZE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


TFontUline Property

Applies to

The TFontUline property is a truefalse value that specifies whether or not a control's label text should be underlined.

This property corresponds to the presence or absence of ULINE in the MWAPI TFONTSTYLE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


TForeColor Property

Applies to

The TForeColor property is a colorvalue that specifies the foreground color of a control's label text. For a window TForeColor is used to specify the default foreground color for the labels of controls placed on the window. Colors can be chosen using the color palette or by explicitly entering the value.

This property is equivalent to the MWAPI TFCOLOR attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Text Box	Window


Tied Property

Applies to

The Tied property is a truefalse value.  If true, a child window is positioned relative to its parent's origin, and moves with its parent.

The Tied property can affect the positioning and sizing of the tied window:

If Tied is true

The position is relative to the top left corner of the parent window. If the sizing unittype (explicitly specified by SizeUnits or inherited from WinUnits) is REL, the basis size is that of the parent window on creation.  If the unit of measure is CHAR, the basis font is that specified by the parent window's font face, font styles, and font size.

If Tied is false

The position is relative to the top left corner of the display. If the sizing unittype is REL, the basis size is the size of the display. If the unit of measure is CHAR, the basis font is that specified by the display's font face, font styles, and font size.

This property is equivalent to the MWAPI TIED attribute.


Window


Title Property

Applies to

The Title property is a string that specifies the text that appears adjacent to or within a control, dependent on its type.

If the string contains an ampersand symbol (&), the following character is underlined and the control can get focus using the keyboard ALT key plus the underlined character. If two & characters are used together, one is displayed in the text.

This property is equivalent to the MWAPI TITLE attribute.


Button	Checkbox	Combo Box	Date
Document	Drop-down Combo	Drop-down List	Group Box
Label	List Box	List Choice	Long List
MDI Child	MDI Parent	Menu Choice	Radio Button
Scroll Bar	Spin Button	Text Box	Window


TitlePos Property

Applies to

The TitlePos property specifies the position of a control's label relative to the control.

Values are: "TOP", "LEFT" or "RIGHT".   If "LEFT", the top right corner of the title is put next to the top left corner of the control. If "RIGHT", the top left corner of the title is put next to the top right corner of the control. If "TOP", the bottom left corner of the title is put next to the top left corner of the control.

This property is equivalent to the MWAPI TPOS attribute.


Combo Box	Date	Document	Drop-down Combo
Drop-down List	List Box	Long List	Radio Button
Scroll Bar	Spin Button	Text Box


ToolTip Property

Applies to

The ToolTip property is a string specifying the text to appear as a tooltip when the pointer pauses over the toolbar button while the window is active.


Toolbar Choice


TopRow Property

Applies to

The TopRow property is a choiceitem that specifies which choice is displayed at the top of the visible area of a list type control.

This property is equivalent to the MWAPI TOPSHOW attribute.


Combo Box	List Box	Long List


Type Property

Applies to

The Type property specifies the object type. It is not editable after definition of an object.

This property is equivalent to the MWAPI TYPE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	SQL Data
Tabbed Group	Text Box	Timer	Window


Units Property

Applies to

The Units property is a unittype used to specify the default units used for the properties of an object which relate to size and height. It also specifies the units in which all size and position properties will be returned when retrieved using %%Get or %%Prop.

This property is equivalent to the MWAPI UNITS attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu
Picture	Radio Button	Scroll Bar	Spin Button
Tabbed Group	Text Box	Window


Value Property

Applies to

The Value property specifies the data associated with or represented by a control.

In the context of a Checkbox, the data type for this property is truefalse.

In the context of Text Box, Combo Box and Drop-down Combo controls, the data type for this property is free text.

In the context of Spin Button and Scroll Bar controls, the data type for this property is a numeric value.

In the context of a Document control, the data type for this property is free text, up to 32k bytes long.

In the context of Radio Button and Drop-down List components, the data type for this property is a choice item.

In the context of the Date control, the data type for this property is datevalue.

This property is equivalent to the MWAPI VALUE attribute.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	Text Box
Toolbar Choice


VarName Property

Applies to

The VarName property is used to specify the name of an unsubscripted M local variable to link to the control.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	Text Box


VarPermanent Property

Applies to

The VarPermanent property is a truefalse value used to specify whether the local variable linked with the control and specified in the VarName property is permanent or not. A permanent variable is visible outside of the scope of execution of the window in which the associated control is contained.


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Scroll Bar	Spin Button	Text Box


Visible Property

Applies to

The Visible property is a truefalse value that specifies whether an object is visible to the user or not.

If Visible is False, the control is not displayed. If True, the control is displayed, except for those parts of it overlapped by other objects, unless it is the descendant of an invisible window.

This property is equivalent to the MWAPI VISIBLE attribute.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Menu
Picture	Radio Button	Scroll Bar	Spin Button
Tabbed Group	Text Box	Toolbar	Window


WinHeight Property

Applies to

The WinHeight property is a positive numeric value used to specify the overall height of a window including any border, sizing frame, menu and title bar. The units used depend on the setting of the WinUnits property.

This property is derived from the MWAPI SIZEWIN attribute.


MDI Child	MDI Parent	Window


WinUnits Property

Applies to

The WinUnits property is a unittype value used to specify the units used for the WinHeight and WinWidth properties of a window.

This property is derived from the MWAPI SIZEWIN attribute.


MDI Child	MDI Parent	Window


WinWidth Property

Applies to

The WinWidth property is a positive numeric value used to specify the overall width of a window including any border or sizing frame. The units used depend on the setting of the WinUnits property.

This property is derived from the MWAPI SIZEWIN attribute.


MDI Child	MDI Parent	Window


About Events and Action Logic

Action logic is the term used for the M code and macros that the developer writes and attaches to the various events that can occur as the application end-user interacts with the product. In simple terms, events happen and your application performs actions in response to them by executing action logic. Modules, windows, and each type of control have a set of events that may occur. These are grouped into low-level events  and high-level events. Windows and modules also have a special action logic section called CommonCode

Within action logic, all tags beginning with a percent character are reserved for MSM-Workstation compiler use. All local variable names starting with the characters ViEW are also reserved. Do not set, get or kill these directly. If the link to MSM-SQL is being used all variable names starting with the characters SQL should also be avoided. Some of these internal variables are accessible to you via macro names. You must also avoid use of the argumentless or exclusive form of the NEW command in your action logic sections.

Tags may be used in action logic lines, but those in sections other than CommonCode are only accessible from within the same section.

See Also:

High-Level Events

Low-Level Events

Event Sequence

Principal Events


High-Level Events

High-level events are more frequently required and used for common tasks than are low-level events.  High-level events are generated by the MSM-Workstation compiler and do not necessarily have an MWAPI counterpart. However, they are frequently caused by a corresponding low-level event.. For example, a Button has a low-level select event and a high-level Push event. Action logic may be attached to either, or to both. The select logic is performed first, followed by the Push logic. In fact, the select logic can be made to mask out the Push logic by using the %%NotOK macro. See Event Sequence for more details.

High-Level Events begin with an uppercase character.

High-Level Events

AddNew	Check	Choose	Create
DeleteRecord	Destroy	Enter	Error
Exit	Modified	MoveFirst	MoveLast
MoveNext	MovePrevious	MoveTo	Push
Scroll	UpdateControls	UpdateRecord	Validate


Low-Level Events

The low-level events are typically less frequently required for common tasks than are the high-level events.  The low-level events correspond closely to what actually happens; they are the MWAPI events. Their names begin with a lowercase character. See Event Sequence for more details.

Low-Level Events

change	char	click	close
dblClick	deselect	goBottom	goDown
goDownBig	gotFocus	goTop	goUp
goUpBig	help	keyDown	keyUp
lostFocus	maximize	minimize	move
ptrDown	ptrDrag	ptrMove	ptrUp
resize	restore	select


Event Sequence

The end-user interacts with a control or window using the mouse or keyboard, and this interaction gives rise to MWAPI events in the normal way. These are the low-level events. When one occurs, any action logic placed on the event is run. If this action logic executes the %%NotOK macro before quitting, then the high-level event linked to the low level one is suppressed and any Action logic on the high-level event is not performed. Otherwise, the high-level action logic follows the low-level logic.

The following list shows which high-level events follow which low-level events for the individual object types:

Object	Low-level events	High-level events
Window & all Controls	gotFocus	Enter
Window & all Controls	lostFocus	Exit
Combo Box, Date, Document, Drop-down Combo, Spin Button, Text Box	change	Modified, Exit
Button	select	Push
Radio Button	deselect, select	Push
Checkbox	deselect, select	Check
Drop-down List, List Box, Long List	deselect, select	Choose
Scroll Bar	select	Scroll
Long List	goBottom, goDown, goDownBig, goTop, goUp, goUpBig	Scroll
Where more than one low-level event is listed for a single table entry, any of the events lead to the same high-level event. If the high-level event action logic needs to know its originator it can examine the event information using the %%Ev* macros. Where more than one high-level event is listed, if action logic for a given event in the list executes the %%NotOK macro before quitting then no more of the listed high-level events occur.

Other chained events

The following table summarises other situations not covered above where the successful completion of action logic on one event (i.e. %%NotOK is not executed) causes another event's logic to be performed. Note that it does not cover the MSM-SQL Data Control events; see Data Control Usage for more details.

Initial event	Chained event
Window Create	Initially-enabled control Create events, in collating sequence of control name. The window and all its defined controls have been created before any Control Create events occur.
Window Destroy	Initially-enabled control Destroy events, in collating sequence of control name. The window is not killed until after all Control Destroy events complete successfully.


Principal Events

Certain controls have one event denoted the principal event. It is considered to be the one most likely to require action logic, and is used by the control's definition dialog to select which action logic to present first. The principal events are as follows:

Control Type	Principal Event
Button	Push
CheckBox	Check
Combo Box	Modified
Date	Modified
Document	Modified
Drop Down Combo	Modified
Drop Down List	Choose
Generic	Create
List Box	Choose
Long List	Choose
MSM-SQL Data	Create
Radio Button	Push
Scroll	Scroll
Spin Button	Modified
Text Box	Modified


Events A-Z

AddNew Event

CommonCode

Check Event

Choose Event

Create Event

DeleteRecord Event

Destroy Event

Enter Event

Error Event

Exit Event

Modified Event

MoveFirst Event

MoveLast Event

MoveNext Event

MovePrevious Event

MoveTo Event

Push Event

Scroll Event

UpdateControls Event

UpdateRecord Event

Validate Event

change Event

char Event

click Event

close Event

dblClick Event

deselect Event

goBottom Event

goDown Event

goDownBig Event

gotFocus Event

goTop Event

goUp Event

goUpBig Event

help Event

keyDown Event

keyUp Event

lostFocus Event

maximize Event

minimize Event

move Event

ptrDown Event

ptrDrag Event

ptrMove Event

ptrUp Event

resize Event

restore Event

select Event

timer Event


AddNew Event

Applies to	See also

The high level event AddNew is caused by use of the macro %%Perform in other action logic.

The action logic for this event is intended to

•	prepare a SQL Data control for the addition of a record,

•	clear the values of all list-type controls on the window that are bound to the SQL Data Control component (see the property ChoiceField)

•	perform user-supplied action logic

Use of the macro %%NotOK in the action logic will cancel the record preparation. Otherwise the new record will be filed when the next UpdateRecord event occurs, which may be performed explicitly or may occur as a result of one of the Move events.


SQL Data


MoveFirst	MoveLast	MoveNext	MovePrevious
MoveTo	UpdateControls	UpdateRecord


CommonCode

Applies to

CommonCode is not an "event", but contains code commonly called from event action logic, and is selected for editing from a list of events.

Both windows and modules may have a CommonCode section.  CommonCode contains subroutines and extrinsic functions that are needed by action logic sections of the window or module. These subroutines are started with a normal M tag and optional formal parameter list and concluded with a Quit command. Logically, these tags are all in the same routine as the logic sections that call them. The tags are used like normal M local tags within the action logic which calls them. Of course, action logic and even the CommonCode section can also call tags in external routines. Such external routines must be edited and managed independently by the developer.

CommonCode in a window is available to that window and any controls within the window.

CommonCode in a module is only available to that module and is not available to any of its components.


MDI Child	MDI Parent	Module	Window


Check Event

Applies to

The high level event Check occurs when a box is checked or cleared.

Appropriate code for this event includes any processing that needs to be done when an option is enabled or disabled. In particular the "activation" (or deactivation or graying out) of other controls in the window, that depend on the current box being "checked" is expected to be in the action logic for this type of event.

The high level event Check occurs after the low level events select and deselect for a Check Box component.

Note: The event Check is triggered after both a deselect and a select event. In general, it is easier to attach event-handling code to either of these low-level events, than to the high level event Check.


Checkbox


Choose Event

Applies to

The high level event Choose occurs when an option is chosen from a list.

Appropriate code for this event includes any processing that needs to be done when the value of the control changes.

If any other controls in the window need to be activated or de-activated for specific values of this control, this event is the appropriate place to insert code that causes such (de)activation.

The high level event Choose occurs after the low-level events deselect and select.

Note: The event Choose is triggered after both a deselect and a select event. For a control in which only a single selection is permitted, change of selection results in two Choose events. It is sometimes easier to attach event-handling code to either of these low-level events. In the case of a list accepting multiple selections the high level event Choose might appropriately contain action logic that must be executed whenever the selection set changes. A single user action can result in multiple events, but the user might have achieved the same result by a sequence of individual operations. The resulting behavior of the application should be equivalent.


Drop-down List	List Box	Long List


Create Event

Applies to

The high level event Create occurs when an object is created.

Appropriate code for this event includes any initialization that is specific to the object.

A window's Create event occurs when the window comes into existence as a result of the %%DoWin or %%OpenWin macro. At the point where the action logic executes, the window exists. Use of %%NotOK indicates that creation is to be aborted.

A control's Create event occurs during the window creation process, unless the event is flagged as Disabled at design time. It occurs after the window's Create event and following the Create events for any controls with names collating before this control. It does not occur if action logic on any preceding Create event signals %%NotOK.

In the case of an SQL Data control's Create event, any list-type controls bound to the control through the property ChoiceField are loaded before the event's action logic is executed. When the action logic begins execution the SQL Data control will be positioned before the first record. In some circumstances (e.g. if the property DataSort specifies a sequence that is not indexed within the database) the event Create on the SQL Data control queries the database for all the records, which may cause a perceptible delay. See the Message property for information about how to show the progress of SQL Data control creation.

Note: once the Create event has occurred for an SQL Data control, this event cannot be re-executed using the %%Perform macro unless a Destroy event first occurs.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	SQL Data
Tabbed Group	Text Box	Timer	Window


DeleteRecord Event

Applies to

The high level event DeleteRecord is caused by use of the macro %%Perform in other action logic.

When this event occurs, MSM-Workstation first deletes the current record of the SQL Data control and then invokes any other action logic.


SQL Data


Destroy Event

Applies to

The high level event Destroy will occur when the object is destroyed.

A window's Destroy event occurs when the window ceases to exist as a result of the %%Return, %%Cancelor %%CloseWin macros. At the point where the action logic executes, the window still exists. Use of %%NotOK indicates that destruction is to be aborted.

A control's Destroy event occurs during the window destruction process, unless the event is flagged as Disabled at design time. It occurs after the window's Destroy event and following the Destroy events for any controls with names collating before this control. It does not occur if action logic on any preceding Destroy event signals %%NotOK.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	Group Box	Label	List Box
Long List	MDI Child	MDI Parent	Picture
Radio Button	Scroll Bar	Spin Button	SQL Data
Tabbed Group	Text Box	Timer	Window


Enter Event

Applies to

The high level event Enter occurs for a window or control when the input focus moves to the object.

For a module or application, the event Enter occurs when the object is called with the %%Do macro. The action logic would normally proceed to %%Do or %%DoWin another module or window. When program flow quits the Enter section, the Exit event occurs unless the macro %%NotOK has been encountered.

For other objects, the event Enter occurs when the object receives the focus as a result of user action. In such cases, the high level event Enter occurs after the low-level event gotFocus. The event Enter also occurs when focus is moved as a result of program action, for example during the execution of %%SetFocus.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Module	Radio Button	Spin Button
Tabbed Group	Text Box	Window


Error Event

Applies to

The high level event Error occurs when an M error is detected and this error is not handled within any localized error trap in the M code.

For a window's Error event, completion of this event's action logic with the M command QUIT will cause resumption of event handling for the window. Use of either of the macros %%Return or %%Cancel will cause a return from the window. Including the macro %%NotOK before a Quit from the Error section will cause the error to be passed back unhandled to the section that called the window.

For an SQL Data control, the Error event occurs if an unhandled M error is detected during the processing of any of its events. Use of the %%NotOK macro before Error event action logic quits will cause the error to be passed back unhandled to a higher error-handler. Otherwise the original event terminates as if %%NotOK had been used within its own action logic.


MDI Child	MDI Parent	Module	SQL Data
Window


Exit Event

Applies to

The high level event Exit occurs for a window or control when the input focus moves off the object.

For a module or application, the event Exit occurs when program flow quits the Enter section, unless the macro %%NotOK has been encountered.

For other objects, the event Exit occurs when the object loses the focus as a result of user action. In such cases, the high level event Exit occurs after the low level events lostFocus or change. The event Exit also occurs when focus is moved as a result of program action, for example during the execution of %%SetFocus.

Where the Exit event occurred as a result of a low level event, use of the %%NotOK macro will prevent the focus-switch, and so far as is possible will suppress other events that would normally have occurred if the focus-switch had proceeded. See details of the low level events for more information.


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Module	Radio Button	Spin Button
Tabbed Group	Text Box	Window


Modified Event

Applies to

The high level event Modified occurs after the Value property of a component has been changed by the user. The event occurs only when the user moves away from the control that was modified.

The high level event Modified occurs after the low level event change. Use of the %%NotOK macro will prevent the focus-switch, and so far as is possible will suppress other events that would normally have occurred if the focus-switch had proceeded. See details of the low level event for more information.


Combo Box	Date	Document	Drop-down Combo
Spin Button	Text Box


MoveFirst Event

Applies to	See also

The high-level event MoveFirst positions an SQL Data control at the first record of its record-set. It is one of a group of Move-events (MoveFirst, MoveLast, MoveNext, MovePrevious and MoveTo), and is initiated by use of the macro %%Perform in other action logic.

When that happens, a Validate event occurs. If action logic on that event uses the macro %%NotOK, the event MoveFirst completes.

Otherwise if

•	the SQL Data control is not ReadOnly,

•	and there is a current record

•	and the Changed property of the SQL Data control is true

then an UpdateRecord event occurs. If action logic on that event uses the macro %%NotOK, then the event MoveFirst completes.

Otherwise the SQL Data control moves to the first record.

If there are no records, the event MoveFirst completes, signalling %%NotOK.

Otherwise, controls on the window that are bound to the SQL Data control (by means of their DataField properties) are loaded from the new record. After this, any MoveFirst action logic is executed. If this uses the macro %%NotOK, the event MoveFirst completes.

Otherwise any action logic for the UpdateControls event is executed.


SQL Data


AddNew	MoveLast	MoveNext	MovePrevious
MoveTo	UpdateControls	UpdateRecord


MoveLast Event

Applies to	See also

The high-level event MoveLast positions an SQL Data control at the last record of its record-set. It is one of a group of Move-events (MoveFirst, MoveLast, MoveNext, MovePrevious and MoveTo), and is initiated by use of the macro %%Perform in other action logic.

When that happens, a Validate event occurs. If action logic on that event uses the macro %%NotOK, the event MoveLast completes.

Otherwise if

•	the SQL Data control is not ReadOnly,

•	and there is a current record

•	and the Changed property of the SQL Data control is true

then an UpdateRecord event occurs. If action logic on that event uses the macro %%NotOK, then the event MoveLast completes.

Otherwise the SQL Data control moves to the last record.

If there are no records, the event MoveLast completes, signalling %%NotOK.

Otherwise, controls on the window that are bound to the SQL Data control (by means of their DataField properties) are loaded from the new record. After this, any MoveLast action logic is executed. If this uses the macro %%NotOK, the event MoveLast completes.

Otherwise any action logic for the UpdateControls event is executed.


SQL Data


AddNew	MoveFirst	MoveNext	MovePrevious
MoveTo	UpdateControls	UpdateRecord


MoveNext Event

Applies to	See also

The high-level event MoveNext positions an SQL Data control at the next record of its record-set. It is one of a group of Move-events (MoveFirst, MoveLast, MoveNext, MovePrevious and MoveTo), and is initiated by use of the macro %%Perform in other action logic.

When that happens, a Validate event occurs. If action logic on that event uses the macro %%NotOK, the event MoveNext completes.

Otherwise if

•	the SQL Data control is not ReadOnly,

•	and there is a current record

•	and the Changed property of the SQL Data control is true

then an UpdateRecord event occurs. If action logic on that event uses the macro %%NotOK, then the event MoveNext completes.

Otherwise the SQL Data control moves to the next record.

If there are no further records, the control remains on its original record and the event MoveNext completes, signalling %%NotOK.

Otherwise, if the new record is the last one and action logic exists for the event MoveLast, the event MoveNext completes and MoveLast occurs.

Otherwise, controls on the window that are bound to the SQL Data control (by means of their DataField properties) are loaded from the new record. After this, any MoveNext action logic is executed. If this uses the macro %%NotOK, the event MoveNext completes.

Otherwise any action logic for the UpdateControls event is executed.


SQL Data


AddNew	MoveFirst	MoveLast	MovePrevious
MoveTo	UpdateControls	UpdateRecord


MovePrevious Event

Applies to	See also

The high-level event MovePrevious positions an SQL Data control at the previous record of its record-set. It is one of a group of Move-events (MoveFirst, MoveLast, MoveNext, MovePrevious and MoveTo), and is initiated by use of the macro %%Perform in other action logic.

When that happens, a Validate event occurs. If action logic on that event uses the macro %%NotOK, the event MovePrevious completes.

Otherwise if

•	the SQL Data control is not ReadOnly,

•	and there is a current record

•	and the Changed property of the SQL Data control is true

then an UpdateRecord event occurs. If action logic on that event uses the macro %%NotOK, then the event MovePrevious completes.

Otherwise the SQL Data control moves to the previous record.

If there are no previous records, the control remains on its original record and the event MovePrevious completes, signalling %%NotOK.

Otherwise, if the new record is the first one and action logic exists for the event MoveFirst, the event MovePrevious completes and MoveFirst occurs.

Otherwise, controls on the window that are bound to the SQL Data control (by means of their DataField properties) are loaded from the new record. After this, any MovePrevious action logic is executed. If this uses the macro %%NotOK, the event MovePrevious completes.

Otherwise any action logic for the UpdateControls event is executed.


SQL Data


AddNew	MoveFirst	MoveLast	MoveNext
MoveTo	UpdateControls	UpdateRecord


MoveTo Event

Applies to	See also

The high-level event MoveTo positions an SQL Data control at a specific record of its record-set. It is one of a group of Move-events (MoveFirst, MoveLast, MoveNext, MovePrevious and MoveTo), and is initiated by use of the macro %%Perform in other action logic.

The macro %%Perform accepts an optional second parameter. In the case of this event, the parameter specifies which record to move to. If the value of this parameter is zero, or if the parameter is not specified, the move is to the current record. Otherwise a positive integer value indicates the record number requested, and a negative number denotes an offset back from the last record.

When the event MoveTo is initiated, a Validate event occurs. If action logic on that event uses the macro %%NotOK, the event MoveTo completes.

Otherwise if

•	the SQL Data control is not ReadOnly,

•	and there is a current record

•	and the Changed property of the SQL Data control is true

then an UpdateRecord event occurs. If action logic on that event uses the macro %%NotOK, then the event MoveTo completes.

Otherwise the SQL Data control moves to the required record.

If there is no such record, the control is positioned after the last record (required record number too large) or before the first record (required record number too small) and the event MoveTo completes, signalling %%NotOK.

Otherwise, controls on the window that are bound to the SQL Data control (by means of their DataField properties) are loaded from the new record. After this, any MoveTo action logic is executed. If this uses the macro %%NotOK, the event MoveTo completes.

Otherwise any action logic for the UpdateControls event is executed.


SQL Data


AddNew	MoveFirst	MoveLast	MoveNext
MovePrevious	UpdateControls	UpdateRecord


Push Event

Applies to

The high level event Push occurs when a Button is pushed or a Radio Button choice is selected.

The high level event Push occurs after the low level event select for a Button component and after the events select and deselect for a Radio Button component.

Note: The event Push occurs for a Radio Button after both a deselect and a select event. For such a control it is often easier to attach event-handling code to either of these low-level events.


Button	Radio Button


Scroll Event

Applies to

The high level event Scroll occurs for a Scroll Bar control when the position-indicator is moved, or for a Long List control after user action requests its contents to scroll.

For a Scroll control, the high level event Scroll occurs after the low level event select.

For a Long List control, the event Scroll occurs after the low level events goBottom, goDown, goDownBig, goTop, goUp and goUpBig.


Long List	Scroll Bar


UpdateControls Event

Applies to	See also

The high level event UpdateControls occurs when

•	an SQL Data control updates any controls that are linked to it, or

•	the macro %%Perform triggers the event directly. In this case the current record will be re-fetched from the database. If there is no current record, the event UpdateControls completes.

Controls on the window that are bound to the SQL Data control (by means of their DataField properties) are reloaded from the record. After this, any UpdateControls action logic is executed.

One sample scenario for issuing a %%Perform on this action would be the implementation of a Cancel button.


SQL Data


AddNew	MoveFirst	MoveLast	MoveNext
MovePrevious	MoveTo	UpdateRecord


UpdateRecord Event

Applies to	See also

The high level event UpdateRecord occurs when

•	an SQL Data control that is not ReadOnly is about to move off a Changed record during a Move-type event, or

•	the macro %%Perform triggers the event directly.

Field values for the record are obtained from the controls on the window that are bound to the SQL Data control (by means of their DataField properties).

If a new record was prepared using the event AddNew, the new record is added to the database. Otherwise the current record is updated.

Then any action logic is executed, and unless this uses the macro %%NotOK, the Changed property of the SQL Data control is cleared.

One sample scenario for issuing a %%Perform on this action would be the implementation of a Save button. In such a case the Validate event might be performed first.


SQL Data


AddNew	MoveFirst	MoveLast	MoveNext
MovePrevious	MoveTo	UpdateControls


Validate Event

Applies to

The high level event Validate occurs when a SQL Data control is about to move to a new record. See the Move-events for more details (MoveFirst, MoveLast, MoveNext, MovePrevious or MoveTo). It can also occur through use of the macro %%Perform in other action logic.


SQL Data


change Event

Applies to

The low level event change is generated instead of the event lostFocus if the value of the Changed property for the control is true when the user moves focus away from it.

The low level event change is followed by the high level events Modified and Exit.

Use of the %%NotOK macro will prevent the focus-switch, and so far as is possible will suppress other events that would normally have occurred if the focus-switch had proceeded. The Changed property will remain true. Otherwise the property will be set false.

In MWAPI, this event is called "CHANGE"


Checkbox	Combo Box	Date	Document
Drop-down Combo	Drop-down List	List Box	Long List
Radio Button	Spin Button	Text Box


char Event

Applies to	See also

The low level event char occurs when one or more keyboard key transitions results in the production of a character.

Information about the character and key(s) in question can be obtained using the macro %%EvKey.

In the context of this event, the macro %%EvKey returns the ASCII value of the character. When action logic is defined for the event, any character whose production causes the event will not alter the value of the control unless the action logic does this explicitly. If a filter is defined on the event, characters not matching the filter will affect the control's value in the normal way instead of causing the event.

In MWAPI, this event is called "CHAR"


Combo Box	Document	Drop-down Combo	Generic
MDI Child	MDI Parent	Text Box	Window


keyDown	keyUp	FilterIn


click Event

Applies to

The low level event click occurs for an object when, with the pointer over the object, the pointer button is pressed and released without any intervening pointer movement.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

In MWAPI, this event is called "CLICK"


Generic	MDI Child	MDI Parent	Window


close Event

Applies to

The low level event close occurs when the end-user attempts to close the window using one of the standard Windows techniques, such as the close-button X on the title bar.

Use of the %%NotOK macro within action logic for this event causes the close request to be refused. Otherwise, the window will be closed in the same manner as if the action logic had executed the %%Return macro.

The close-button on a window is disabled if all of the following conditions are met:

•	the window has a parent, either defined at design-time using the Parent property or else established at create-time using the Settings parameter of %%DoWin

•	the close event is defined as initially Disabled and has no lines of action logic, not even any comments

In MWAPI, this event is called "CLOSE"


MDI Child	MDI Parent	Window


dblClick Event

Applies to

The low level event dblClick occurs for an object when , with the pointer over the object, the pointer button is pressed and released twice within a Windows-defined time interval and without any intervening pointer movement.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

In MWAPI, this event is called "DBLCLICK"


Combo Box	Generic	List Box	Long List
MDI Child	MDI Parent	Window


deselect Event

Applies to

The low level event deselect occurs when one of an object's selected choices is deselected.

For a Radio Button control, the low level event deselect is followed by the high level event Push.

For a Check Box control, the low level event deselect is followed by the high-level event Check.

For Drop-Down List, List Box and Long List controls, the low level event deselect is followed by the high level event Choose.

For Combo Box and Drop-Down Combo controls, the deselect event occurs when another choice is selected, or when the choice text is edited directly.

For a checkbox-type Toolbar Button, the deselect event occurs when the user releases the button from its pushed-in state.

Note: The high level events Check, Choose, and Push which follow some instances of this event also occur after a select event for the same control. In some cases it is simpler to locate action logic on the appropriate low level event. Where the control permits concurrent selection of more than one choice, multiple deselect events may occur as a result of a single user action.

In MWAPI, this event is called "DESELECT"


Checkbox	Combo Box	Drop-down Combo	Drop-down List
List Box	Long List	Radio Button	Toolbar Choice


goBottom Event

Applies to	See also

The low level event goBottom occurs for a Long List control when the key labeled End is depressed while the focus is on thecontrol, or when the corresponding scroll-button is clicked.

The low level event goBottom occurs for a Long List control when the one of the following actions is performed:

•	the control's "last-record" scroll-button is clicked

•	the End key is pressed on the keyboard while focus is on the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goBottom is followed by the high level event Scroll.

In MWAPI, this event is called "GOBOTTOM"


Long List


goDown	goDownBig	goTop	goUp
goUpBig	Scroll


goDown Event

Applies to	See also

The low level event goDown occurs for a Long List control when the one of the following actions is performed:

•	the control's "one-down" scroll-button is clicked

•	the Cursor Down key is pressed on the keyboard while focus is on the last visible choice of the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goDown is followed by the high level event Scroll.

In MWAPI, this event is called "GODOWN"


Long List


goBottom	goDownBig	goTop	goUp
goUpBig	Scroll


goDownBig Event

Applies to	See also

The low level event goDownBig occurs for a Long List control when the one of the following actions is performed:

•	the control's "page-down" scroll-button is clicked

•	the Page Down key is pressed on the keyboard while focus is on the last visible choice of the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goDownBig event is followed by high level event Scroll.

In MWAPI, this event is called "GODOWNBIG"


Long List


goBottom	goDown	goTop	goUp
goUpBig	Scroll


gotFocus Event

Applies to

The low level event gotFocus occurs when an object receives focus as a result of a user action. This can happen as the user moves between windows and controls within the Workstation application, or returns to the Workstation application after interacting with another part of the Windows environment.

The low level event gotFocus is followed by the high level event Enter.

In MWAPI, this event is called "FOCUS"


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Radio Button	Spin Button	Tabbed Group
Text Box	Window


goTop Event

Applies to	See also

The low level event goTop occurs for a Long List control when the one of the following actions is performed:

•	the control's "first-record" scroll-button is clicked

•	the Home key is pressed on the keyboard while focus is on the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goTop is followed by the high level event Scroll.

In MWAPI, this event is called "GOTOP"


Long List


goBottom	goDown	goDownBig	goUp
goUpBig	Scroll


goUp Event

Applies to	See also

The low level event goUp occurs for a Long List control when the one of the following actions is performed:

•	the control's "one-up" scroll-button is clicked

•	the Cursor Up key is pressed on the keyboard while focus is on the first visible choice of the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goUp is followed by the high level event Scroll.

In MWAPI, this event is called "GOUP"


Long List


goBottom	goDown	goDownBig	goTop
goUpBig	Scroll


goUpBig Event

Applies to	See also

The low level event goUpBig occurs for a Long List control when the one of the following actions is performed:

•	the control's "page-up" scroll-button is clicked

•	the Page Up key is pressed on the keyboard while focus is on the first visible choice of the list.

Where the event is caused using the keyboard, the macro %%EvKey reports which, if any, of the modifier keys CTRL and SHIFT were also depressed. Where it is necessary to distinguish between keyboard and mouse action, $DATA(^$EVENT("KEY"))=1 for keyboard action.

The low level event goUpBig event is followed by high level event Scroll.

In MWAPI, this event is called "GOUPBIG"


Long List


goBottom	goDown	goDownBig	goTop
goUp	Scroll


help Event

Applies to

The low level event help occurs for an object when the function key F1 is pressed while the object has focus, or when the help-pointer is clicked on it. The help-pointer is obtained by clicking on the ? button that appears on the title bar of  a window that meets all the following conditions:

•	the window's Resizable property is false

•	the window's MinButton property is false

•	the window has a title bar; that is, either the Title property is not null, or the No Title Bar checkbox on the window's definition dialog is unchecked

•	action logic is defined for the help event for the window, or for at least one control on it; or at least one of these objects has a non-null HelpID property

For details of how to provide context help for objects without having to write action logic for this event, refer to the HelpID property.

When help is requested for a control on which no help action logic is provided and no HelpID property is set, a help event occurs for the window instead. In this case, the macro %%EvControl reports the name of the control for which the user requested help.

In MWAPI, this event is called "HELP"


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Radio Button	Scroll Bar	Spin Button
Tabbed Group	Text Box	Window


keyDown Event

Applies to	See also

The low level event keyDown occurs for an object when a key is pressed while the object has focus.

Information about the key can be obtained using the macro %%EvKey.

In the context of this event, the macro %%EvKey returns a string describing the meaning of the key (e.g. "F8", "ENTER", "ALT", "ESC").

Hint: It is sometimes more conventional to initiate processing when the key is released than when it is depressed. Consult Windows style guidelines or investigate the behavior of other common Windows applications.

In MWAPI, this event is called "KEYDOWN"


Combo Box	Document	Drop-down Combo	Generic
MDI Child	MDI Parent	Text Box	Window


char	keyUp	FilterIn


keyUp Event

Applies to	See also

The low level event keyDown occurs for an object when a key is released while the object has focus.

Information about the key in question can be obtained using the macro %%EvKey.

In the context of this event, the macro %%EvKey returns a string describing the meaning of the key (e.g. "F8", "ENTER", "ALT", "ESC").

Hint: It is sometimes more conventional to initiate processing when the key is released than when it is depressed. Consult Windows style guidelines or investigate the behavior of other common Windows applications.

In MWAPI, this event is called "KEYUP"


Combo Box	Document	Drop-down Combo	Generic
MDI Child	MDI Parent	Text Box	Window


char	keyDown	FilterIn


lostFocus Event

Applies to

The low level event lostFocus occurs when focus is transferred to another control in the window or to another window as a result of a user action.

The event occurs for a window when the user moves focus to another window within the Workstation application. If the user switches to another Windows task and then returns to a different window within the Workstation application, the lostFocus event does not occur until the time at which user focus returns to the new Workstation window.

The event occurs for a control when the user moves focus to another control within the same window. If the user moves first to another window and then returns to a different control on the original window, the lostFocus event does not occur until the return.

The low level event lostFocus event is followed by the high level event Exit.

Use of the %%NotOK macro will prevent the focus-switch, and so far as is possible will suppress other events that would normally have occurred if the focus-switch had proceeded.

In MWAPI, this event is called "UNFOCUS"


ActiveX	Button	Checkbox	Combo Box
Date	Document	Drop-down Combo	Drop-down List
Generic	List Box	Long List	MDI Child
MDI Parent	Radio Button	Spin Button	Tabbed Group
Text Box	Window


maximize Event

Applies to	See also

The low level event maximize occurs when, using standard Windows techniques, the user instructs a resizable window to occupy the entire display, or in the case of an MDI Child window the entire application area of its MDI Parent window.

In MWAPI, this event is called "MAX"


MDI Child	MDI Parent	Window


minimize	resize	restore


minimize Event

Applies to	See also

The low level event minimize occurs when, using standard Windows techniques, the user instructs a minimizable window to become minimized. An MDI Child window will minimize within its MDI Parent's application area. Any other window with a parent will minimize to the desktop. A window with no parent will disappear, remaining accessible via its entry on the Windows taskbar.

In MWAPI, this event is called "MIN"


MDI Child	MDI Parent	Window


maximize	resize	restore


move Event

Applies to

The low level event move occurs after a window's origin is moved by the user. Note that what the user considers as a resize operation on the top or left edge or from the upper-left corner results in both a move and a resize event. A move event also occurs when a window is minimized, restored or maximized.

In MWAPI, this event is called "MOVE"


MDI Child	MDI Parent	Window


ptrDown Event

Applies to	See also

The low level event ptrDown occurs for an object when a pointer button is pressed while the pointer is over it.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

Hint: action logic for the event ptrDown is typically related to dragging activity.
Any other action logic is often more appropriate when the event ptrUp occurs, or using the click or dblClick events.

In MWAPI, this event is called "PDOWN"


Generic	MDI Child	MDI Parent	Window


ptrDrag	ptrMove	ptrUp


ptrDrag Event

Applies to	See also

The low level event ptrDrag occurs for an object when the pointer is being moved while at least one pointer button is depressed. It occurs for the object that was under the pointer when the first pointer button was depressed, even if the pointer subsequently moves off the object.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

For a Scroll Bar control, the event occurs when the user depresses a pointer button over the scroll-thumb and moves the pointer. In this case, no information is present in %%EvPtrPos.

In MWAPI, this event is called "PDRAG"


Generic	MDI Child	MDI Parent	Scroll Bar
Window


ptrDown	ptrMove	ptrUp


ptrMove Event

Applies to	See also

The low level event ptrMove occurs when the pointer is being moved without any pointer buttons depressed. It occurs for the object under the pointer as it moves.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

In MWAPI, this event is called "PMOVE"


Generic	MDI Child	MDI Parent	Window


ptrDown	ptrDrag	ptrUp


ptrUp Event

Applies to	See also

The low level event ptrUp occurs when a pointer button is released.

The low level event ptrDrag occurs for an object when the pointer button is released. It occurs for the object that was under the pointer when the first pointer button was depressed, even if the pointer subsequently moves off the object.

Information about the position of the pointer and about the pointer-button(s) pressed can be obtained using the macros %%EvPtrButton, %%EvPtrPos and %%EvPtrState.

Hint: action logic for the event ptrDown is typically related to dragging activity.
Any other action logic is often more appropriate when the event ptrUp occurs, or using the click or dblClick events.

In MWAPI, this event is called "PUP"


Generic	MDI Child	MDI Parent	Window


ptrDown	ptrDrag	ptrMove


resize Event

Applies to	See also

The low level event resize occurs after a window's size is altered by the user. Note that what the user considers as a resize operation on the top or left edge or from the upper-left corner also results in a move event.

In MWAPI, this event is called "RESIZE"


MDI Child	MDI Parent	Window


maximize	minimize	restore


restore Event

Applies to	See also

The low level event restore occurs when, using standard Windows techniques, the user instructs a minimized or maximized window to be restored to its normal size.

In MWAPI, this event is called "RESTORE"


MDI Child	MDI Parent	Window


maximize	minimize	resize


select Event

Applies to

The low level event select occurs when

•	a Menu choice is selected,

•	a Button control is pushed

•	a Toolbar button is pushed

•	a selection is made for a component that offers choices

For Button and Radio Button components, the low level event select is followed by the high level event Push.

For a Scroll Bar component, the low level event select is followed by the high level event Scroll.

For a Check Box component, the low level event select is followed by the high level event Check.

For Drop-Down List, List Box and Long List components, the low level event select is followed by the high level event Choose.

Note: The high level events Check, Choose, and Push which follow some instances of this event also occur after a deselect event for the same control. In some cases it is simpler to locate action logic on the appropriate low level event. Where the control permits concurrent selection of more than one choice, multiple select events may occur as a result of a single user action.

In MWAPI, this event is called "SELECT"


Button	Checkbox	Combo Box	Date
Drop-down Combo	Drop-down List	List Box	Long List
Menu	Menu Choice	Radio Button	Scroll Bar
Spin Button	Toolbar Choice


timer Event

Applies to

The low level event timer occurs when the interval period of an active Timer control expires Timer Control. See details of the Timer control for more information.


Timer


Additional Reference Information

MSM-Workstation to MWAPI Name Map

External to Internal MSM-Workstation Names Map


MSM-Workstation to MWAPI Name Map

Property	Attribute	Get logic
Accelerator	ACCELERATOR
Active	ACTIVE
AppId	AID
AreaColor	ZACOLOR
BackColor	BCOLOR
BarSite	TBPOS
BarSize	TBSIZE
Border	FRAMED
ButtonHeight	BSIZE	$P(data,",",2)
ButtonWidth	BSIZE	$P(data,",")
Cancel	CANCEL
CancelButton	ZCANCELBUTTON
Changed	CHANGED
Color	COLOR
DateFormat	ZDATEFORMAT
DefaultButton	DEFBUTTON
Display	DISPLAY
DisplayOnly	CANCHANGE	'data
DrawType	DRAWTYPE
Enable	ENABLE
FillDirection	ROWCOL	$P(data,",",3)
FilterIn	FILTERIN
FontBold	FSTYLE	data["BOLD"
FontFace	FFACE
FontItalic	FSTYLE	data["ITALIC"
FontSize	FSIZE
FontUline	FSTYLE	data["ULINE"
ForeColor	FCOLOR
Hwnd	ID	$&MWAPI.GetHWND(data)
Icon	ICON
IconTitle	ITITLE
Interval	INTERVAL
Marker	MARKER
Max	SCROLLRANGE	$P(data,",",2)
MaxLength	CHARMAX
MaxSelect	SELECTMAX
Maximized	ZMAX
MenuBar	MENUBAR
Message	ZMESSAGE
Min	SCROLLRANGE	$P(data,",")
MinButton	ICONIFY
MinHeight	SIZEMIN	$P(data,",",2)
MinUnits	SIZEMIN	$P(data,",",3)
MinWidth	SIZEMIN	$P(data,",")
Minimized	MIN
Modal	MODAL
MonthFormat	ZMONTHS
NextControl	NEXTG
Parent	PARENT
PasswordChar	ZPASSWORDCHAR
Picture	RESOURCE
PictureHeight	ISIZE	$P(data,",",2)
PictureIndex	IMAGE
PictureWidth	ISIZE	$P(data,",")
Pointer	PTYPE
PosLeft	POS	$P(data,",")
PosTop	POS	$P(data,",",2)
PosUnits	POS	$P(data,",",3)
Resizable	RESIZE
RowCol	ROWCOL	$P(data,",")
RowColSize	ROWCOL	$P(data,",",2)
ScrollBars	SCROLL
ScrollDir	SCROLLDIR
ScrollHeight	SCROLL	$P(data,",",2)
ScrollHorz	SCROLL	$P(data,",")'=""
ScrollLarge	SCROLLBY	$P(data,",",2)
ScrollMax	SCROLLRANGE	$P(data,",",2)
ScrollMin	SCROLLRANGE	$P(data,",")
ScrollPosition	SCROLLPOS
ScrollSmall	SCROLLBY	$P(data,",")
ScrollUnits	SCROLL	$P(data,",",3)
ScrollVert	SCROLL	$P(data,",",2)'=""
ScrollWidth	SCROLL	$P(data,",")
SelStartLength	INSELECT
SelText	SELECTVAL
Separator	SEPARATOR
SizeHeight	SIZE	$P(data,",",2)
SizeUnits	SIZE	$P(data,",",3)
SizeWidth	SIZE	$P(data,",")
SpinStep	SCROLLBY
Style	STYLE
Submenu	SUBMENU
TBackColor	TBCOLOR
TFontBold	TFSTYLE	data["BOLD"
TFontFace	TFFACE
TFontItalic	TFSTYLE	data["ITALIC"
TFontSize	TFSIZE
TFontUline	TFSTYLE	data["ULINE"
TForeColor	TFCOLOR
TabStops	ZTABSTOPS
Tied	TIED
Title	TITLE
TitlePos	TPOS
ToolTip	ZTOOLTIP
TopRow	TOPSHOW
Type	TYPE
Units	UNITS
Value	VALUE
Visible	VISIBLE
WinHeight	SIZEWIN	$P(data,",",2)
WinUnits	SIZEWIN	$P(data,",",3)
WinWidth	SIZEWIN	$P(data,",")


External to Internal MSM-Workstation Names Map

External name	Internal name
ActiveX	Custom
AddNew	Ev30d22
Button	BUTTON
Check	Ev30v2
CheckBox	CHECK
Choice	Choice
Choice	MChoice
Choice	TBChoice
Choose	Ev30v3
Combo	LISTENTRY
Create	Ev10
Data	Data
Date	ZDATE
DeleteRecord	Ev30d24
Destroy	Ev50
Document	DOCUMENT
DropCombo	ZLISTCOMBO
DropDown	LISTBUTTON
Enter	Ev20
Error	Ev80
Exit	Ev40
Generic	GENERIC
GroupBox	FRAME
Label	LABEL
ListBox	LIST
Long List	LONGLIST
MDIchild	WINDOW:C
MDIparent	WINDOW:P
Menu	MENU
Modified	Ev30
MoveFirst	Ev30d12
MoveLast	Ev30d13
MoveNext	Ev30d10
MovePrevious	Ev30d11
MoveTo	Ev30d14
Picture	SYMBOL
Push	Ev30v1
RadioButton	RADIO
Scroll	Ev30v4
Scroll	SCROLL
SpinButton	Spin Button
TabbedGroup	TabbedGroup
TextBox	TEXT
Timer	Timer
Toolbar	Toolbar
UpdateControls	Ev30d20
UpdateRecord	Ev30d23
Validate	Ev30d21
Window	WINDOW
change	EvCHANGE
char	EvCHAR
click	EvCLICK
close	EvCLOSE
dblClick	EvDBLCLICK
deselect	EvDESELECT
fkeyDown	EvFKEYDOWN
fkeyUp	EvFKEYUP
goBottom	EvGOBOTTOM
goDown	EvGODOWN
goDownBig	EvGODOWNBIG
goTop	EvGOTOP
goUp	EvGOUP
goUpBig	EvGOUPBIG
gotFocus	EvFOCUS
help	EvHELP
keyDown	EvKEYDOWN
keyUp	EvKEYUP
lostFocus	EvUNFOCUS
maximize	EvMAX
minimize	EvMIN
move	EvMOVE
ptrDown	EvPDOWN
ptrDrag	EvPDRAG
ptrMove	EvPMOVE
ptrUp	EvPUP
resize	EvRESIZE
restore	EvRESTORE
select	EvSELECT
timer	EvTIMER


Data Types

Each property, as well as values passed to and returned from %% macros, has a data type. Data types are used to keep the definition of the property values brief. These shorthand terms can be reduced to the self-evident domains alphanumeric, string, integer, number, or null.

buttoncode	colorvalue	controlname
datafield	dateformat	externalresource
fontface	fontsize	identifier
keycode	markervalue	menuname
pointertype	truefalse	unittype


buttoncode

colorvalue

controlname

datafield

dateformat

externalresource

fontface

fontsize

identifier

keycode

markervalue

menuname

pointertype

truefalse

unittype


buttoncode

string

Code for a pointer button.

The following pointer button codes are returned as event information, and can be specified as FilterIn values:

Button Code	Description
[modifier+]... PB1	Primary button (normally left), with optional modifier key(s) from the list: ALT, CTRL, SHIFT.
[modifier+]    PB2	Middle mouse button, with optional modifier key(s) from the list: ALT, CTRL, SHIFT.
[modifier+]... PB3	Secondary button (normally right), with optional modifier key(s) from the list: ALT, CTRL, SHIFT.
An example of a FilterIn value is: ALT+PB1, PB3, CTRL+SHIFT+PB3

The event information returned for the click, dblClick, ptrDown, ptrDrag, ptrMove, and ptrUp events is listed in the following table.

Returned event information

Event Information Macro	Domain	Description
%%EvPtrButton	buttoncode	Pointer button that caused event, plus optional modifier key(s), ALT, CTRL, and SHIFT.
%%EvPtrState	buttoncode[,buttoncode]...	List of mouse buttons pressed.


colorvalue

integer,integer,integer

   or

null

A color is specified as three positive integer numbers, separated by commas. The values are the intensity levels of the three primary colors in the color-rendition system of the display: red, green and blue (in that order). The intensity levels for each color may vary between 0 and 65535 (inclusive).

"0,0,0" is black, "65535,0,0" is red, "0,65535,0" is green, "0,0,65535" is blue, "65535,65535,65535" is white.

Null indicates that the Windows default color is to be used.


controlname

string

The name of a control.  It must meet the syntax of a name identifier (not starting with a percent sign), and may not exceed 20 characters.


datafield

controlname.[linkfield@]…field

The controlname must refer to a data control component of the current window.

The field must be a column name defined in an SQL data dictionary.

Each linkfield must be a foreign key name defined in an SQL data dictionary.


dateformat

string

This specifies the format used by the Date control.  Possible values:

"[A]-[M]-[D]"	yy-Mmmmmm-dd

"[A]-[O]-[D]"	yy-Mmm-dd

"[D]-[M]-[A]"	dd-Mmmmmm-yy

"[D]-[M]-[Y]"	dd-Mmmmmm-yyyy

"[D]-[O]-[A]"	dd-Mmm-yy

"[D]-[O]-[Y]"	dd-Mmm-yyyy

"[M]-[D]-[A]"	Mmmmmm-dd-yy

"[M]-[D]-[Y]"	Mmmmmm-dd-yyyy

"[O]-[D]-[A]"	Mmm-dd-yy

"[O]-[D]-[Y]"	Mmm-dd-yyyy

"[Y]-[M]-[D]"	yyyy-Mmmmmm-dd

"[Y]-[O]-[D]"	yyyy-Mmm-dd

Key to codes:

[D]	day number

[M]	name of month, fully spelled

[O]	three letter abbreviation for name of month

[Y]	year number (all digits)

[A]	year number modulo 100


externalresource

Possible values:

F,file

R,resourcefile

file is a string naming a Windows file. It may include an absolute path, or a path relative to the home directory of the Workstation application. Based on the attribute for which the extresource is used, the file may be .BMP, .CUR, .ICO, or .EXE type. The attribute context may supply a default extension. If the file is .EXE type, an icon is extracted from it. If the file type is .CUR, .ICO, or .EXE,  the name may be followed by ","index, where index is a positive integer specifying which resource is to be used. If no index is specified, the first suitable one is used.

resourcefile takes the following form:

filename,resourceid[,resourcetype]

where filename is a string naming a Windows file, optionally including an absolute or relative path as described above. The file extension is usually .EXE or .DLL, and resourceid is the integer ID of the desired resource. The attribute context implies a default resource type, but the resourcetype can be specified as B, C, or I for bitmap, cursor, or icon, respectively.

An attribute that uses the extresource domain may not support all resource types.


fontface

string

Possible values:

"M,DEFAULT"	system
"M,FIXED"	fixed
"M,SANS"	san serif
"M,SERIF"	serif
fontname	any font
Where fontname is the name of other fonts that may be installed in the end-user's PC.  Installed fonts are available in ^$DI($PD,"TYPEFACE").


fontsize

integer[.integer]

Font size in points, where 1 point is 1/72 inches. A size of 0 indicates a scalable type face within the ^$DISPLAY attribute TYPEFACE; everywhere else, an explicit size must be given.  The value must be a positive number, possibly with a decimal fraction.


identifier

[%]alphanumeric

Identifier, maximum length 20 characters.


keycode

string

Code for a keyboard key.

When key events (char, keyDown, keyUp) are enabled via the normal event mechanism, key codes are returned in %%EvKey to report keys pressed as keycodes, or are specified to the FilterIn event specification attribute. For the char event the code is an ASCII character. For keyDown and keyUp, the following keycodes are recognized:

BACKSPC	F9	NUM9	BREAK
F10	NUMDEC	CAPSLOCK	F11
NUMDIV	DEL	F12	NUMENTER
DOWN	HOME	NUMLOCK	END
INS	NUMMINUS	ENTER	LEFT
NUMMULT	ESC	NUM0	NUMPLUS
F1	NUM1	PAGEDOWN	F2
NUM2	PAGEUP	F3	NUM3
PAUSE	F4	NUM4	RIGHT
F5	NUM5	SCRLLOCK	F6
NUM6	TAB	F7	NUM7
UP	F8	NUM8

The following three keys can modify the state of other keys pressed:

ALT	CTRL	SHIFT

A key pressed together with a state modifier is specified or returned using the following style of key code:

ALT+CTRL+B

A keycode can therefore be either a simple code; or a code plus one or more state modifiers all joined by + signs.


markervalue

string

Possible values:

"M,BULLET"	A bullet.
"M,CHECK"	A checkmark.
"M,DIAMOND"	A diamond.
externalresource	A predefined symbol or bitmap to appear on the left of a menu choice.


menuname

identifier

Menu name.  Data of this type must meet the syntax of a name (possibly starting with a percent sign and not exceeding 32 characters), or must be a single digit, or must start with a digit, followed by a name (not starting with a percent sign, and not exceeding 32 characters).


pointertype

string

Indicates the representation of the pointing device (mouse) to be used in various contexts.

Possible values:

"M,CROSS"	Crosshair

"M,IBEAM"	I-beam

"M,WAIT"	Hourglass

"Z,POINTER"	Pointer


truefalse

A Boolean value:

1	true (yes)

0	false (no)


unittype

string

A specification of the units to be used for various sizing and positioning purposes.

Possible values:

"CHAR"[,string]	The character width is the average width of the specified character string in the font in use (the "basis font"); if no character is specified, the width is the maximum character width in the font.  Character height is the line height of that font, including leading.
"PIXEL"	One unit is one pixel.
"POINT"	One unit is one point. One point is 1/72 inches.
"REL"[,hscale,vscale]	The units are relative to the size of a parent window's viewport on its creation, unless the object is a window whose TIED attribute is 0, when the units are relative to the size of the display. The horizontal scale hscale and the vertical scale vscale are integers greater than 0 (zero), defining the value at which a relative-scaled dimension reaches a scaling ration of 1:1. For example, using units of "REL,60,40", a size of "30,40" would produce an object of the same height as its parent but half its width. The default for both hscale and vscale is 100.
"ZDLG"	The units are Windows dialog units. This is a unit based on the average width of the current Windows default font. The unit is 0.25 characters wide and 0.125 characters high.