OpenVMS DCL Dictionary

Document revision date: 19 July 1999

OpenVMS DCL Dictionary

Contents

Index

CANCEL

Cancels wakeup requests for a specified process, including wakeup requests scheduled with either the RUN command or the $SCHDWK system service.
Requires one of the following:

Ownership of the process.
GROUP privilege to cancel scheduled wakeup requests for processes in the same group but not owned by you.
WORLD privilege to cancel scheduled wakeup requests for any process in the system.

Format

CANCEL [[node-name::]process-name]

Parameters

node-name::
The name of the node on which the specified process is running.
You cannot specify a node name on a different OpenVMS Cluster system from the current process.
process-name
The name of the process for which wakeup requests are to be canceled. The process name can have up to 15 alphanumeric characters.
The specified process must be in the same group as the current process.

Description

The CANCEL command cancels scheduled wakeup requests for the specified process.
The CANCEL command does not delete the specified process. If the process is executing an image when the CANCEL command is issued for it, the process hibernates instead of exiting after the image completes execution.
To delete a hibernating process for which wakeup requests have been canceled, use the STOP command. You can determine whether a subprocess has been deleted by entering the SHOW PROCESS command with the /SUBPROCESSES qualifier.
A local process name can look like a remote process name. Therefore, if you specify ATHENS::SMITH, the system checks for a process named ATHENS::SMITH on the local node before checking node ATHENS for a process named SMITH.
You also can use the /IDENTIFICATION=pid qualifier to specify a process name. If you use the /IDENTIFICATION qualifier and the process-name parameter together, the qualifier overrides the parameter. If you do not specify either the process-name parameter or the /IDENTIFICATION qualifier, the CANCEL command cancels scheduled wakeup requests for the current (that is, the issuing) process.

Qualifier

/IDENTIFICATION=pid
Identifies the process by its process identification (PID). You can omit leading zeros when you specify the PID.

Examples

#1
$ CANCEL CALENDAR

The CANCEL command in this example cancels a wakeup request for a process named CALENDAR (which continues to hibernate until it is deleted with the STOP command).

#2
$ RUN/SCHEDULE=14:00 STATUS %RUN-S-PROC_ID, identification of created process is 0013012A . . . $ CANCEL/IDENTIFICATION=13012A

The RUN command in this example creates a process to execute the image STATUS. The process hibernates and is scheduled to be awakened at 14:00. Before the process is awakened, the CANCEL command cancels the wakeup request.

#3
$ RUN/PROCESS_NAME=LIBRA/INTERVAL=1:00 LIBRA %RUN-S-PROC_ID, identification of created process is 00130027 . . . $ CANCEL LIBRA $ STOP LIBRA

The RUN command in this example creates a subprocess named LIBRA to execute the image LIBRA.EXE at hourly intervals.
Subsequently, the CANCEL command cancels the wakeup request. The process continues to exist, but in a state of hibernation, until the STOP command deletes it.

CLOSE

Closes a file opened with the OPEN command and deassigns the associated logical name.

Format

CLOSE logical-name[:]

Parameter

logical-name[:]
Specifies the logical name assigned to the file when it was opened with the OPEN command.

Description

Files that are opened for reading or writing at the command level remain open until closed with the CLOSE command, or until the process terminates. If a command procedure that opens a file terminates without closing the open file, the file remains open; the command interpreter does not automatically close it.

Qualifiers

/ERROR=label
Specifies a label in the command procedure to receive control if the close operation results in an error. Overrides any ON condition action specified. If an error occurs and the target label is successfully given control, the global symbol $STATUS retains the code for the error that caused the error path to be taken.
/LOG (default)

/NOLOG
Generates a warning message when you attempt to close a file that was not opened by DCL. If you specify the /ERROR qualifier, the /LOG qualifier has no effect. If the file has not been opened by DCL, the error branch is taken and no message is displayed.

Examples

#1
$ OPEN/READ INPUT_FILE TEST.DAT $ READ_LOOP: $ READ/END_OF_FILE=NO_MORE INPUT_FILE DATA_LINE . . . $ GOTO READ_LOOP $ NO_MORE: $ CLOSE INPUT_FILE

