SAS Companion for the OpenVMS Operating Environment

Issuing DCL Commands during a SAS Session

You can issue DCL commands from within a SAS program by using either the SAS X statement (in any mode of SAS operation) or the SAS X command in interactive and non-interactive mode. Depending on which form of the X statement (or X command) that you use, you can either issue a single DCL command or you can spawn an OpenVMS subprocess from which you can issue multiple DCL commands.

System administrators can specify the NOXCMD option to prevent users from issuing any DCL commands.

You can use the SYSTASK statement to execute DCL commands asynchronously. For more information, see SYSTASK and WAITFOR.

Note: In general, the X statement and the X command are equivalent. The following discussion illustrates the X statement but points out any differences that would apply to the X command. [cautionend]

Using the X Statement to Issue a Single DCL Command

Use the following form of the X statement to issue one DCL command:

X <'>DCL-command <'>;

The DCL-command is passed to the operating environment and executed. If errors occur, the appropriate error messages are displayed.

In interactive line mode, after the command executes you are prompted for another SAS statement. For example, in Issuing DCL Command with the X Statement the X statement is submitted from an interactive line mode session and executes the DIRECTORY DCL command. The contents of the current directory appear on the display, and then the SAS System prompts the user for another SAS statement.

Issuing DCL Command with the X Statement

[IMAGE]

In Version 8 of the SAS System, the XLOG option specifies to write the output from the X command to the SAS log. However, XLOG is not the default. When XLOG is not turned on, the output from the X command is displayed in the invocation window. The XCMDWIN option determines whether X command output is displayed in a DECTERM window or in the invocation window. XCMDWIN is on by default. For more details on the XCMDWIN option, see XCMDWIN.

Note: You can also use the VMS function, the CALL SYSTEM routine, or the %SYSEXEC macro statement to issue single DCL commands. For details, see the function VMS, the routine CALL SYSTEM, and Macro Statements. [cautionend]

How OpenVMS Processes the DCL Command

It is important to understand how OpenVMS processes the DCL command that you issue with the X statement. A DCL command can be executed in either the OpenVMS parent process (the OpenVMS process in which your SAS session is running) or in an OpenVMS subprocess. For some DCL commands, such as DIR or COPY, it makes little difference whether it executes in the parent process or a subprocess. However, for DCL commands such as DEFINE and MOUNT, the process in which they are executed is significant. The following DCL commands are executed in the parent process:

ALLOCATE DEASSIGN

ASSIGN DEFINE

ATTACH MOUNT

DEALLOCATE SET DEFAULT

The results of these DCL commands (for example, OpenVMS logical names, tape mounts, and so on) are available to the OpenVMS parent process. All other DCL commands are executed in a subprocess. Therefore, when you use an X statement to submit these commands from SAS, their results are not available to the OpenVMS parent process in which SAS is running. For example, the following DCL command has no effect in the OpenVMS parent process:

x 'set protection=o:d/default';

This command is executed in a subprocess, so the default protection for the OpenVMS process in which SAS is running does not change.

The XTIMEOUT= system option determines whether a subprocess remains in existence after a DCL command has been executed and control has been returned to SAS. (See the system option XTIMEOUT=.) By default, the same subprocess is used during the entire SAS session. However, when any of the commands in the previous list are executed, the following actions occur regardless of the value of the XTIMEOUT= system option:

The subprocess is deleted.
A new subprocess is started when the next X statement is issued.

These actions ensure that the subprocess always accurately reflects any OpenVMS logical names or defaults that were set in the parent process.

Executing a DCL Command Using Procedure Syntax

You can also use procedure syntax to issue a single DCL command. However, the X command and the X statement are more versatile because they each allow you to specify parameters and qualifiers for a DCL command; with procedure syntax, you cannot specify parameters or qualifiers.

