.p.h
INTRODUCTION TO
COMMAND PROCEDURES
.w 
(VA147)

by


Arthur T. McClinton Jr.

MITRE Corporation
7525 Colshire Dr
McLean, Va 22102



October 1988
.S.p.h
WHAT IS A
COMMAND PROCEDURE?
.X.W.v

 - A file containing a group of
   DCL commands and data lines

 - 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 or on 
   another computer.
.S.p.h
SAMPLE
COMMAND PROCEDURE
.X.W.V
 
$!	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.p.h
COMMAND PROCEDURE FORMAT
.X.W.v

 - DCL Statements

 - DCL Comments

 - Using Multiple Lines

 - Data lines
   - usually no leading $
   - DECK and EOD commands
 
 - Blank lines
.S.p.h
WHY USE
COMMAND PROCEDURES?
.X.W.v

 - 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.p.h
WHEN TO USE A
COMMAND PROCEDURE
.X.W.v 
 - Required on all jobs
   submitted to the batch queue

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

.S.p.h
WHEN TO USE A
COMMAND PROCEDURE
.X.W.v 
 - 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.p.h
WHEN TO USE A
COMMAND PROCEDURE
.X.W.v 
 - 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.p.h
WHEN TO USE A
COMMAND PROCEDURE
.X.W.v 
 - 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.p.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.X.W.v 
 - @ is the symbol to execute
   a command procedure




     $@CLGO WEATHER

.S.p.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.X.W.v 
 - @ is the symbol to execute
   a command procedure

 - SUBMIT will submit to the
   batch queue


    $SUBMIT/PARAM=("WEATHER") CLGO

.S.p.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.X.W.v 
 - @ 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.p.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.X.W.v 
 - @ 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.p.h
HOW TO EXECUTE A
COMMAND PROCEDURE
.X.W.v 
 - @ 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.p.h
EXECUTING A COMMAND 
PROCEDURE ON REMOTE NODE
.X.W.v 
$! SHOWUSERS.COM
$ IF F$MODE() >EQS. "NETWORK" THEN -
  DEFINE/USER SYS$OUTPUT SYS$NET
$ SHOW USERS

TYPE ODLVX::"TASK=SHOWUSERS.COM"

.S.p.h
CONTROL OF INPUT/OUTPUT
.X.W.v 
 - 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.p.hCONTROL OF INPUT/OUTPUT
.X.W.v 
 - 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

   4.Want to suppress output
            NL: is the null device
.S.p.h
USING SYMBOLS
.W.X.v 
 - 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.p.h
USING SYMBOLS
.W.X.v 

 - 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.p.h
USING SYMBOLS
When is 1 + 2 not equal to 3?
.W.X.v 
 $ONE="1"
 $TWO:=2
 $THREE=ONE+TWO
 $SHOW SYM THREE
  THREE = "12"
 $TWO=2
 $THREE=ONE+TWO
 $SHOW SYM THREE
  THREE = 3  Hex...