The OPEN command in this example opens the file TEST.DAT and assigns it the logical name of INPUT_FILE. The /END_OF_FILE qualifier on the READ command requests that, when the end-of-file (EOF) is reached, the command interpreter should transfer control to the line at the label NO_MORE. The CLOSE command closes the input file.

#2
$ @READFILE `[Ctrl/Y]` $ STOP $ SHOW LOGICAL/PROCESS . . . "INFILE" = "_DB1" "OUTFILE" = "_DB1" $ CLOSE INFILE $ CLOSE OUTFILE

In this example, pressing Ctrl/Y interrupts the execution of the command procedure READFILE.COM. Then, the STOP command stops the procedure. The SHOW LOGICAL/PROCESS command displays the names that currently exist in the process logical name table. Among the names listed are the logical names INFILE and OUTFILE, assigned by OPEN commands in the procedure READFILE.COM.
The CLOSE commands close these files and deassign the logical names.

CONNECT

Connects your physical terminal to a virtual terminal that is connected to another process.
You must connect to a virtual terminal that is connected to a process with your user identification code (UIC). No other physical terminals may be connected to the virtual terminal.

Format

CONNECT virtual-terminal-name

Parameter

virtual-terminal-name
Specifies the name of the virtual terminal to which you are connecting. A virtual terminal name always begins with the letters VTA. To determine the name of the virtual terminal that is connected to a process, enter the SHOW USERS command.

Description

The CONNECT command connects you to a separate process, as opposed to the SPAWN and ATTACH commands, which create and attach subprocesses.
The CONNECT command is useful when you are logged in to the system using telecommunications lines. If there is noise over the line and you lose the carrier signal, your process does not terminate. After you log in again, you can reconnect to the original process and log out of your second process.
To use the CONNECT command, the virtual terminal feature must be enabled for your system with the System Manager utility (SYSMAN) on OpenVMS Alpha systems and the System Generation utility (SYSGEN) on OpenVMS VAX systems.
If virtual terminals are allowed on your system, use the SET TERMINAL/DISCONNECT/PERMANENT command to enable the virtual terminal characteristic for a particular physical terminal. When you enable this characteristic, a virtual terminal is created when a user logs in to the physical terminal. The physical terminal is connected to the virtual terminal, which is in turn connected to the process.
For new virtual terminals, you must first set the TT2$V_DISCONNECT bit in the TTY_DEFCHAR2 system parameter and reboot the system. This is done by creating the virtual device VTA0: using the ttdriver. For example, on Alpha:
$ MCR SYSMAN IO CONNECT/NOADAPTER - _$ /DRIVER=SYS$LOADABLE_IMAGES:SYS$TTDRIVER VTA0:
On VAX:
$ MCR SYSGEN CONNECT /NOADAPTER/DRIVER=TTDRIVER VTA0:
When the connection between the physical terminal and the virtual terminal is broken, you are logged out of your current process (and any images that the process is executing stop running) unless you have specified the /NOLOGOUT qualifier.
If you have specified the /NOLOGOUT qualifier, the process remains connected to the virtual terminal. If the process is executing an image, it continues until the process needs terminal input or attempts to write to the terminal. At that point, the process waits until the physical terminal is reconnected to the virtual terminal.
You can connect to a virtual terminal even if you are not currently using a virtual terminal. However, to log out of your current process you must use the CONNECT command with the /LOGOUT qualifier. If you connect to a virtual terminal from another virtual terminal, you can save your current process by using the /NOLOGOUT qualifier.

Qualifiers

/CONTINUE

/NOCONTINUE (default)
Controls whether the CONTINUE command is executed in the current process just before connecting to another process. This qualifier allows an interrupted image to continue processing after you connect to another process.
The /CONTINUE qualifier is incompatible with the /LOGOUT qualifier.
/LOGOUT (default)

/NOLOGOUT
Logs out your current process when you connect to another process using a virtual terminal.
When you enter the CONNECT command from a process that is not connected to a virtual terminal, you must specify the /LOGOUT qualifier. Otherwise, DCL displays an error message.
The /LOGOUT qualifier is incompatible with the /CONTINUE qualifier.

Examples

#1
$ RUN AVERAGE `[Ctrl/Y]` $ CONNECT/CONTINUE VTA72

