dsm(1) — Commands

Name

dsm − The dsm command accepts a series of command line options including a MUMPS routine entry reference.

Syntax

dsm [ options ]

Description

The following is the format of the DSM command line:

% dsm [ options ]

The following rules apply to the command line:

•Command elements in brackets are optional.

•All punctuation (minus sign, space) is necessary to separate the components of the command line.

If the optional routine entry reference is present on the DSM command line, then DSM runs in application mode. DSM executes the routine starting at the first line, or if you include a label, at the label you specify. For more information about routine entry references, see the Introduction to DSM.

The following are some of the uses of the dsm command line options:

•Specifying the global directory that you want to access

•Enabling and disabling routine interrupts by Ctrl/C

•Specifying a DSM environment

•Changing the default size of your source and precompiled routine buffers, the local symbol table, and the call stack

The OSF/1 operating system supports aliases. You can use aliases to redefine the dsm command. For example:

% alias dsm ’dsm -e cenable’

Then if you want to disable Ctrl/C recognition, you can enter the following:

% dsm -d cenable[Return]

Options

DSM supports default command line options on a configurationwide basis. For more information, see the Installation and Management Guide.

The following list describes the dsm command line options.

-a entryrefThe -a entryref option lets you enter an application program name and run DSM in application mode. Note that entryref is a valid MUMPS routine entry reference and must be enclosed in quotation marks (single or double).

-b numberThe -b number option establishes the size, in bytes, of the DSM source routine buffer and precompiled routine buffer. The default value of number is 14000 bytes (16384 when you use -M) and the maximum value is 65535 bytes. The source routine buffer stores the lines of a routine written in the DSM language as ASCII character strings. The precompiled routine buffer stores routines in precompiled format, as described in Chapter 1.

-d BINARY_OPTThe -d BINARY_OPT option disables a binary option. The BINARY_OPT options are described in the -e BINARY_OPT section.

-e BINARY_OPTThe -e BINARY_OPT option enables a binary option. BINARY_OPT can be one of the following:

•byp[as]

The byp[as] binary option disables all types of security checking, protection verification on volume set globals, protected external calls, global creation in other UCIs, and use of the %SETUCI external routine. The default is to have protection verification enabled.

Only the DSM environment manager can use the byp[as] option. For more information about access control methods, see the Installation and Management Guide.

•cen[able]

The cen[able] binary option enables Ctrl/C recognition.

•cha[in]

The cha[in] binary option enables UCI chaining. For more information about UCI chaining, see the Database Operations Guide.

•das[l_customize]

The das[l_customize] option argument allows you to recompile the DASL software.

•nou[ndefined]

The nou[ndefined] binary option enables DSM to return the null string if you attempt to retrieve the value of an undefined variable.

The nou[ndefined] option argument aids in the conversion of programs written in MUMPS dialects before ANSI Standard MUMPS was used. This extension modifies the way in which DSM handles references to undefined local or global variables. With the extension disabled, attempts to retrieve the value of an undefined variable result in the following program error:

%DSM-E-UNDEF, undefined variable or label

Subscripted variables that contain subscripts whose value is null are normally not considered legal variable names under DSM. Attempts to reference these values return the following program error:

%DSM-E-NULLSUBSCR, null subscript

When the extension is enabled, attempts to retrieve the value of an undefined variable always return the null string. Also, the value of a subscripted local or global variable is null if one of its subscript values is null.

The MUMPS extension is enabled by running DSM with the nou[ndefined] binary option. For example:

% dsm -e nou[Return]

You can also alter the state of the nou[ndefined] option argument while running a MUMPS program by calling the $$NOUNDEF^%SYSUTL supplied extrinsic function. Use the following call procedure:

S A=$$NOUNDEF^%SYSUTL(p1)

where:

p1	is 0 to disable the NOUNDEF extension
p1	is 1 to enable the NOUNDEF extension

•typ[eahead]

The typ[eahead] binary option enables typeahead regardless of the READ command syntax. It overrides the following DSM-11 compatible type-ahead behavior:

•The READ command with a literal (READ "Prompt: ",X) causes the type-ahead buffer to be purged.

•The READ command without a prompt (READ X) does not purge the type-ahead buffer.

The typ[eahead] binary option always allows typeahead regardless of the form of the READ command. When typeahead is enabled:

•You can issue a USE ’terminal’:[NO]TYPE to selectively enable or disable typeahead.

•USE ’terminal’:TYPE is the default.

