Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS User's Manual
Previous Contents Index
  1. 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.
  2. The procedure writes a header for the display.
  3. 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.
  4. 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.
  5. 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.
  6. 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 


$ @SYS



   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.

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

  1. The procedure saves the current image and procedure verification settings before turning off verification.
  2. If a question mark character was passed to the procedure as a parameter, the procedure branches to the label TELL (Note 6).
  3. 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.
  4. 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.
  5. The original verification settings are restored.
  6. 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.

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

  1. 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.
  2. The procedure checks whether a parameter was entered. If not, the procedure prompts for a file type.
  3. 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.
  4. 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.
  5. The OPEN command opens the directory output file and gives it a logical name of DIRFILE.
  6. 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.
  7. 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.

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

  1. The DEFINE command allows the editor input to come from the terminal instead of the command file.
  2. The IF statement distinguishes between editing a file with a different output file name from editing a file with the same file name.
  3. 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'

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

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

  1. 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.
  2. The option table lists the commands that the user will be allowed to execute. Each command is separated by a slash.
  3. The procedure introduces itself.
  4. 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.
  5. 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.
  6. 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.
  7. At the label INVALID_COMMAND, the procedure writes an error message and displays the help text that lists the commands that are valid.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6489PRO_048.HTML