In this example, you use the RUN command to execute the image AVERAGE.EXE. You enter this command from a terminal that is connected to a virtual terminal. Next, you press Ctrl/Y to interrupt the image. After you interrupt the image, enter the CONNECT command with the /CONTINUE qualifier. This operation issues the CONTINUE command, so the image continues to run and connects you to another virtual terminal. You can reconnect to the process later.

#2
$ SHOW USERS/FULL VAX/VMS User Processes at 22-DEC-1998 14:11:56.91 Total number of users = 51, number of processes = 158 Username Node Process Name PID Terminal KIDDER BUKETT KIDDER 29A0015E FTA3: KIDDER BUKETT _FTA4: 29A0015F FTA4: KIDDER RACEY1 KIDDER 05800062 FTA5: KIDDER RACEY1 DECW$MWM 0580005D MBA44: Disconnected KIDDER RACEY1 DECW$SESSION 05800059 KIDDER RACEY1 VUE$KIDDER_2 0580005E (subprocess of 05800059) KIDDER RACEY1 VUE$KIDDER_3 0580005F MBA51: Disconnected KIDDER RACEY1 VUE$KIDDER_4 05800060 MBA53: Disconnected MACKRILL BUKETT MACKRILL 29A002C1 FTA7: MACKRILL BUKETT MACKRILL_1 29A006C2 (subprocess of 29A002C1) MACKRILL BUKETT MACKRILL_2 29A00244 (subprocess of 29A002C1) MACKRILL HAMLET MACKRILL 24800126 FTA6: MACKRILL HAMLET DECW$BANNER 24800155 (subprocess of 24800126) MACKRILL HAMLET DECW$MWM 2480011F MBA170: Disconnected MACKRILL HAMLET DECW$SESSION 2480011D FTA5: . . . $ CONNECT VTA273 MACKRILL logged out at 22-DEC-1998 14:12:04.53 $

$ SHOW USERS/FULL
     VAX/VMS User Processes at 22-DEC-1998 14:11:56.91 
   Total number of users = 51,  number of processes = 158 
 
Username    Node   Process Name       PID     Terminal 
KIDDER     BUKETT  KIDDER           29A0015E  FTA3: 
KIDDER     BUKETT  _FTA4:           29A0015F  FTA4: 
KIDDER     RACEY1  KIDDER           05800062  FTA5: 
KIDDER     RACEY1  DECW$MWM         0580005D  MBA44:   Disconnected 
KIDDER     RACEY1  DECW$SESSION     05800059 
KIDDER     RACEY1  VUE$KIDDER_2     0580005E  (subprocess of 05800059) 
KIDDER     RACEY1  VUE$KIDDER_3     0580005F  MBA51:   Disconnected 
KIDDER     RACEY1  VUE$KIDDER_4     05800060  MBA53:   Disconnected 
MACKRILL   BUKETT  MACKRILL         29A002C1  FTA7: 
MACKRILL   BUKETT  MACKRILL_1       29A006C2  (subprocess of 29A002C1) 
MACKRILL   BUKETT  MACKRILL_2       29A00244  (subprocess of 29A002C1) 
MACKRILL   HAMLET  MACKRILL         24800126  FTA6: 
MACKRILL   HAMLET  DECW$BANNER      24800155  (subprocess of 24800126) 
MACKRILL   HAMLET  DECW$MWM         2480011F  MBA170:  Disconnected 
MACKRILL   HAMLET  DECW$SESSION     2480011D  FTA5: 
. 
. 
.
 
$ CONNECT VTA273
  MACKRILL      logged out at 22-DEC-1998 14:12:04.53
$

This example shows how to reconnect to your original process after you have lost the carrier signal. First, you must log in again and create a new process. After you log in, enter the SHOW USERS/FULL command to determine the virtual terminal name for your initial process. Then enter the CONNECT command to connect to the virtual terminal associated with your original process. The process from which you enter the CONNECT command is logged out because you have not specified any qualifiers.
When you reconnect to the original process, you continue running the image that you were running when you lost the carrier signal. In this example, the user MACKRILL was at interactive level when the connection was broken.

CONTINUE

Resumes execution of a DCL command, a program, or a command procedure that was interrupted by pressing Ctrl/Y or Ctrl/C. You cannot resume execution of the image if you have entered a command that executes another image or if you have invoked a command procedure.