The default is to have typeahead disabled. You can also select the type-ahead control mode with the USE command [NO]READPFLU parameter. For more information about the [NO]READPFLU and the [NO]TYPE parameters, see Chapter 9.

-g UCI,VOLThe -g UCI,VOL option allows DSM users to gain access to the specified UCI and volume set (VOL). The UCI name must consist of three uppercase alphabetic characters and must reside on the specified volume set (VOL).

The VOL argument selects the volume set to access. The volume set name must consist of three uppercase alphabetic characters and must be mounted in the current configuration.

-r UCI,VOLThe -r UCI,VOL option lets you select a nondefault routine directory. This qualifier allows you to separate the UCI and volume set that your globals are located in from the UCI and volume set that your routines are located in.

By default, your routines and globals are located in the same UCI and volume set. The volume set name and UCI name must consist of three uppercase alphabetic characters. The volume set must be mounted in your current configuration. The UCI must reside in the volume set specified by VOL.

-s numberThe -s number option changes the size of the DSM call stack. The default value of number is 16384 bytes. The size of the stack determines how many call frames an application can keep active at the same time; that is, how many nested DO statements, FOR commands, or XECUTE commands can be used. If the stack is too small, DSM displays the %DSM-E-STKOVF error message.

For more information about the DSM call stack, see Chapter 6.

-t numberThe -t number option allows you to increase or decrease the size of your local symbol table. The local symbol table contains an entry for all defined local variables, subscripted or unsubscripted. The default size of the local symbol table is 102400 bytes. The minimum size of the local symbol table is 4096.
Your virtual address limit determines the maximum size of your local symbol table.

-B numberThe -B number option equates a control character with the BREAK command, where number can be any ASCII value of 1 to 31, excluding the following:

3	Ctrl/C
17	Ctrl/Q
19	Ctrl/S

When you press the specified control character in programmer mode, DSM stops program execution before the start of the next executed command and enters break mode.

For more information about how to use the -B number command line option, see Chapter 4.

-D stringThe -D string option passes a value to DSM in the % variable. You must enclose the string you specify in quotation marks. The -D string option allows a shell script to pass a value to a DSM routine in the MUMPS % variable.

-E envnmThe -E envnm option allows users to access a configuration running in any environment on the system. The envnm argument is the OSF/1 login name of the DSM environment manager’s account.

-MThe -M option allows access to DSM in manager mode when no configuration is running, and allows use of System Utilities. The -M command line option has two effects:

•If no DSM configuration is running, you can run DSM with the -M command line option to build and start up a configuration.

•When you are logged in with -M, you can perform privileged DSM manager functions.

The following option is enforced by the -M command line option, regardless of what you enter:

UCI 1 in volume set 0 for all globals and routines

The following default minimum values are also used:

•-t 102400

•-s 16384

•-b 18000

If you enter higher values for these qualifiers, DSM uses these values. Note that once you enable the -M option, you cannot disable it.

-P stringThe -P option allows you to set the default prompt (>). The string argument must be enclosed in quotation marks and can contain the substitution characters described in the following table and can contain free text.

Substitution Character	Description
%g	Displays the current global directory (Ignored if a configuration is not running.)
%r	Displays the current routine directory (Ignored if a configuration is not running.)
%e	Displays the environment name
%n	Displays the DECnet[TM] node name

The maximum prompt length after substitution is 30 characters. Additional characters are truncated. The -P command line option has the same effect as the %PROMPT external routine. If you specified %g or %r, the %SETUCI external routine automatically updates the prompt with the new global directory or routine directory.

You can combine free text with any of the substitution characters described in the previous table. The substitution characters must be entered as lowercase characters. Free text is displayed as it is entered.

The -P option is ignored if you run DSM in application mode.

The following are examples of how to use the -P option:

% dsm -P "%n >"[Return]
nurse >
% dsm -P "[%g][%r] >"[Return]
[PHA,EMP][EMP,EMP] >
% dsm -P "Inventory >"[Return]
Inventory >

Examples

The following example runs DSM in programmer mode, enables typeahead, disables Ctrl/C recognition, sets the global directory to DBS,BJL, sets the routine directory to REB,KMF, and accesses a configuration running in the billing environment.

% dsm -e type -d cen -g DBS,BJL -r REB,KMF -E billing[Return]

The following example defines an alias for accessing a DSM application.

% alias billing ’dsm -a "^MENU" -E billing’[Return]

Note that alias is available only under the csh shell.

The following example overrides the default values for source buffer size and symbol table size.