 |
OpenVMS User's Manual
C.4 SYS.COM Command Procedure
This command procedure returns statistics about the current process,
all processes in the group (if the current process has group
privilege), and all processes on the system (if the current process has
world privilege). This procedure illustrates use of the F$PID,
F$EXTRACT, and F$GETJPI lexical functions.
Example: SYS.COM
$ !
$ ! Displays information about owner, group, or system processes.
$ !
$ ! Turn off verification and save current settings
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0)
$ CONTEXT = "" ! Initialize PID search context (1)
$ !
$ ! Output header line.
$ !
$ WRITE SYS$OUTPUT " PID Username Term Process " + - (2)
"name State Pri Image"
$ !
$ ! Output process information.
$ !
$LOOP:
$ !
$ ! Get next PID. If null, then done.
$ !
$ PID = F$PID(CONTEXT) (3)
$ IF PID .EQS. "" THEN GOTO DONE
$ !
$ ! Get image file specification and extract the file name.
$ !
$ IMAGNAME = F$GETJPI(PID,"IMAGNAME") (4)
$ IMAGNAME = F$PARSE(IMAGNAME,,,"NAME","SYNTAX_ONLY")
$ !
$ ! Get terminal name. If none, then describe type of process.
$ !
$ TERMINAL = F$GETJPI(PID,"TERMINAL") (5)
$ IF TERMINAL .EQS. "" THEN -
TERMINAL = "-"+F$EXTRACT(0,3,F$GETJPI(PID,"MODE"))+"-"
$ IF TERMINAL .EQS. "-INT-" THEN TERMINAL = "-DET-"
$ IF F$GETJPI(PID,"OWNER") .NE. 0 THEN TERMINAL = "-SUB-"
$ !
$ ! Get more information, put process line together,
$ ! and output it.
$ !
$ LINE = F$FAO("!AS !12AS !7AS !15AS !5AS !2UL/!UL !10AS", - (6)
PID,F$GETJPI(PID,"USERNAME"),TERMINAL,-
F$GETJPI(PID,"PRCNAM"),-
F$GETJPI(PID,"STATE"),F$GETJPI(PID,"PRI"),-
F$GETJPI(PID,"PRIB"),IMAGNAME)
$ WRITE SYS$OUTPUT LINE
$ GOTO LOOP
$ !
$ ! Restore verification and exit.
$ !
$DONE:
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$ EXIT
|
Notes for SYS.COM Command Procedure
- The symbol CONTEXT is initialized with a
null value. This symbol will be used with the F$PID function to obtain
a list of process identification numbers.
- The procedure writes a header for the
display.
- The procedure gets the first process
identification (PID) number. If the current process lacks group or
world privilege, the PID number of the current process is returned. If
the current process has group privilege, the first PID number in the
group list is returned. The first PID number in the system list is
returned if the current process has world privilege. The function
continues to return the next PID number in sequence until the last PID
number is returned. At this point, a null string is returned, and the
procedure branches to the end.
- The procedure uses the F$GETJPI lexical
function to get the image file specification for each PID number. The
F$PARSE function extracts the file name from the specification returned
by the F$GETJPI function.
- The procedure uses the F$GETJPI function to
get the terminal name for each PID number. The F$EXTRACT function
extracts the first three characters of the MODE specification returned
by F$GETJPI(PID,"MODE") to determine the type of process. The F$GETJPI
function is used again to determine whether the process is a subprocess.
- The procedure uses the F$GETJPI lexical
function to get the user name, process name, process state, process
priority, and process base priority for each PID number returned. The
F$FAO lexical function formats this information into a screen display.
Sample Execution for SYS.COM Command Procedure
PID Username Term Process name State Pri Image
00050011 NETNONPRIV -NET- MAIL_14411 LEF 9/4 MAIL
00040013 STOVE RTA6: STOVE LEF 9/4
00140015 MAROT -DET- DMFB0ACP HIB 9/8 F11BAC
00080016 THOMPSON -DET- MTA0ACP HIB 12/8 MTAAACP
00070017 JUHLES TTF1: JUHLES LEF 9/4
.
.
.
00040018 MARCO TTA2: MARCO HIB 9/4 RTPAD
0018001A VERN RTA3: VERN LEF 9/4
0033001B YISHA RTA7: YISHA CUR 4/4
0002004A SYSTEM -DET- ERRFMT HIB 12/7 ERRFMT
|
This procedure returns information on all processes on the system. The
current process has world privilege.
C.5 GETPARMS.COM Command Procedure
This command procedure returns the number of parameters passed to a
procedure. You can call GETPARMS.COM from another procedure to
determine how many parameters were passed to the calling procedure.
Example: GETPARMS.COM
$ ! Procedure to count the number of parameters passed to a command
$ ! procedure. This number is returned as the global symbol PARMCOUNT.
$ !
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") (1)
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0)
$ !
$ IF P1 .EQS. "?" THEN GOTO TELL (2)
$ !
$ ! Loop to count the number of parameters passed. Null parameters are
$ ! counted until the last non-null parameter is passed.
$ !
$ COUNT = 0 (3)
$ LASTNONNULL = 0
$ LOOP:
$ IF COUNT .EQ. 8 THEN GOTO END_COUNT
$ COUNT = COUNT + 1
$ IF P'COUNT' .NES. "" THEN LASTNONNULL = COUNT
$ GOTO LOOP
$ !
$ END_COUNT: (4)
$ !
$ ! Place the number of non-null parameters passed into PARMCOUNT.
$ !
$ PARMCOUNT == LASTNONNULL
$ !
$ ! Restore verification setting, if it was on, before exiting
$ ! (5)
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE)
$ EXIT
$ !
$ TELL: (6)
$ TYPE SYS$INPUT
This procedure counts the number of parameters passed to
another procedure. This procedure can be called by entering
the following string in any procedure:
@GETPARMS 'P1 'P2 'P3 'P4 'P5 'P6 'P7 'P8
On return, the global symbol PARMCOUNT
contains the number of parameters passed to the procedure.
$ !
$ EXIT
|
Notes for GETPARMS.COM Command Procedure
- The procedure saves the current image and
procedure verification settings before turning off verification.
- If a question mark character was passed to
the procedure as a parameter, the procedure branches to the label TELL
(Note 6).
- A loop is established to count the number of
parameters that were passed to the procedure. The counters COUNT and
LASTNONNULL are initialized to 0 before entering the loop. Within the
loop, COUNT is incremented and tested against the value 8. If COUNT is
equal to 8, the maximum number of parameters has been entered. Each
time a non-null parameter is passed, LASTNONNULL is equated to that
parameter's number.
Each time the IF command executes, the symbol
COUNT has a different value. The first time, the value of COUNT is 1
and the IF command checks P1. The second time, it checks P2, and so on.
- When the parameter count reaches 8, the
procedure branches to END_COUNT. The symbol LASTNONNULL contains the
count of the last non-null parameter passed. This value is placed in
the global symbol PARMCOUNT. PARMCOUNT must be defined as a global
symbol so that its value can be tested at the calling command level.
- The original verification settings are
restored.
- At the label TELL, the TYPE command displays
data that is included in the input stream. (In command procedures, the
input stream is the command procedure file.) The TYPE command displays
instructions on how to use GETPARMS.COM.
Sample Execution for GETPARMS.COM Command Procedure
The procedure SORTFILES.COM requires the user to pass three non-null
parameters. The SORTFILES.COM procedure can contain the following lines:
$ @GETPARMS 'P1' 'P2' 'P3' 'P4' 'P5' 'P6' 'P7' 'P8'
$ IF PARMCOUNT .NE. 3 THEN GOTO NOT_ENOUGH
.
.
.
$NOT_ENOUGH:
$ WRITE SYS$OUTPUT -
"Three non-null parameters required. Type SORTFILES HELP for info."
$ EXIT
|
The procedure SORTFILES.COM can be invoked as follows:
$ @SORTFILES DEF 4
Three non-null parameters required. Type SORTFILE HELP for info.
|
For this procedure to be properly invoked --- that is, for the
parameters that are passed to SORTFILES to be passed intact to GETPARMS
for processing --- the symbols P1 to P8 must be enclosed in single
quotation marks.
If the return value from GETPARMS is not 3, SORTFILES outputs an error
message and exits.
C.6 EDITALL.COM Command Procedure
This command procedure invokes the EDT editor repeatedly to edit a
group of files with the same file type. This procedure illustrates how
to use lexical functions to extract file names from columnar output. It
also illustrates a way to redefine the input stream for a program
invoked within a command procedure.
Example: EDITALL.COM
$ ! Procedure to edit all files in a directory with a
$ ! specified file type. Use P1 to indicate the file type.
$ !
$ ON CONTROL_Y THEN GOTO DONE ! Ctrl/Y action (1)
$ ON ERROR THEN GOTO DONE
$ !
$ ! Check for file type parameter. If one was entered, continue;
$ ! otherwise, prompt for a parameter.
$ !
$ IF P1 .NES. "" THEN GOTO OKAY (2)
$ INQUIRE P1 "Enter file type of files to edit"
$ !
$ ! List all files with the specified file type and write the DIRECTORY
$ ! output to a file named DIRECT.OUT
$ !
$ OKAY:
$ DIRECTORY/VERSIONS=1/COLUMNS=1 - (3)
/NODATE/NOSIZE -
/NOHEADING/NOTRAILING -
/OUTPUT=DIRECT.OUT *.'P1'
$ IF .NOT. $STATUS THEN GOTO ERROR_SEC (4)
$ !
$ OPEN/READ/ERROR=ERROR_SEC DIRFILE DIRECT.OUT (5)
$ !
$ ! Loop to read directory file
$ !
$ NEWLINE: (6)
$ READ/END=DONE DIRFILE NAME
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND: ! Redefine SYS$INPUT
$ EDIT 'NAME' ! Edit the file
$ GOTO NEWLINE
$ !
$ DONE: (7)
$ CLOSE DIRFILE/ERROR=NOTOPEN ! Close the file
$ NOTOPEN:
$ DELETE DIRECT.OUT;* ! Delete temp file
$ EXIT
$ !
$ ERROR_SEC:
$ WRITE SYS$OUTPUT "Error: ",F$MESSAGE($STATUS)
$ DELETE DIRECT.OUT;*
$ EXIT
|
Notes for EDITALL.COM Command Procedure
- ON commands establish condition handling for
this procedure. If Ctrl/Y is pressed at any time during the execution
of this procedure, the procedure branches to the label DONE. Similarly,
if any error or severe error occurs, the procedure branches to the
label DONE.
- The procedure checks whether a parameter was
entered. If not, the procedure prompts for a file type.
- The DIRECTORY command lists all files with
the file type specified as P1. The command output is written to the
file DIRECT.OUT. The /VERSIONS=1 qualifier requests that only the
highest numbered version of each file be listed. The /NOHEADING and
/NOTRAILING qualifiers request that no heading lines or directory
summaries be included in the output. The /COLUMNS=1 qualifier ensures
that one file name per record is given.
- The IF command checks the return value from
the DIRECTORY command by testing the value of $STATUS. If the DIRECTORY
command does not complete successfully, then $STATUS has an even
integer value, and the procedure branches to the label ERROR_SEC.
- The OPEN command opens the directory output
file and gives it a logical name of DIRFILE.
- The READ command reads a line from the
DIRECTORY command output into the symbol name NAME. After it reads each
line, the procedure uses the DEFINE command to redefine the input
stream for the edit session (SYS$INPUT) to be the terminal. Then, it
invokes the editor, specifying the symbol NAME as the file
specification. When the edit session is completed, the command
interpreter reads the next line in the command procedure and branches
to the label NEWLINE. When the procedure has edited all files of the
specified file type in the directory, it branches to the label DONE.
- The label DONE is the target label for the
/END qualifier on the READ command and the target label for the ON
CONTROL_Y and ON ERROR conditions set at the beginning of the
procedure. At this label, the procedure performs the necessary cleanup
operations.
The CLOSE command closes the DIRECTORY command output
file; the /ERROR qualifier specifies the label on the next line in the
file. This use of /ERROR suppresses any error message that would be
displayed if the directory file is not open. For example, this would
occur if Ctrl/Y were pressed before the directory file were opened.
The second step in cleanup is to delete the temporary directory
file.
Sample Execution for EDITALL.COM Command Procedure
$ @EDITALL DAT
* .
.
.
%DELETE-I-FILDEL, device:[directory]DIRECT.OUT;1 deleted (x blocks)
|
The procedure EDITALL is invoked with P1 specified as .DAT. The
procedure creates a directory listing of all files in the default
directory whose file types are .DAT and invokes the editor to edit each
one. After you finish editing the last file with the file type .DAT,
the procedure deletes the temporary file DIRECT.OUT and displays an
informational message at your terminal.
C.7 MAILEDIT.COM Command Procedure
This command procedure invokes a text editor in the Mail utility.
Example: MAILEDIT.COM
$ ! Command procedure to invoke an editor for Mail.
$ !
$ ! Inputs:
$ !
$ ! P1 = Input file name.
$ ! P2 = Output file name.
$ !
$ ! If MAIL$EDIT is undefined, Mail will invoke the user's selected
$ ! callable editor set by the mail SET EDITOR command.
$ !
$ ! If MAIL$EDIT is defined to be a command procedure, Mail will create
$ ! a subprocess to edit the mail, but any SET EDITOR command in Mail
$ ! will override the definition of MAIL$EDIT for the remainder of that
$ ! Mail session.
$ !
$ ! Note that this procedure is run in the context of a subprocess.
$ ! LOGIN.COM is not executed. However, all process logical names
$ ! and DCL global symbols are copied. In particular, note that the
$ ! user's individual definition of the symbol EDIT is used if there
$ ! is one. Otherwise, the system default editor is used.
$ !
$ ! The default directory is the same as the parent process
$ !
$ DEFINE /USER SYS$INPUT 'F$TRNLNM("SYS$OUTPUT")' (1)
$ IF P1 .EQS. "" THEN GOTO NOINPUT (2)
$ EDIT /OUTPUT='P2' 'P1' (3)
$ EXIT
$NOINPUT:
$ EDIT 'P2' (4)
$ EXIT
|
Notes for MAILEDIT.COM Command Procedure
- The DEFINE command allows the editor input
to come from the terminal instead of the command file.
- The IF statement distinguishes between
editing a file with a different output file name from editing a file
with the same file name.
- This EDIT command invokes an editor with
input and output file names. You can edit this line to invoke an editor
of your choice. For example:
$ RUN XYZ_EDITOR.EXE /INPUT= 'P1' /OUTPUT='P2'
|
- This EDIT command invokes an editor with a
single file name. You can edit this line to invoke an editor of your
choice. For example:
$ RUN XYZ_EDITOR.EXE /INPUT= 'P2' /OUTPUT='P2'
|
Sample Execution for MAILEDIT.COM Command Procedure
$DEFINE MAIL$EDIT MAILEDIT.COM
$MAIL
MAIL> SHOW EDITOR
Your editor is defined by the file MAILEDIT.COM.
|
C.8 FORTUSER.COM Command Procedure
Provides a sample of a system-defined login command procedure that
controls the terminal environment for an interactive user who creates,
compiles, and executes FORTRAN programs. If a user logs in to a captive
account where FORTUSER.COM is listed as the login command procedure,
the user can execute only the commands accepted by FORTUSER.COM. This
procedure also illustrates how to use lexical functions to step through
an option table, comparing a user-entered command with a list of valid
commands.
Example: FORTUSER.COM
$ ! Procedure to create, compile, link, execute, and debug
$ ! FORTRAN programs. Users can enter only the commands listed
$ ! in the symbol OPTION_TABLE.
$ SET NOCONTROL=Y (1)
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE")
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0)
$ OPTION_TABLE = "EDIT/COMPILE/LINK/RUN/EXECUTE/DEBUG/PRINT/HELP/FILE/DONE/" (2)
$ TYPE SYS$INPUT (3)
VMS FORTRAN Command Interpreter
Enter name of file with which you would like to work.
$ !
$ ! Set up for initial prompt
$ !
$ PROMPT = "INIT" (4)
$ GOTO HELP ! Print the initial help message
$ !
$ ! after the first prompting message, use the prompt: Command
$ !
$ INIT:
$ PROMPT = "GET_COMMAND"
$ GOTO FILE ! Get initial file name
$ !
$ ! Main command parsing routine. The routine compares the current
$ ! command against the options in the option table. When it finds
$ ! a match, it branches to the appropriate label.
$ !
$ GET_COMMAND:
$ ON CONTROL_Y THEN GOTO GET_COMMAND ! Ctrl/Y resets prompt (5)
$ SET CONTROL=Y
$ ON WARNING THEN GOTO GET_COMMAND ! If any, reset prompt
$ INQUIRE COMMAND "Command"
$ IF COMMAND .EQS. "" THEN GOTO GET_COMMAND
$ IF F$LOCATE(COMMAND + "/", OPTION_TABLE) .EQ. F$LENGTH(OPTION_TABLE) - (6)
THEN GOTO INVALID_COMMAND
$ GOTO 'COMMAND'
$ !
$ INVALID_COMMAND: (7)
$ WRITE SYS$OUTPUT " Invalid command"
$ !
$ HELP: (8)
$ TYPE SYS$INPUT
The commands you can enter are:
FILE Name of FORTRAN program in your current
default directory. Subsequent commands
process this file.
EDIT Edit the program.
COMPILE Compile the program with FORTRAN.
LINK Link the program to produce an executable image.
RUN Run the program's executable image.
EXECUTE Same function as COMPILE, LINK, and RUN.
DEBUG Run the program under control of the debugger.
PRINT Queue the most recent listing file for printing.
DONE Return to interactive command level.
HELP Print this help message.
Enter Ctrl/Y to restart this session
$ GOTO 'PROMPT' (9)
$ EDIT: (10)
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$ EDIT 'FILE_NAME'.FOR
$ GOTO GET_COMMAND
$ COMPILE:
$ FORTRAN 'FILE_NAME'/LIST/OBJECT/DEBUG
$ GOTO GET_COMMAND
$ LINK:
$ LINK 'FILE_NAME'/DEBUG
$ PURGE 'FILE_NAME'.*/KEEP=2
$ GOTO GET_COMMAND
$ RUN:
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$ RUN/NODEBUG 'FILE_NAME'
$ GOTO GET_COMMAND
$ DEBUG:
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND:
$ RUN 'FILE_NAME'
$ GOTO GET_COMMAND
$ EXECUTE:
$ FORTRAN 'FILE_NAME'/LIST/OBJECT
$ LINK/DEBUG 'FILE_NAME'
$ PURGE 'FILE_NAME'.*/KEEP=2
$ RUN/NODEBUG 'FILE_NAME'
$ GOTO GET_COMMAND
$ PRINT:
$ PRINT 'FILE_NAME'
$ GOTO GET_COMMAND
$ BADFILE: (11)
$ WRITE SYS$OUTPUT "File must be in current default directory."
$ FILE:
$ INQUIRE FILE_NAME "File name"
$ IF FILE_NAME .EQS. "" THEN GOTO FILE
$ IF F$PARSE(FILE_NAME,,,"DIRECTORY") .NES. F$DIRECTORY() - (12)
THEN GOTO BADFILE
$ FILE_NAME = F$PARSE(FILE_NAME,,,"NAME")
$ GOTO GET_COMMAND
$ DONE:
$ EXIT
|
Notes for FORTUSER.COM Command Procedure
- The SET NOCONTROL=Y command ensures that the
user who logs in under the control of this procedure cannot interrupt
the procedure or any command or program in it.
- The option table lists the commands that the
user will be allowed to execute. Each command is separated by a slash.
- The procedure introduces itself.
- The symbol name PROMPT is given the value of
a label in the procedure. When the procedure is initially invoked, this
symbol has the value INIT. The HELP command text terminates with a GOTO
command that specifies the label PROMPT. When this text is displayed
for the first time, the GOTO command results in a branch to the label
HELP. This displays the HELP message that explains the commands that
you can enter. Then, the procedure branches back to the label INIT,
where the value for PROMPT is changed to "GET_COMMAND". Finally, the
procedure branches to the label FILE to get a file name. Thereafter,
when the help text is displayed, the procedure branches to the label
GET_COMMAND to get the next command.
- The Ctrl/Y condition action is set to return
to the label GET_COMMAND, as is the warning condition action. The
procedure prompts for a command and continues to prompt, even if
nothing is entered. To terminate the session and return to interactive
command level, enter the command DONE.
- The procedure uses the F$LOCATE and F$LENGTH
lexical functions to determine whether the command is included in the
list of options. The F$LOCATE function searches for the user-entered
command, followed by a slash. (For example, if you enter EDIT, the
procedure searches for EDIT/.) If the command is not included in the
option list, then the procedure branches to the label INVALID_COMMAND.
If the command is valid, the procedure branches to the appropriate
label.
- At the label INVALID_COMMAND, the procedure
writes an error message and displays the help text that lists the
commands that are valid.
- The help text lists the commands that are
valid. This text is displayed initially. It is also displayed whenever
the user enters the HELP command or any invalid command.
- At the conclusion of the HELP text, the GOTO
command specifies the symbol name PROMPT. When this procedure is first
invoked, the symbol has the value INIT. Thereafter, it has the value
GET_COMMAND.
- Each valid command in the list has a
corresponding entry in the option table and a corresponding label in
the command procedure. For the commands that read input from the
terminal, for example, EDIT, the procedure contains a DEFINE command
that defines the input stream as SYS$COMMAND.
- At the label BADFILE, the procedure displays
a message indicating that the file must be in the current directory.
Then the procedure prompts for another file name.
- After obtaining a file name, the procedure
checks that you have not specified a directory that is different from
your current default directory. The procedure then uses the F$PARSE
function to extract the file name. (Each command supplies the
appropriate default file type.) Next, the procedure branches back to
the label GET_COMMAND to get a command to process the file.
Sample Execution for FORTUSER.COM Command Procedure
The following example illustrates how to use this command procedure as
a captive command procedure:
Username: CLASS30
Password:
OpenVMS Version 7.1
OpenVMS FORTRAN Command Interpreter
Enter name of file with which you would like to work.
The commands you can enter are:
FILE Name of FORTRAN program in your current
default directory. Subsequent commands
process this file.
EDIT Edit the program.
COMPILE Compile the program with VAX FORTRAN.
LINK Link the program to produce an executable image.
RUN Run the program's executable image.
EXECUTE Same function as COMPILE, LINK and RUN.
DEBUG Run the program under control of the debugger.
PRINT Queue the most recent listing file for printing.
DONE Return to interactive command level.
HELP Print this help message.
Enter Ctrl/Y to restart this session
File name: AVERAGE
Command: COMPILE
Command: LINK
Command: RUN
Command: FILE
File name: READFILE
Command: EDIT
|
This sample execution illustrates a session in which a user named
CLASS30 logs in to the account controlled by the FORTUSER command
procedure. The FORTUSER command procedure displays the commands the
user is allowed to execute, as well as an instruction for restarting
the session. Next, the user specifies the file AVERAGE, compiles,
links, and runs it. Then, the user enters the FILE command to begin
working on another file.
|