Format

CONTINUE

Parameters

None.

Description

The CONTINUE command enables you to resume processing an image or a command procedure that was interrupted by pressing Ctrl/Y or Ctrl/C. You cannot resume execution of the image if you have entered a command that executes another image or if you have invoked a command procedure. However, you can use CONTINUE after commands that do not execute separate images; for a list of these commands, refer to the OpenVMS User's Manual.
You can abbreviate the CONTINUE command to a single letter, C.
The CONTINUE command serves as the target command of an IF or ON command in a command procedure. The CONTINUE command is also a target command when it follows a label that is the target of a GOTO command. In addition, you can use the CONTINUE command to resume processing of a program that has executed either a VAX FORTRAN PAUSE statement or a VAX COBOL-74 STOP literal statement.

Examples

#1
$ RUN MYPROGRAM_A `[Ctrl/Y]` $ SHOW TIME 14-DEC-1998 13:40:12 $ CONTINUE

In this example, the RUN command executes the program MYPROGRAM_A. While the program is running, pressing Ctrl/Y interrupts the image. The SHOW TIME command requests a display of the current date and time. The CONTINUE command resumes the image.

#2
$ ON SEVERE_ERROR THEN CONTINUE

In this example, the command procedure statement requests the command interpreter to continue executing the procedure if any warning, error, or severe error status value is returned from the execution of a command or program. This ON statement overrides the default action, which is to exit from a procedure following errors or severe errors.

CONVERT

Invokes the Convert utility, which copies records from one file to another and changes the organization and format of the input file to those of the output file.
For more information about the Convert utility, refer to the OpenVMS Record Management Utilities Reference Manual or online help.

Format

CONVERT input-filespec[,...] output-filespec

CONVERT/DOCUMENT

Converts a CDA supported revisable input file to another revisable or final form output file.

Note
You can use this command only if DECwindows Motif for OpenVMS is installed on your system.

Format

CONVERT/DOCUMENT input-filespec output-filespec

Parameters

input-filespec
Specifies the name of the input file to be converted. The default file type is .DDIF.
output-filespec
Specifies the name of the output file. The default file type is .DDIF.

Description

The CONVERT/DOCUMENT command lets you convert documents from one format to another. You specify the name and format of the input file (a file whose format is incompatible with the application that needs to read the file) and the output file (the file to be created in a new format).
You can convert a file from one format to another if an input converter exists for the input file format and an output converter exists for the output file format. The default input and output file format is DDIF (DIGITAL Document Interchange Format). DDIF is a standard format for the storage and interchange of compound documents, which can include text, graphics, and images.
DDIF input and output converters, in addition to several other converters, are installed with the CDA Base Services for DECwindows Motif for OpenVMS. Some of the converters support processing options, which ensure minimal changes when your input file is converted to a different output file format. Create an options file with the processing options you need before specifying the CONVERT/DOCUMENT command with the /OPTIONS qualifier.
Every converter supports a message log option, which is a file name you specify and to which informational and error messages are logged during the conversion.

Qualifiers

/FORMAT=format-name
Specifies the encoding format of the input or output file. The default input and output format is DDIF.
Input converters bundled with the CDA Base Services for DECwindows Motif for OpenVMS and the default file type for the file formats they support are as follows:

Input Format File Type

DDIF .DDIF

DTIF .DTIF

TEXT .TXT

Output converters bundled with the CDA Base Services for DECwindows Motif for OpenVMS and the default file types for the file formats they support are as follows:

Output Format File Type

DDIF .DDIF

DTIF .DTIF

TEXT .TXT

PS .PS

ANALYSIS .CDA$ANALYSIS

DIGITAL's CDA Converter Library is a layered product that offers several other document, graphics, image, and data table input and output converters. Independent software vendors also write CDA conforming applications and converters for the operating system. Contact your system manager for a complete list of converters available on your system.
Analysis Output Converter

