.c.y.h
INTRODUCTION TO
COMMAND PROCEDURES
.w


by



Arthur T. McClinton Jr.

MITRE Corporation


December 1982
.S
.c.y.h
WHAT IS A
COMMAND PROCEDURE?
.x.w

 - A file containing a group of
   DCL commands

 - It may be a series of frequently 
   executed commands

 - It may be a series of complicated
   commands - SYSTEM STARTUP/SHUTDOWN

 - It may be a series of commands to be
   executed in the batch queue.
.S
.c.y.h
SAMPLE
COMMAND PROCEDURE
.x.w
$!	LINK AND TEST VUS AND DVS
$
$SET DEF [PROD.VUS]
$LINK/EXEC=DVS VUS,LOGREQ,VUS1B,ARFVUS,SDRTV,[-.TESTARF]ARFLIB/LI
$LINK VUS,LOGREQ,VUS1C,ARFVUS,SDRTV,[-.TESTARF]ARFLIB/LIB
$PURGE VUS.*,ARFVUS.*,DVS.*
$RUN VUS
DCA
80
DCA
DCAFT
IADSD
BWIUA
 ...
.S
.c.y.h
WHY USE
COMMAND PROCEDURES?
.x.w

 - To simplify the typing of
   frequently used commands

 - To correctly execute
   complicated code

 - To document the method to
   execute a series of commands

 - To simplify commands

 - To create user commands

 - As a programming language
      style
.S
.c.y.h
WHEN TO USE A
COMMAND PROCEDURE
.x.w
 - Required on all jobs
   submitted to the batch queue

         $FORTRAN WEATHER
         $LINK WEATHER
         $RUN WEATHER   
         DCA 01 1246  76  78  

.S
.c.y.h
WHEN TO USE A
COMMAND PROCEDURE
.x.w
 - Required on all jobs
   submitted to the batch queue

 - When you expect to execute the
   same commands more than once.

  !  command file CLGO
  $IF P1 .EQS. "" THEN INQUIRE P1 "FILE"
  $FORTRAN P1
  $LINK P1
  $RUN P1
.S
.c.y.h
WHEN TO USE A
COMMAND PROCEDURE
.x.w
 - Required on all jobs
   submitted to the batch queue

 - When you expect to execute the
   same commands more than once.

 - If you need to execute at
   a specified time
	$SUBMIT/AFTER=12:30 LUNCH
.S
.c.y.h
WHEN TO USE A
COMMAND PROCEDURE
.x.w
 - Required on all jobs
   submitted to the batch queue

 - When you expect to execute the
   same commands more than once.

 - If you need to execute at
   a specified time

 - If yo havf a ard tme tyqing
.S
.c.y.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.x.w
 - @ is the symbol to execute
   a command procedure




     $@CLGO WEATHER

.S
.c.y.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.x.w
 - @ is the symbol to execute
   a command procedure

 - SUBMIT will submit to the
   batch queue


    $SUBMIT/PARAM=("WEATHER") CLGO

.S
.c.y.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.x.w
 - @ is the symbol to execute
   a command procedure

 - SUBMIT will submit to the
   batch queue

 - LOGIN.COM is automatically
   executed during login

   SYS$LOGIN:LOGIN.COM
   EDTINI.EDT
.S
.c.y.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.x.w
 - @ is the symbol to execute
   a command procedure

 - SUBMIT will submit to the
   batch queue

 - LOGIN.COM is automatically
   executed during login

 - Reading a deck of cards
   
   unsolicited input from card
   reader is sent to batch queue
.S
.c.y.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.x.w
 - @ is the symbol to execute
   a command procedure

 - SUBMIT will submit to the
   batch queue

 - LOGIN.COM is automatically
   executed during login

 - Reading a deck of cards
   
 - SPAWN of a subprocess
     $SPAWN/INPUT=COMMANDS/[NO]WAIT
       [/OUTPUT=...]
