HELPLIB.HLB  —  @
    Executes a command procedure or requests the command interpreter
    to read subsequent command input from a specific file or device.

    Format

      @  filespec [parameter[,...]]

1  –  Parameters

 filespec

    Specifies either the input device or the file for the preceding
    command, or the command procedure to be executed. The default
    file type is .COM. The asterisk (*)  and the percent sign (%)
    wildcard characters are not allowed in the file specification.

 parameter[,...]

    Specifies from one to eight optional parameters to pass to the
    command procedure. The symbols (P1, P2, . . . P8) are assigned
    character string values in the order of entry.

    Setting bit 3 of DCL_CTLFLAGS to 1, specifies from one to sixteen
    optional parameters to pass to the command procedure. The symbols
    (P1, P2, . . . P16) are assigned character string values in the
    order of entry. If you clear the bit 3 of DCL_CTLFLAGS, the
    default parameters are set (that is, (P1, P2, . . . P8)).

    The symbols are local to the specified command procedure.
    Separate each parameter with one or more blanks. Use two
    consecutive quotation marks ("")  to specify a null parameter.
    You can specify a parameter with a character string value
    containing alphanumeric or special characters, with the following
    restrictions:

    o  The command interpreter converts alphabetic characters to
       uppercase and uses blanks to delimit each parameter. To pass a
       parameter that contains embedded blanks or literal lowercase
       letters, place the parameter in quotation marks.

    o  If the first parameter begins with a slash (/),  you must
       enclose the parameter in quotation marks (" ").

    o  To pass a parameter that contains literal quotation marks
       and spaces, enclose the entire string in quotation marks and
       use two consecutive quotation marks within the string. For
       example, the command procedure TEST.COM contains the following
       line:

       $ WRITE SYS$OUTPUT P1

       Enter the following at the DCL prompt ($):

       $ @TEST "Never say ""quit"""

       When the procedure TEST.COM executes, the parameter P1 is
       equated to the following string:

       Never say "quit"

       If a string contains quotation marks and does not contain
       spaces, the quotation marks are preserved in the string and
       the letters within the quotation marks remain in lowercase.
       For example, enter the following at the DCL prompt:

       $ @TEST abc"def"ghi

       When the procedure TEST.COM executes, the parameter P1 is
       equated to the following string:

       ABC"def"GHI

    To use a symbol as a parameter, enclose the symbol in single
    quotation marks (` ')  to force symbol substitution. For example:

    $ NAME = "JOHNSON"
    $ @INFO 'NAME'

    The single quotation marks cause the value "JOHNSON" to be
    substituted for the symbol NAME. Therefore, the parameter
    "JOHNSON" is passed as P1 to INFO.COM.

2  –  Qualifier

2.1    /OUTPUT

       /OUTPUT=filespec

    Specifies the name of the file to which the command procedure
    output is written. By default, the output is written to the
    current SYS$OUTPUT device. The default output file type is
    .LIS. The asterisk (*)  and the percent sign (%) wildcard
    characters are not allowed in the output file specification.
    System responses and error messages are written to SYS$COMMAND
    as well as to the specified file. The /OUTPUT qualifier must
    immediately follow the file specification of the command
    procedure; otherwise, the qualifier is interpreted as a parameter
    to pass to the command procedure.

    You can also redefine SYS$OUTPUT to redirect the output from a
    command procedure. If you place the following command as the
    first line in a command procedure, output will be directed to the
    file you specify:

    $ DEFINE SYS$OUTPUT filespec

    When the procedure exits, SYS$OUTPUT will be restored to its
    original equivalence string. This produces the same result
    as using the /OUTPUT qualifier when you execute the command
    procedure.

3  –  Examples

    1.$ CREATE DOFOR.COM
      $ ON WARNING THEN EXIT
      $ IF P1.EQS."" THEN INQUIRE P1 FILE
      $ FORTRAN/LIST 'P1'
      $ LINK 'P1'
      $ RUN 'P1'
      $ PRINT 'P1'
 <Ctrl/Z>

      $ @DOFOR AVERAGE

      This example shows a command procedure, named DOFOR.COM, that
      executes the FORTRAN, LINK, and RUN commands to compile,
      link, and execute a program. The ON command requests that
      the procedure not continue if any of the commands result in
      warnings or errors.

      When you execute DOFOR.COM, you can pass the file specification
      of the FORTRAN program as the parameter P1. If you do not
      specify a value for P1 when you execute the procedure, the
      INQUIRE command issues a prompting message to the terminal and
      equates what you enter with the symbol P1. In this example,
      the file name AVERAGE is assigned to P1. The file type is not
      included because the commands FORTRAN, LINK, RUN, and PRINT
      provide default file types.

    2.$ @MASTER/OUTPUT=MASTER.LOG

      This command executes a procedure named MASTER.COM; all output
      is written to the file MASTER.LOG.

    3.$ CREATE FILES.COM
      *.FOR, *.OBJ
 <Ctrl/Z>

      $ DIRECTORY @FILES

      This example shows a command procedure, FILES.COM, that
      contains parameters for a DCL command line. The entire file is
      treated by DCL as command input. You can execute this procedure
      after the DIRECTORY command to get a listing of all FORTRAN
      source and object files in your current default directory.

    4.$ CREATE QUALIFIERS.COM
      /DEBUG/SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE
 <Ctrl/Z>

      $ LINK SYNAPSE@QUALIFIERS

      This example shows a command procedure, QUALIFIERS.COM, that
      contains qualifiers for the LINK command. When you enter the
      LINK command, specify the command procedure immediately after
      the file specification of the file you are linking. Do not type
      a space between the file specification and the @ command.

    5.$ CREATE SUBPROCES.COM
      $ RUN 'P1' -
        /BUFFER_LIMIT=1024 -
        /FILE_LIMIT=4 -
        /PAGE_FILES=256 -
        /QUEUE_LIMIT=2 -
        /SUBPROCESS_LIMIT=2 -
        'P2'  'P3'  'P4'  'P5'  'P6'  'P7'  'P8'
 <Ctrl/Z>

      $ @SUBPROCES  LIBRA  /PROCESS_NAME=LIBRA

      This example shows a command procedure named SUBPROCES.COM.
      This procedure issues the RUN command to create a subprocess to
      execute an image and also contains qualifiers defining quotas
      for subprocess creation. The name of the image to be run is
      passed as the parameter P1. Parameters P2 to P8 can be used to
      specify additional qualifiers.

      In this example, the file name LIBRA is equated to P1; it
      is the name of an image to execute in the subprocess. The
      qualifier /PROCESS_NAME=LIBRA is equated to P2; it is an
      additional qualifier for the RUN command.

    6.$ CREATE EDOC.COM
      $ ASSIGN SYS$COMMAND:  SYS$INPUT
      $ NEXT:
      $      INQUIRE NAME "File name"
      $      IF NAME.EQS."" THEN EXIT
      $      EDIT/TPU 'NAME'.DOC
      $      GOTO NEXT
 <Ctrl/Z>

      $ @EDOC

      This procedure, named EDOC.COM, invokes the EVE editor. When
      an edit session is terminated, the procedure loops to the
      label NEXT. Each time through the loop, the procedure requests
      another file name for the editor and supplies the default
      file type .DOC. When a null line is entered in response to
      the INQUIRE command, the procedure terminates with the EXIT
      command.

      The ASSIGN command changes the equivalence name of SYS$INPUT
      for the duration of the procedure. This change allows the EVE
      editor to read input data from the terminal, rather than from
      the command procedure file (the default input data stream if
      SYS$INPUT had not been changed). When the command procedure
      exits, SYS$INPUT is reassigned to its original value.

    7.! PEOPLE.DAT
      ! A set of data with embedded key qualifiers for the SORT command.
      !
      ! Usage: SORT@PEOPLE.DAT
      !
      /KEY=(POS:10,SIZE:10) sys$input people.out
      Fred     Flintstone    555-1234
      Barney   Rubble        555-2244
      Wilma    Flintstone    555-1234
      Betty    Rubble        555-2244
      George   Slate         555-8911
      Dino     Dinosaur      555-1234
      $!
      $ purge people.out
      $ type people.out

      Creates a sorted list of people in file PEOPLE.OUT and displays
      it. This demonstrates when using "@" in the middle of a DCL
      command, DCL redirects the entire file as command input.

    8.$ CREATE SUBPROCES.COM
      $ RUN 'P1' -
        /BUFFER_LIMIT=1024 -
        /FILE_LIMIT=4 -
        /PAGE_FILES=256 -
        /QUEUE_LIMIT=2 -
        /SUBPROCESS_LIMIT=2 -
        'P2'  'P3'  'P4'  'P5'  'P6'  'P7'  'P8' 'P9'
        'P10' 'P11' 'P12'  'P13'  'P14'  'P15'  'P16'
 <Ctrl/Z>

      $ @SUBPROCES  LIBRA  /PROCESS_NAME=LIBRA

      This example shows a command procedure named SUBPROCES.COM.
      This procedure issues the RUN command to create a subprocess to
      execute an image and also contains qualifiers defining quotas
      for subprocess creation. The name of the image to be run is
      passed as the parameter P1. Parameters P2 to P16 can be used to
      specify additional qualifiers. This is applicable if bit 3 of
      DCL_CTLFAGS is set to 1. In this example, the file name LIBRA
      is equated to P1; it is the name of an image to execute in the
      subprocess. The qualifier /PROCESS_NAME=LIBRA is equated to P2;
      it is an additional qualifier for the RUN command.
Close Help