When you ask the SAS System to run a procedure--for example, a procedure named MYPROC--SAS first tries to load the Version 8 procedure named MYPROC. If the procedure does not exist, then SAS searches for either an image named MYPROC.EXE in your current directory or the OpenVMS logical name MYPROC. If the image MYPROC.EXE is found in your current directory, then SAS issues the MYPROC DCL command via a subprocess. If the OpenVMS logical name exists for MYPROC, then SAS translates the logical name and searches for the image that it points to. If it finds the image, it issues the MYPROC DCL command via a subprocess. If it does not find the image in your current directory, and if no OpenVMS logical name is assigned to the image or if the logical name does not point to an image that exists, then you receive the following error message:

ERROR: Procedure MYPROC not found.

In this example, note that if the SAS System issues the MYPROC command, you must either define a symbol called MYPROC or have a DCL verb defined for MYPROC. Otherwise, you receive the error message

%DCL-W-IVVERB, unrecognized command verb - 
               check validity and spelling.

The most useful application of using procedure syntax to issue a DCL command is executing a stand-alone image. Suppose you have a program called CALC.EXE in your current directory which performs arithmetic calculations, and you want to run it from within your SAS session. First, define a symbol with the same name as the image you want to invoke. In this case, you define CALC as the following:

$ CALC := RUN MYDISK$:[MYDIR]CALC.EXE

Then, from your SAS session, run your program using a procedure statement. The following is an example:

$ SAS8
   . . . Log notes . . .
1? proc calc;
2? run;
    Input the calculation: 2+2=
        4.000000
3? endsas;

Now suppose that the CALC.EXE image is located in a different directory. The symbol for CALC must still be defined, as in the previous example, but you also need an OpenVMS logical name that points to the actual file. The following is an example:

$ DEFINE CALC MYDISK$:[MYPLAYPEN.SUBDIR]CALC.EXE

Now SAS can find the image that is defined by the OpenVMS logical name CALC and can issue the CALC DCL command.

Note: You can accomplish the same thing by issuing the following X command:

$ SAS8
   . . . Log notes . . .
  1? x 'run calc.exe';
       Input the calculation: 2+2=
               4.000000
  2? endsas;

Using the X Statement to Issue Several DCL Commands

You can use the X statement to spawn an OpenVMS subprocess from which you can enter multiple DCL commands. In interactive line mode or noninteractive mode, use either of the following forms of the X statement:

x '';
x;

These statements make it easy for you to manage files and devices from within your SAS session. When you use these forms of the X statement, you receive the following message:

Type LOGOFF to return to SAS.

During the subprocess, you enter DCL commands in response to the following prompt:

SAS_$

In Version 8, the SAS_$ prompt appears in the terminal window from where you invoked SAS.

In Version 8, the XCMDWIN option specifies whether to create a DECTERM window from which the spawned subprocess reads its input and writes it output. This option applies only in windowing mode. For more information about the XCMDWIN option, see XCMDWIN.

Note: If you issue DCL commands that affect or describe process attributes, be aware that these commands pertain to the subprocess, not to the process in which SAS is running. For example, if you define OpenVMS logical names within the subprocess, these logical names are not available to the OpenVMS parent process in which SAS is running. Therefore, it is usually best to define logical names with the form of the X statement described in Using the X Statement to Issue a Single DCL Command. [cautionend]

To return to the SAS session, enter LOGOFF in response to the SAS_$ prompt.

SAS System Options That Affect Subprocesses

The following SAS system options affect the subprocess environment that is created by an X statement or X command:

XCMDWIN: in windowing mode, determines whether a separate DECTERM window is created. For details about the XCMDWIN option, see XCMDWIN.
XKEYPAD: affects the keypad definitions that are used in the subprocess. For more information, see the system option XKEYPAD.
XLOGICAL: affects the logical names that are used in the subprocess. For more information, see the system option XLOGICAL.
XOUTPUT: affects the display of output from the X command. For more information, see the system option XOUTPUT.
XSYMBOL: affects the Command Line Interpreter (CLI) symbols that are used in the subprocess. For more information, see the system option XSYMBOL.
XTIMEOUT=: affects how long a subprocess exists after control is returned to the SAS System. For more information, see the system option XTIMEOUT=.

Note: These options take effect only after a subprocess is spawned. [cautionend]