.S
.c.y.h
CONTROL OF INPUT/OUTPUT
.x.w
 - SYSTEM assigned logical names

    SYS$INPUT
       - program input
       - defaults to current command 
         source
    SYS$OUTPUT
       - program and command output
       - terminal for interactive
       - log file for batch
    SYS$ERROR
      - originally the same as SYS$OUTPUT
    SYS$COMMAND
       - highest level command source
.S
.c.y.hCONTROL OF INPUT/OUTPUT
.x.w
 - Common problems

   1.While in a command file you want 
     input from your terminal.
        $ASSIGN SYS$ERROR SYS$INPUT 

   2.Running an interactive job and want
     output to the printer.
        $ASSIGN/USER LP: SYS$OUTPUT

   3.In a subdirectory and want to 
     submit a command file to the 
     batch queue.

     remember that the command file will
     not be run in the same environment
     (both verify and directory)

   4.Want to suppress output
            NL: is the null device
.S
.c.y.h
USING SYMBOLS
.w.x
 - used to pass information
   from one command to another

 - rules for forming a symbol name
   - first character letter, _, $
   - all letters translated upper
   - may contain numbers
   - length 1-255 characters
   - may be a formed by evaluating
     a symbol     $USER_'P1'=P2
.S
.c.y.h
USING SYMBOLS
.w.x

 - symbol types
   - character or integer
  
   - type assigned by context

   - lexical functions to translate

          F$STRING - integer to string
          F$INTEGER - string to integer

 - when is 1 + 2 not equal to 3?
.S
.c.y.h
USING SYMBOLS
When is 1 + 2 not equal to 3?
.w.x
 $ONE="1"
 $TWO:=2
 $THREE=ONE+TWO
 $SHOW SYM THREE
  THREE = "12"
 $TWO=2
 $THREE=ONE+TWO
 $SHOW SYM THREE
  THREE = 3  Hex...
.S
.c.y.h
SAMPLE USING SYMBOLS
.w.x
$TOP:
$ASSIGN/USER ZZTEMP.LIS SYS$OUTPUT
$SHOW USERS
$OPEN/READ TEMP ZZTEMP.LIS
$READ TEMP LINE
$LINE=LINE - "VAX/VMS " -  " - Total"-
$_ + " " + F$TIME()
$WRITE SYS$OUTPUT LINE
$CLOSE TEMP
$DELETE ZZTEMP.LIS.*
$WAIT 0:01:00
$GOTO TOP