.S.p.h
SAMPLE USING SYMBOLS
.W.X.v 
$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.p.H.$(0
SYMBOL TABLES
.W.X.v 
       lqqqqqqqqqqqqqqqqqqqqqk
       x  GLOBAL SYMBOLS   5 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 ... SYMBOLS  x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 31 SYMBOLS   x
       tqqqqqqqqqqqqqqqqqqqqqu
       x  LEVEL 32 SYMBOLS   x
       mqqqqqqqqqqqqqqqqqqqqqj
.$(B
.S.p.H
PASSING PARAMETERS
.W.X.v 
 - 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.p.H
PASSING PARAMETERS
.W.X.v 

$!	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.p.H
SYMBOL SUBSTITUTION
.W.X.v 
 - ORDER OF SUBSTITUTION
     1.FIRST TOKEN IF A SYMBOL
     2.LEXICAL FUNCTIONS
     3.EVALUATE THE COMMAND

 - REPETITIVE AND ITERATIVE SUB
        
 - $SET VERIFY
.S.p.H
LEXICAL FUNCTIONS
.W.X.v 
 - 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.p.H
LEXICAL FUNCTIONS
.W.X.v 
  - Bit oriented

  - Character

  - String Editing

  - Time conversion

  - Directory

  - File characteristics

  - Message sending

  - Process information

  - System wide information
.S.p.H
Bit LEXICAL FUNCTIONS
.W.X.v 
F$CVSI(bit-position,width,string)

Returns  a signed decimal value


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

Returns  an  unsigned  value
.S.p.H
Character LEXICAL FUNCTIONS
.W.X.v 
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

F$ELEMENT(Element_number,delimiter,string)

extracts the desired element
.S.p.H
En(De)code LEXICAL FUNCTIONS
.W.X.v 
F$FAO(control-string[,argument...])

Returns a formatted string

F$EDIT(String,edit_list)

returns an edited list

F$INTEGER(string)

Returns the decimal  equivalent


F$STRING(integer)

integer converted to a string.
.S.p.H
Time LEXICAL FUNCTIONS
.W.X.v 
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.p.H
Directory LEXICAL FUNCTIONS
.W.X.v 
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.p.H
File LEXICAL FUNCTIONS
.W.X.v 
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.p.H
Message LEXICAL FUNCTIONS
.W.X.v 

F$MESSAGE(status_code)

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

Returns device information


F$GETJPI(pid,item)

Returns  process information.


F$GETSYI(item)

Returns system information
.S.p.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X.v 
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.p.H
SYSTEM, DEVICE, PROCESS
INFO LEXICAL FUNCTIONS
.W.X.v 
F$ENVIRONMENT(item)

information about the DCL envirnmt.

F$PROCESS()

Returns current process name string.

F$PRIVILEGE(priv-list)

Test for the ability to set a privilege

F$SETPRV(priv-list)

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

Returns the current UIC as a string


F$VERIFY([value])

Return and optionally set VERIFY
.S.p.H
CONTROLING EXECUTION FLOW
.W.X.v 
.Y.HIF
.W.X  Separate string and numeric tests

  IF ... THEN $statemnt to exec if true

  $ IF expression
  $   THEN
  $     command
  $     command
  $   ELSE
  $     command
  $     command
  $ ENDIF
.S.p.H
CONTROLING EXECUTION FLOW
.W.X.v 
.Y.HGOSUB
.W.X  Transfers control to labeled
  subroutine.
  Can nest 16 levels deep
  terminate with return
  Same procedure level
.y.HCALL
.w.x  Transfers control to labeled
  command procedure
  Same as @ but not new file
  new procedure level
  SUBROUTINE ENDSUBROUTINE
.S.p.H
CONTROLING EXECUTION FLOW
.W.X.v 
.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.p.H
ERROR HANDLING
.W.X.v 
.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.p.H
INTERRUPT HANDLING
.v 
ON CONTROL_Y THEN
.W.X 
  Can be used to divert control
  when control y is received.
  Current statement aborted

.y.hSET [NO]CONTROL=Y
.W.X 
  -  WARNING ABOUT DISABLING
     can no longer stop process
.S.p.H
FILE I/O
.X.W.v 
 - 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.p.hTESTING & DEBUGGING
.x.w.v 
 - SET VERIFY 
    shows each line before exec.

 - TOP DOWN TESTING
    test flow using stubs

 - SHOW SYMBOL
    print values of symbols in 
    control loops.

.S.p.hRESTORE ENVIRONMENT
.x.w.v 
 - Close any files opened

 - delete temporary files created

 - purge files edited.

 - reset directory, prompt, priv
.S.p.hTESTING FOR REMOTE NODE UP
.X.W.V

$ON ERROR THEN $GOTO CCELMVDOWN
$DIR ccelmv::nl:
%DIRECT-E-OPENIN, error opening ...
-RMS-E-FND, ACP file or directory...
-SYSTEM-F-UNREACHABLE, remote node
   is not currently reachable

      - or -
-SYSTEM-F-NOSUCHNODE, remote node 
  unknown ...

      - or -
Directory MWVMS::NL:[DECNET]
 ...
Control drops thru if node is up
.S.p.v




THE END
.s