Issuing OpenVMS Functions from Captive Accounts

If you run SAS from a captive OpenVMS account, then you cannot access the DCL command level. Nevertheless, you can use the X statement or the X command to issue a number of general-purpose OpenVMS functions.

A captive OpenVMS account is under the control of the login command procedure. It cannot access the DCL command level, nor can it spawn a subprocess. Captive accounts are set up in the AUTHORIZE system utility by specifying the option /FLAGS=CAPTIVE.

As explained in Issuing DCL Commands during a SAS Session, if you run SAS from a noncaptive account, you can issue DCL commands by means of the SAS X command, X statement, VMS function, or CALL SYSTEM routine. For most DCL commands, each of these methods spawns an OpenVMS subprocess, and the subprocess executes the DCL command that you specified. (The exceptions are the commands listed in How OpenVMS Processes the DCL Command, which execute in the OpenVMS parent process. Also note that only the X statement and the X command can be used to spawn a subprocess from which you can issue multiple DCL commands. The other methods can be used only to issue single DCL commands.)

In general, if you issue one of these SAS commands, statements, functions, or CALL routines from a captive account, a message informs you that a subprocess cannot be spawned from a captive account; the command requested is denied, and control of the process is returned to SAS.

However, several general-purpose OpenVMS functions can be called from within the same process that is running the SAS System. Therefore, even if you are running SAS from a captive account, you can use the FINDFILE function (for example) to see a directory listing of the files in a certain directory. The results are the same as if you had issued an X command from a noncaptive account. Similarly, you can use the DELETE function from a captive account to delete a file from a particular directory structure, and you can use the RENAME function to rename a file.

The following OpenVMS functions are available in the SAS System and can be called from a captive account:

DELETE: deletes a file. For more information, see the function DELETE.
FINDFILE: searches a directory for a file. For more information, see the function FINDFILE.
GETDVI: returns a specified item of information from a device. For more information, see the function GETDVI.
GETJPI: retrieves job-process information. For more information, see the function GETJPI.
GETLOG: returns the value of a DCL logical name. For more information, see the function GETLOG.
GETMSG: translates an OpenVMS error code into text. For more information, see the function GETMSG.
GETQUOTA: retrieves disk quota information. For more information, see the function GETQUOTA.
GETSYM: returns the value of a DCL symbol. For more information, see the function GETSYM.
GETTERM: returns the characteristics of your terminal device. For more information, see the function GETTERM.
PUTSYM: creates a DCL symbol in your process. For more information, see the function PUTSYM.
RENAME: renames a file. For more information, see the function RENAME.
SETTERM: modifies a characteristic of your terminal device. For more information, see the function SETTERM.
TERMIN: allows simple input from SYS$INPUT. For more information, see the function TERMIN.
TERMOUT: allows simple output to SYS$OUTPUT. For more information, see the function TERMOUT.
TTCLOSE: closes a channel that was previously assigned by TTOPEN. For more information, see the function TTCLOSE.
TTCONTRL: modifies characteristics of a channel that was previously assigned by TTOPEN. For more information, see the function TTCONTRL.
TTOPEN: assigns an I/O channel to a terminal. For more information, see the function TTOPEN.
TTREAD: reads characters from the channel that was assigned by TTOPEN. For more information, see the function TTREAD
TTWRITE: writes characters to the channel that was assigned by TTOPEN. For more information, see the function TTWRITE.

Misuse of these functions can occur only if your system has insufficient file-protection and directory-protection schemes. The SAS System honors all protection schemes. For example, if you cannot delete a file from a noncaptive account, then you cannot delete that file from a captive account either.

Note: System administrators can restrict users from calling the above functions from captive accounts by either renaming or deleting the appropriate executables or by making the NOXCMD option the default. The executables that are associated with the above functions are stored in the directory SAS$EXTENSION:[LOAD]. [cautionend]

Chapter Contents
Previous
Next
Top of Page

ALLOCATE	DEASSIGN
ASSIGN	DEFINE
ATTACH	MOUNT
DEALLOCATE	SET DEFAULT