The Analysis output converter produces an analysis of the intermediate representation of the input file. The analysis output file shows the named objects and values stored in the input file. Application programmers use an analysis output file for debugging purposes.
Application end users use an analysis output file to determine whether an input file contains references or links to multiple subfiles. Each subfile must be copied separately across a network because subfiles are not automatically included when an input file is transferred across the network.
You can search the analysis output file for all occurrences of the string "ERF_". The following example shows that the image file "griffin.img" is linked to the DDIF compound document that is the input file:
ERF_LABEL ISO LATIN1 "griffin.img" ! Char. string. ERF_LABEL TYPE RMS_LABEL TYPE "$RMS: ERF_CONTROL COPY_REFERENCE ! Integer = 1
Note that an analysis output file is intended as a programmer's tool. The coded information in the file is not intended for modification but rather to examine the content of a file. The previous example shows how you can search analysis output for references to linked files.
DDIF Input Converter

The DDIF input converter converts a DDIF input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the DDIF input converter.

Data mapping
The information in the DDIF input file maps directly to an intermediate representation.
Conversion restrictions
The DDIF input file does not lose any information when converted to the intermediate representation.
However, if the DDIF input file is a newer version of the DDIF grammar than that understood by the DDIF input converter, data represented by the new grammar elements is lost.
External file references
Any external file references within the DDIF input file are converted to the intermediate representation.
The DDIF input converter makes no attempt to resolve external references, although the converter kernel can if requested by the output converter.
Document syntax errors
A document syntax error in the DDIF input file causes a fatal input processing error. If the DDIF input converter encounters a document syntax error, the conversion stops and no further input processing occurs.

DDIF Output Converter

The DDIF output converter creates a DDIF output file from the intermediate representation of the input file. The following list summarizes the data mapping and conversion restrictions relevant to the DDIF output converter.

Data mapping
The information in the intermediate representation of the input file maps directly to the DDIF output file.
Conversion restrictions
The intermediate representation of the input file does not lose any information when converted to the DDIF output file.

DTIF Input Converter

The DTIF input converter converts a DTIF input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the DTIF input converter.

Data mapping
The information in the DTIF input file maps directly to an intermediate representation.
Conversion restrictions
The DTIF input file does not lose any information when converted to the intermediate representation.
However, if the DTIF input file is a newer version of the DTIF grammar than that understood by the DTIF front end, data represented by the new grammar elements is lost.
External file references
Any external file references within the DTIF input file are converted to the intermediate representation.
The DTIF input converter makes no attempt to resolve external references.
Document syntax errors
A document syntax error in the DTIF input file causes a fatal input processing error. If the DTIF input converter encounters a document syntax error, the conversion stops and no further input processing occurs.

DTIF Output Converter

The DTIF output converter converts the intermediate representation of the input file to a DTIF output file. The following list summarizes the data mapping, conversion restrictions, and external file references relevant to the DTIF output converter.

Data mapping
The information in the intermediate representation of the input file maps directly to the DTIF output file.
Conversion restrictions
The intermediate representation of the input file does not lose any information when converted to the DTIF output file.
External file references
The DTIF output converter converts external file references stored in the intermediate representation of the input file but makes no attempt to resolve external references.

Text Input Converter

The Text input converter converts a Text (ISO Latin1) input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the Text input converter:

Data mapping
The information in the text input file maps directly to an intermediate representation. Line breaks and form feeds are mapped to DDIF directives. One or more contiguous blank lines are interpreted as end-of-paragraph markers.
If the text input file was entered as a DEC Multinational character set file on a character-cell terminal or terminal emulator, the following conversions occur:

Original Character Converted Character

Concurrency sign Diaeresis

Capital OE ligature Multiplication sign

Capital Y with diaeresis Capital Y with acute accent

Small oe ligature Division sign

Small y with diaeresis Y with acute accent

Conversion restrictions
The text input file does not lose any information when converted to the intermediate representation because no structure information is contained in a text file.
All nonprinting characters are converted to space characters. For example, characters introducing ANSI escape characters are converted to space characters. There is no attempt to interpret ANSI escape sequences.
External file references
Text files do not contain external file references.
Document syntax errors
Text files do not contain syntax, so syntax errors are not reported by the Text input converter.

Previous Next Contents Index

privacy and legal statement

9996PRO_005.HTML

Original Character	Converted Character
Concurrency sign	Diaeresis
Capital OE ligature	Multiplication sign
Capital Y with diaeresis	Capital Y with acute accent
Small oe ligature	Division sign
Small y with diaeresis	Y with acute accent