Getting Started with SAS under OpenVMS

Issuing DCL Commands during a SAS Session

Introduction to Issuing DCL Commands within SAS

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 noninteractive 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.

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

In previous releases of SAS, if you wanted to issue a DCL command for ODS-5 files, you had to issue the SET PROCESS command to set the parse_style to extended. To start SAS, the parse_style has to be set to extended, which processes both ODS-5 and ODS-2 files. Therefore, you no longer need to switch between the extended and traditional parse_style values.

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

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

Issuing a Single DCL Command Using the X Statement

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 the following display 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 SAS prompts the user for another SAS statement.

Issuing DCL Commands with the X Statement

[Issuing DCL Commands with the X Statement]

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 information about the XCMDWIN option, see XCMDWIN System Option: OpenVMS.

Note: You can also use the VMS function, the CALL SYSTEM routine, or the %SYSEXEC macro statement to issue single DCL commands. For information, see the function VMS Function: OpenVMS and the routine CALL SYSTEM Routine: OpenVMS. [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, 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= System Option: OpenVMS.) 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 SAS to run a procedure (for example, a procedure named MYPROC), SAS first tries to load the 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 SAS 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 that 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:

$ SAS92
   . . . 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:

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

[cautionend]

Issuing Several DCL Commands Using the X Statement

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;

(For more information, see X Statement: OpenVMS.)

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_$

The SAS_$ prompt appears in the terminal window from where you invoked SAS.

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 System Option: OpenVMS. If you use /NOXCMDWIN, the window from which SAS was invoked will be used for both input and output for the subprocess.

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 Issuing a Single DCL Command Using the X Statement. [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 more information, see XCMDWIN System Option: OpenVMS.
XKEYPAD: affects which keypad settings the subprocess uses. For more information, see XKEYPAD System Option: OpenVMS.
XLOG: affects whether the output from the X command is displayed in the SAS log file. For more information, see XLOG System Option: OpenVMS.
XLOGICAL: affects which process-level logical names the subprocess uses. For more information, see XLOGICAL System Option: OpenVMS.
XOUTPUT: affects the display of output from the X command. For more information, see XOUTPUT System Option: OpenVMS.
XSYMBOL: affects the Command Line Interpreter (CLI) symbols that are used in the subprocess. For more information, see XSYMBOL System Option: OpenVMS.
XTIMEOUT=: affects the amount of time a subprocess exists or remains inactive before control is returned to SAS. For more information, see XTIMEOUT= System Option: OpenVMS.

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

Issuing OpenVMS Functions from Captive Accounts

Limitations of Using a Captive Account

If you run SAS from a captive OpenVMS account, then you cannot access the DCL command level, nor can you spawn subprocesses. A captive OpenVMS account is under the control of the login command procedure. SAS functionalities that require a detached process will not work under a captive account. The following functionalities require either a detached process or a subprocess, so they are not available from a captive account:

host-specific commands that are executed asynchronously using the SYSTASK statement
the PIPE device in the FILENAME statement
remote signons using SAS/CONNECT
the SAS Session Manager
X commands that cannot be executed in the current process

Captive accounts are set up in the AUTHORIZE system utility by specifying the option /FLAGS=CAPTIVE.

Difference between Captive and Noncaptive Accounts

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, SYSTASK statement, 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. Nevertheless, you can use the X statement or the X command to issue a number of general-purpose OpenVMS functions. For more information, see Functions Available from a Captive Account.

Functions Available from a Captive Account

Several general-purpose OpenVMS functions can be called from within the same process that is running SAS. 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 SAS and can be called from a captive account:

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

Misuse of these functions can occur only if your system has insufficient file-protection and directory-protection schemes. SAS 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]

Top of Page