![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
The FORTRAN command uses the logical name SYS$INPUT to identify the file to be compiled. Because SYS$INPUT equates to the command procedure, the FORTRAN compiler compiles the statements following the FORTRAN command (up to the next line that begins with a dollar sign). When the compilation completes, two output files are created: TESTER.OBJ and TESTER.LIS. The PRINT command then prints the file.
Output from command procedures such as data, error messages, and verification of command lines can be directed to either terminals or other files. The following methods of directing output are covered in this section:
The following sections describe how to write data to terminals.
Use the TYPE command to display text that is several lines long and does not require symbol substitution. The TYPE command writes data from the file you specify to SYS$OUTPUT.
In the following example, SYS$INPUT is specified as the data file. The TYPE command reads data from the data lines that follow and displays the lines on the terminal:
$ ! Using TYPE to display lines $ TYPE SYS$INPUT REPORT BY MARY JONES PREPARED APRIL 15, 1995 SUBJECT: Analysis of Tax Deductions for 1995 . . . $ EXIT
Use the WRITE command to write data that contains symbols or lexical functions. Unless you enclose the data in quotation marks (" "), the WRITE command performs symbol substitution automatically.
To use the WRITE command to display a character string as literal text, enclose the string in quotation marks (" "). For example:
$ WRITE SYS$OUTPUT "Two files are written." Two files are written.
To include quotation marks in character strings, use two sets of quotation marks ("" ""). For example:
$ WRITE SYS$OUTPUT "Summary of ""Q & A"" Session" Summary of "Q & A" Session
To continue a line of text on more than one line, concatenate the two strings with a plus sign (+) and a hyphen (-). For example:
$ WRITE SYS$OUTPUT "Report by Mary Jones" + - " Prepared April 15, 1996" Report by Mary Jones Prepared April 15, 1996
The WRITE command performs symbol substitutions automatically and displays the values of symbols. To force symbol substitutions within character strings, enclose the symbol in apostrophes. For example:
$ AFILE = "STAT1.DAT" $ BFILE = "STAT2.DAT" $ WRITE SYS$OUTPUT "''AFILE' and ''BFILE' ready." STAT1.DAT and STAT2.DAT ready.
In this example, STAT1.DAT is the translation of the symbol AFILE; STAT2.DAT is the translation of the symbol BFILE.
The following sections describe how to redirect output from commands and images.
Commands, utilities, and other system images write their output to the source specified by the logical name SYS$OUTPUT. By default, SYS$OUTPUT equates to the terminal. However, you can redirect the output in one of the following ways:
In the following example, the command procedure redirects the output from the SHOW USERS command to a file. The new definition for SYS$OUTPUT is in effect only for the execution of the SHOW USERS command:
$ DEFINE/USER_MODE SYS$OUTPUT SHOW_USER.DAT $ SHOW USERS $ ! $ ! Process the information in SHOW_USER.DAT $ OPEN/READ INFILE SHOW_USER.DAT $ READ INFILE RECORD . . . $ CLOSE INFILE $ EXIT
In the following example, SYS$OUTPUT is defined as a null device (NL:).
$ DEFINE/USER_MODE SYS$OUTPUT NL: $ APPEND NEW_DATA.DAT STATS.DAT . . .
The /USER_MODE qualifier is used to create a temporary logical name assignment that is in effect only until the next image completes. After the command executes, SYS$OUTPUT reverts to the default definition (usually the terminal).
You cannot use the DEFINE/USER_MODE command to redirect output from DCL commands that are executed within the command interpreter. Instead, use the DEFINE command to redefine SYS$OUTPUT and use the DEASSIGN command to delete the definition when you are through with it.
The following is a complete list of DCL commands that are performed within the command interpreter:
| = | ALLOCATE | ASSIGN |
| ATTACH | CALL | CANCEL |
| CLOSE | CONNECT | CONTINUE |
| CREATE/LOGICAL_NAME_TABLE | DEALLOCATE | DEASSIGN |
| DEBUG | DECK | DEFINE |
| DEFINE/KEY | DELETE/SYMBOL | DISCONNECT |
| ELSE | ENDIF | ENDSUBROUTINE |
| EOD | EXAMINE | EXIT |
| GOSUB | GOTO | IF |
| INQUIRE | ON | OPEN |
| READ | RECALL | RETURN |
| SET CONTROL | SET DEFAULT | SET KEY |
| SET ON | SET OUTPUT_RATE | SET PROMPT |
| SET PROTECTION/DEFAULT | SET SYMBOL/SCOPE | SET UIC |
| SET VERIFY | SHOW DEFAULT | SHOW KEY |
| SHOW PROTECTION | SHOW QUOTA | SHOW STATUS |
| SHOW SYMBOL | SHOW TIME | SHOW TRANSLATION |
| SPAWN | STOP | SUBROUTINE |
| THEN | WAIT | WRITE |
The following example shows the commands that would be used to redirect output from the SHOW TIME command to the file TIME.DAT. After you deassign SYS$OUTPUT, it reverts to the default definition (the terminal):
$ DEFINE SYS$OUTPUT TIME.DAT $ SHOW TIME $ DEASSIGN SYS$OUTPUT
The following sections describe how to return data from command procedures.
Global symbols and logical names return data from a command procedure to a calling procedure or to DCL command level. You can read a global symbol or a logical name at any command level. Logical names can return data from a nested command procedure to the calling procedure.
The following example shows a how a command procedure passes a value with a global symbol created with a global assignment statement:
$ @DATA "Paul Cramer"
$ ! DATA.COM
$ !
$ ! P1 is a full name.
$ ! NAME.COM returns the last name in the
$ ! global symbol LAST_NAME.
$ !
$ @NAME 'P1'
$ ! NAME.COM
$ ! P1 is a first name
$ ! P2 is a last name
$ ! return P2 in the global symbol LAST_NAME
$ LAST_NAME == P2
$ EXIT
$ ! write LAST_NAME to the terminal
$ WRITE SYS$OUTPUT "LAST_NAME = ''LAST_NAME'"
LAST_NAME = CRAMER
DATA.COM invokes the command procedure NAME.COM, passing NAME.COM a full name. NAME.COM places the last name in the global symbol LAST_NAME. When NAME.COM completes, DCL continues executing DATA.COM, which reads the last name by specifying the global symbol LAST_NAME. The command procedure NAME.COM would be in a separate file. It is shown indented in this example for clarity.
In this command procedure, REPORT.COM obtains the file name for a report, equates the file name to the logical name REPORT_FILE, and executes a program that writes a report to REPORT_FILE:
$! Obtain the name of a file and then run $! REPORT.EXE to write a report to the file $! $ INQUIRE FILE "Name of report file" $ DEFINE/NOLOG REPORT_FILE 'FILE' $ RUN REPORT $ EXIT
In the following example, the command procedure REPORT.COM is invoked from another procedure. The calling procedure uses the logical name REPORT_FILE to refer to the report file:
$! Command procedure that updates data files
$! and optionally prepares reports
$!
$ UPDATE:
.
.
.
$ INQUIRE REPORT "Prepare a report [Y or N]"
$ IF REPORT THEN GOTO REPORT_SEC
$ EXIT
$!
$ REPORT_SEC:
$ @REPORT
$ WRITE SYS$OUTPUT "Report written to ", F$TRNLNM("REPORT_FILE")
$ EXIT
The following sections describe how to redirect error messages.
By default, command procedures send system error messages to the file indicated by SYS$ERROR. You can redefine SYS$ERROR to direct system error messages to a specified file. However, if you redefine SYS$ERROR to be different from SYS$OUTPUT (or if you redefine SYS$OUTPUT without also redefining SYS$ERROR), DCL commands and images that use standard system error display mechanisms send system error level and system severe level error messages to both SYS$ERROR and SYS$OUTPUT. Therefore, you receive these messages twice---once in the file indicated by the definition of SYS$ERROR and once in the file indicated by SYS$OUTPUT. Success, informational, and warning level messages are sent only to the file indicated by SYS$OUTPUT.If you want to suppress system error messages from a DCL command, be sure that neither SYS$ERROR nor SYS$OUTPUT is equated to the terminal.
If you run one of your own images from a command procedure and the image references SYS$ERROR, the image sends system error messages only to the file indicated by SYS$ERROR---even if SYS$ERROR is different from SYS$OUTPUT. Only DCL commands and images that use standard system error display mechanisms send messages to both SYS$ERROR and SYS$OUTPUT when these files are different.
This command procedure accepts a directory name as a parameter, sets the default to that directory, and purges files in the directory. To suppress system error messages, the procedure temporarily defines SYS$ERROR and SYS$OUTPUT as the null device:
$ ! Purge files in a directory and suppress messages $ ! $ SET DEFAULT 'P1' $ ! Suppress messages $ ! $ DEFINE/USER_MODE SYS$ERROR NL: $ DEFINE/USER_MODE SYS$OUTPUT NL: $ PURGE $ EXIT
You can also use the SET MESSAGE command to suppress system messages. By using the qualifiers /NOFACILITY, /NOIDENTIFICATION, /NOSEVERITY, or /NOTEXT, you can suppress the facility name, message identification, severity level, or the message text.
In the following example, the facility, identification, severity and text messages are temporarily suppressed, until the second SET MESSAGE command is issued:
$ ! Purge files in a directory and suppress system messages
$ !
$ SET DEFAULT 'P1'
$ ! Suppress system messages
$ !
$ SET MESSAGE/NOFACILITY -
/NOIDENTIFICATION -
/NOSEVERITY -
/NOTEXT
$ PURGE
$ SET MESSAGE/FACILITY -
/IDENTIFICATION -
/SEVERITY
/TEXT
$ EXIT
The basic steps in reading and writing files from command procedures are:
| Step | Action |
|---|---|
| 1 |
Use the OPEN command to open files.
This assigns a logical name to the file and specifies whether the file is to be read, written, or both read and written. Subsequent READ, WRITE, and CLOSE commands use this logical name to refer to the file. |
| 2 |
Use the READ or WRITE commands to read or write records to files.
Input and output to files are usually accomplished by designing a loop to read a record, process the record, and write the modified record to either the same file or to another file. |
| 3 |
Use the CLOSE command to close files.
If you do not include the CLOSE command, files remain open until you log out. |
You do not have to open process-permanent files such as SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR explicitly to read or write to them because the system opens these files for you when you log in.
The following sections describe:
The OPEN command opens sequential, relative, or indexed sequential files. The files are opened as process-permanent; they remain open for the duration of your process unless you explicitly close them (with the CLOSE command). While the files are open, they are subject to OpenVMS RMS restrictions on using process-permanent files.
When you open a file, the OPEN command assigns a logical name (specified as the first parameter) to the file (specified as the second parameter) and places the name in the process logical name table. Subsequent READ, WRITE, and CLOSE commands use this logical name to refer to the file.
In the following example, the OPEN command assigns the logical name INFILE to the file DISK4:[MURPHY]STATS.DAT:
$ OPEN/READ INFILE DISK4:[MURPHY]STATS.DAT
The logical name in the OPEN command must be unique. If the OPEN command does not work and your commands seem correct, change the logical name in the OPEN command. To display a list of logical name definitions, use the SHOW LOGICAL command.
To ensure that the command procedure can access the correct files, use complete file specifications (for example, DISK4:[MURPHY]STATS.DAT) or use the SET DEFAULT command to specify the proper device and directory before you open a file.
You can also specify shareable files. The /SHARE qualifier enables other opened file. In addition, users can access shareable files with the DCL commands TYPE and SEARCH.
The OPEN/READ command opens the files, assigns logical names to the files, and places record pointers at the beginning of the files. When you open files for reading, you can read but not write records. Each time you read a record, the pointer moves to the next record.
The OPEN/READ command in this command procedure opens the file STATS.DAT and assigns the logical name INFILE to the file:
$ OPEN/READ INFILE DISK4:[MURPHY]STATS.DAT $ READ_FILE: $ READ/END_OF_FILE=DONE INFILE DATA $ GOTO READ_FILE $ DONE: $ CLOSE INFILE $ EXIT
Use the OPEN/WRITE command when you want to write to a new file. The OPEN/WRITE command creates a sequential file in print file format. The record format for the file is variable with fixed control (VFC), with a 2-byte record header. The /WRITE qualifier cannot be used with the /APPEND qualifier.
If you specify a file that already exists, the OPEN/WRITE command opens a new file with a version number one greater than the existing file.
The command procedure in the following example creates a new file (NAMES.DAT) that can be used for writing:
$ OPEN/WRITE OUTFILE DISK4:[MURPHY]NAMES.DAT $ UPDATE: $ INQUIRE NEW_RECORD "Enter name" $ WRITE OUTFILE NEW_RECORD $ IF NEW_RECORD .EQS. "" THEN GOTO EXIT_CODE $ GOTO UPDATE $ EXIT_CODE: $ CLOSE OUTFILE $ EXIT
The OPEN/APPEND command appends records to the end of an existing file. If you attempt to open a file that does not exist, an error occurs and the file is not opened. The /APPEND qualifier cannot be used with the /WRITE qualifier.
In the following example, records are appended to the end of an existing file, NAMES.DAT:
$ OPEN/APPEND OUTFILE DISK4:[MURPHY]NAMES.DAT $ INQUIRE NEW_RECORD "Enter name" $ WRITE OUTFILE NEW_RECORD . . . $ CLOSE OUTFILE
The OPEN/READ/WRITE command places the record pointer at the beginning of a file so you can read the first record. When you use this method to open a file, you can replace only the record you have read most recently; you cannot write new records to the end of the file. In addition, a revised record must be exactly the same size as the record being replaced.
In the following example, the record pointer is placed at the beginning of the file STATS.DAT so the first record can be read:
$ OPEN/READ/WRITE FILE DISK4:[MURPHY]STATS.DAT
The following sections describe how to write files.
To write to files, use the following procedure:
| Step | Action |
|---|---|
| 1 | Open the file for writing. |
| 2 |
Begin the write loop with a label.
File I/O is always done in a loop unless you are writing or reading a single record. |
| 3 |
Read the data to be written.
Use the INQUIRE command or the READ command to read data into a symbol. |
| 4 |
Test the data.
Check the symbol containing the data. If the symbol is null (for example, if you press Return and enter no data on the line), you have reached the end of the data to be written to the file and you should go to the end of the loop. Otherwise, continue. |
| 5 |
Write the data to the file.
Use the WRITE command to write the value of the symbol (one record) to the file. |
| 6 |
Return to the beginning of the loop.
You remain within the loop until there is no more data to be written to the file. |
| 7 | End the loop and close the file. |
The following command procedure writes data to the new file STATS.DAT. If a file of that name exists, a new version is created:
$ ! Write a file $ ON ERROR THEN EXIT ! Exit if the command $ ! ! procedure cannot $ ! ! open the file $ OPEN/WRITE IN_FILE DISK4:[MURPHY]STATS.DAT ! Open the file $ ON CONTROL_Y THEN GOTO END_WRITE ! Close the file if you $ ! ! quit execution with $ ! ! Ctrl/Y $ ON ERROR THEN GOTO END_WRITE ! Close the file if an $ ! ! error occurs $WRITE: ! Begin the loop $ INQUIRE STUFF "Input data" ! Prompt for input $ IF STUFF .EQS. "" THEN GOTO END_WRITE ! Test for the end of $ ! ! the file $ WRITE IN_FILE STUFF ! Write to the file $ GOTO WRITE ! Go to the beginning $END_WRITE: ! End the loop $ ! ! $ CLOSE IN_FILE ! Close the file
To create a file with a unique name, use the F$SEARCH lexical function to see whether the name is already in the directory. (See the lexical function descriptions in the OpenVMS DCL Dictionary for more information about F$SEARCH.)
This command procedure prompts the user for a file name, then uses the F$SEARCH lexical function to search the default directory for the name. If a file with that name already exists, control is passed to ERROR_1, the procedure prints the message The file already exists and control returns to the label GET_NAME. The procedure then prompts for another file name:
$ ! FILES.COM $ ! $GET_NAME: $ INQUIRE FILE "File" ! Prompt the user for a file name $ IF F$SEARCH (FILE) .NES. "" ! Make sure the file name is unique $ THEN $ WRITE SYS$OUTPUT "The file already exists" $ GOTO GET_NAME $ ELSE $ OPEN/WRITE IN_FILE 'FILE' ! Open the file with WRITE access $ ENDIF . . . $ EXIT
When you specify data for the WRITE command, follow the rules for character string expressions described in Chapter 14. You can specify data in the following ways:
$ WRITE OUTFILE "Count is ",COUNT,"."
$! Define symbols $! $ CREATED = "File created April 15, 1996" $ COUNT = 4 $ P4 = "fourth parameter" $! $! Open the file DATA.OUT for writing $! $ OPEN/WRITE OUTFILE DISK4:[MURPHY]DATA.OUT $! $ WRITE OUTFILE CREATED (1) $ WRITE OUTFILE "CREATED" (2) $! $ WRITE OUTFILE "Count is ''COUNT'." (3) $ WRITE OUTFILE P'COUNT' (4) $! $ WRITE OUTFILE "Mode is ''f$mode()'" (5) $! $ CLOSE OUTFILE $ TYPE DISK4:[MURPHY]DATA.OUT [Return] (6) File created April 15, 1996 CREATED Count is 4. fourth parameter Mode is INTERACTIVE $
As you examine the example, note the following:
When the WRITE command writes a record, it positions the record pointer after the record just written. The WRITE command can write a record that is up to 2,048 bytes long.
6489P030.HTM OSSG Documentation 22-NOV-1996 13:17:21.56
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.