Interactive Users = 1 11-NOV-1982 20:17:
.S
.C.Y.H.$(0
SYMBOLS TABLES
.W.X
       lqqqqqqqqqqqqqqqqqqqqqk
       x  GLOBAL SYMBOLS   5 x
       x                     x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 1 SYMBOLS  4 x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 2 SYMBOLS  3 x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 3 SYMBOLS  2 x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 4 SYMBOLS  1 x<qqq 
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 5 SYMBOLS    x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 6 SYMBOLS    x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 7 SYMBOLS    x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 8 SYMBOLS    x
       mqqqqqqqqqqqqqqqqqqqqqj
.$(B
.S
.C.Y.H
PASSING PARAMETERS
.W.X
 - Up to 9 parameters may be passed
 - P1, P2, P3,... P9

 - Command file syntax
     $@MEMO BIWEEKLY

 - SUBMIT syntax
   $SUBMIT/PAR=("Y",1,BCK) BCKUP
      string number symbol

 - Redefining/using parameters
   $P1=P1+1    not passed out
   $IF P1 .EQS. "" THEN-
   $_  INQUIRE P1 "FILE NAME"
.S
.C.Y.H
PASSING PARAMETERS
.W.X

$!	COMMAND FILE TO REPEAT COMMANDS
$ IF P1 .EQS. "" THEN INQUIRE P1 "COMMAND"
$ IF P2 .EQS. "" THEN INQUIRE P2 "CYCLE TIME IN SECONDS"
$ESC[0,7]=%O33
$WRITE SYS$OUTPUT "''ESC'<"	!ENTER ANSI MODE IF THIS TERMINAL SET TO VT52
$WRITE SYS$OUTPUT "''ESC'[2J"	!CLEAR SCREEN
$N1=P2/60
$N2=P2-N1*60
$TOP:
$write SYS$OUTPUT "''ESC'[H"	!HOME
$'P1'				!EXECUTE THE COMMAND
$write SYS$OUTPUT "''ESC'[J"	!ERASE TO END OF SCREEN
$WAIT 00:'N1':'N2'		!WAIT
$GOTO TOP
.S
.C.Y.H
SYMBOL SUBSTITUTION
.W.X
 - ORDER OF SUBSTITUTION
     1.FIRST TOKEN IF A SYMBOL
     2.LEXICAL FUNCTIONS
     3.EVALUATE THE COMMAND

 - REPETITIVE AND ITERATIVE SUB
        
 - $SET VERIFY
.S
.C.Y.H
LEXICAL FUNCTIONS
.W.X
 - FORMAT

   F$function_name([arg,...])

    function_name may be truncated

    ( ) required

  args
    numeric constant   45
    string constant   "ABC34"
    symbols           THREE
    expressions       PTR+5
    other lexical functions
.S
.C.Y.H
LEXICAL FUNCTIONS
.W.X
  F$CVSI     F$CVTIME   F$CVUI     

 F$DIRECTORY F$EXTRACT  F$FAO

  F$FILE_ATTRIBUTES     F$GETDVI

  F$GETJPI   F$GETSYI   F$INTEGER

  F$LENGTH   F$LOCATE   F$LOGICAL

  F$MESSAGE  F$MODE     F$PARSE  

  F$PID     F$PRIVILEGE F$PROCESS

  F$SEARCH   F$SETPRV   F$STRING 

  F$TIME     F$USER     F$VERIFY
.S
.C.Y.H
Bit LEXICAL FUNCTIONS
.W.X
F$CVSI(bit-position,width,string)

Returns  a signed decimal value


F$CVUI(bit-position,width,string)

Returns  an  unsigned  value
.S.C.Y.H
Character LEXICAL FUNCTIONS
.W.X
F$EXTRACT(offset,length,string)

Returns a  substring of the string.
The first character in a string is 0.


F$LENGTH(string)

Returns the length of the string.


F$LOCATE(substring,string)

Returns the offset of the substring
.S.C.Y.H
Time LEXICAL FUNCTIONS
.W.X
F$CVTIME(time)

INPUT: dd-mmm-yyyy hh:mm:ss.cc
OUTPUT: yyyy-mm-dd hh:mm:ss.cc


F$TIME()

Returns the current date and time
   dd-mmm-yyyy hh:mm:ss.cc
.S.C.Y.H
Directory LEXICAL FUNCTIONS
.W.X
F$DIRECTORY()

Returns the current default directory
including brackets.


F$SEARCH(file-spec [,stream])

Returns the next resultant name string
that matches the given file-spec.
.S.C.Y.H
File LEXICAL FUNCTIONS
.W.X
F$FILE_ATTRIBUTES(file-spec,item)

Returns  file attribute  information


F$PARSE(file-spec [,default-name 
[,related-name [,field]]])

Returns either the expanded file 
specification for  the file you
designate, or the particular 
specification field that you request.
Use to find if a file exists
.S.C.Y.H
En(De)code LEXICAL FUNCTIONS
.W.X
F$FAO(control-string[,argument...])

Returns a formatted string
$FAO system  service


F$INTEGER(string)

Returns the decimal  equivalent


F$STRING(integer)

integer converted to a string.
.S.C.Y.H
Message LEXICAL FUNCTIONS
.W.X

F$MESSAGE(status_code)

Returns the message text.
.S.C.Y.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X
F$GETDVI(device-name,item)

Returns device information


F$GETJPI(pid,item)

Returns  process information.


F$GETSYI(item)

Returns system information
.S.C.Y.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X
F$LOGICAL(logical-name)

Returns the equivalence name string
of the given logical-name. Only one
level of translation is performed.


F$MODE()

"BATCH","INTERACTIVE",or "NETWORK"


F$PID(context)

Returns the next PID
.S.C.Y.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X
F$PRIVILEGE(priv-list)

TRUE/FALSE


F$PROCESS()

Returns current process name string.


F$SETPRV(priv-list)

Set privileges and return string to
all resetting to original condition.
.S.C.Y.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X
F$USER()

Returns the current UIC as a string


F$VERIFY([value])

Return and optionally set VERIFY
.S
.C.Y.H
WARNINGS ABOUT
LEXICAL FUNCTIONS
.W.X
1. Lexical functions are evaluated
   while skipping lines in a GOTO

2. Lexical functions in comment lines
   are evaluated

3. This may change privilege or
   verify states!!!!!!
.y.h$!N=F$VERIFY(0)
.S
.C.Y.H
CONTROLLING EXECUTION FLOW
.W.X
.Y.HIF
.W.X  Separate string and numeric tests
  IF ... THEN $statemnt to exec if true
.y.hGOTO
.W.X  Absolute transfer to label
.y.hEXIT
.W.X  exit the command proc level
  with optional status.
.y.hSTOP
.w.x  return to top command level
  with optional status.
.S
.C.Y.H
ERROR HANDLING
.W.X
.Y.HON ERROR
.w.x  Can be used to divert control
  when an error condition exists

.y.hSET [NO]ON
.W.X  used to stop recognition
  of errors.

.y.h$STATUS
.W.X  may be tested to determine the
  exact error_code.  F$MESSAGE($STATUS)
.S
.C.Y.H
INTERRUPT HANDLING

ON CONTROL_Y THEN
.w.x
  Can be used to divert control
  when control y is received.


.y.hSET [NO]CONTROL=Y
.W.X
  -  NOT UPWARD COMPATIBLE FROM 2.5
  -  CONTROL=T
  -  WARNING ABOUT DISABLING
     can no longer stop process
.S
.C.Y.H
FILE I/O
.w.x
 - OPEN
    create new files
    access existing files

 - READ
    read a record into a string
    symbol.
    return end-of-file information
    may read a keyed file

 - WRITE
    write a string symbol to a
    file.

 - CLOSE
    close a file
.S
.C.Y.H



SAMPLES

.S
.C.Y.H



THE END
.S
.C
.Y.WCOMMANDFILE TO CREATE A MEMO
.L.X
$ IF P1 .NES. "" THEN MEMO_FILE==P1
$ IF MEMO_FILE .NES. "" THEN GOTO test
$ IF P1 .EQS. "" THEN INQUIRE/global MEMO_FILE "NAME OF MEMO FILE"
$!	CHECK TO SEE IF FILE ALREADY EXITS
$test: OPEN/READ/ERR=NOT_FOUND INFILE 'MEMO_FILE'.RNO
$CLOSE INFILE
$GOTO EDIT
$NOT_FOUND: COPY DBC4:[ART.BIWEEKLY]MEMOFORM.RNO 'MEMO_FILE'.RNO
$EDIT:  DEFINE/USER SYS$INPUT SYS$COMMAND:
$EDT 'MEMO_FILE'.RNO
$on error then goto edit_ques
$RUNOFF 'MEMO_FILE'
$SPELL 'MEMO_FILE'.MEM
$INQUIRE ANS "PRINT A COPY OF THE MEMO"
$IF ANS THEN GOTO PRINT
$edit_ques: INQUIRE ANS "RE-EDIT MEMO"
$IF ANS THEN GOTO EDIT
$EXIT
$PRINT: PRINT/DEV=TTB6: 'MEMO_FILE'.MEM
$PURGE 'MEMO_FILE'.*
.S