1 ZSET
!
The ZSET utility puts the contents of selected lines of a file into local DCL
Symbols.

The syntax of the ZSET command is:

	$ ZSET file_name [ /qualifier ... ]

The two main qualifiers for selecting lines are /LINE and /STRING.  See the
description of the /SYMBOL qualifier to see the names of DCL Symbols that
ZSET creates.
!
2 Examples
!
Assume the file MYFILE.DAT contains the following records:

	1. Author:  Alan L. Zirkle
	2. Phone:   (703) 663-8023
	3. Address:
	4.      Naval Surface Warfare Center
	5.      Code K55
	6.      Dahlgren, Virginia  22448

Example 1:  $ ZSET MYFILE.DAT
            $ SHOW SYMBOL /ALL
               ZSET_STATUS = "T1"
               ZSET_STRING = "1. Author:  Alan L. Zirkle"

            Since no qualifiers are present on the command line, the
            contents of the first line of the file are saved.

Example 2:  $ ZSET MYFILE.DAT /STRING="Phone:"
            $ SHOW SYMBOL /ALL
               ZSET_STATUS = "T1"
               ZSET_STRING = "2. Phone:   (703) 663-8023"

Example 3:  $ ZSET MYFILE.DAT /STRING="PHONE:"
            $ SHOW SYMBOL /ALL
               ZSET_STATUS = "F"

            The /STRING qualifier must be specified in the correct case.

Example 4:  $ ZSET MYFILE.DAT /STRING="Address" /LINE=1 /COUNT=8 /SYMBOL=X
            $ SHOW SYMBOL /ALL
               ZSET_STATUS = "T3"
               X_0 = "4.      Naval Surface Warfare Center"
               X_1 = "5.      Code K55"
               X_2 = "6.      Dahlgren, Virginia  22448"

            We asked for eight lines, starting one line after the string
            "Address", but the file ended after three lines.
!
2 Parameter
!
ZSET has one parameter; the name of the file from which ZSET will set DCL 
Symbols based on the file's contents.
!
2 Qualifiers
!
/COLUMN

  /COLUMN=n

  The /COLUMN qualifier can only be used when the /STRING qualifier is also
  used.  It specifies the column in which the string must begin.  If the
  /COLUMN qualifier is not specified, the string can begin in any column.

/COUNT

  /COUNT=n

  The /STRING and /LINE qualifiers are used to locate the line(s) in the
  file which are to be saved as the values of DCL Symbols.  Once a matching
  line is located, the /COUNT value specifies how many subsequent lines are
  saved.  The default is 1, meaning that only the matching line is saved.

  Example:  ZSET MYFILE.DAT /STRING="XX" /COUNT=2

  ZSET searches the file MYFILE.DAT for the string "XX".  When the first
  occurence is found, the contents of the line containing it is saved in
  DCL Symbol ZSET_STRING_0, and the contents of the very next line in the
  file is saved in DCL Symbol ZSET_STRING_1.

  Note that while ZSET is saving lines due to the /COUNT qualifier, it is
  not checking those lines for occurrences of the /STRING value, or checking
  whether those lines match the /LINE qualifier value.

  Also note that there is a limit to the number of DCL Symbols which you
  can create.  Although the limit is normally quite large, you can reach
  it if you are not careful.

/LINE

  /LINE=n

  The operation of the /LINE qualifier depends on whether the /STRING
  qualifier is also present.

  If neither the /LINE nor the /STRING qualifier is present, then ZSET
  saves the contents of the first line of the file in a DCL Symbol.  If
  the /COUNT=j qualifier is present, then the first J lines of the file
  are saved.

  If the /LINE=n qualifier is present, but the /STRING qualifier is not,
  then ZSET saves the contents of the Nth line of the file in a DCL Symbol.
  If the /COUNT=j qualifier is also present, then the Nth line and the fol-
  lowing J-1 lines are saved.

  If both the /LINE=n and /STRING="xxx" qualifiers are present, then ZSET
  searches for a line containing the specified string.  When a matching
  line is found, then the Nth line AFTER that is saved in a DCL Symbol.
  If the /COUNT=j qualifier is also present, then that line and the follow-
  ing J-1 lines are saved.

  When ZSET is skipping lines to the Nth line after the occurrence of the
  string, it does not check those lines for the string.

  See the description of the /SYMBOL qualifier to see the names of the DCL
  Symbols that ZSET creates.

/OCCURRENCE

  /OCCURRENCE=n

  The /OCCURRENCE qualifier can only be used when the /STRING qualifier is
  also used.  It specifies that the line containing Nth occurrence of the
  string is to be saved, instead of the first occurrence.

  Note that each line of the file is checked only once for the string; if
  the string appears twice on one line, that only counts as one occurrence.

/STRING

  /STRING="quoted_string"

  When the /STRING qualifier is used, ZSET searches for the occurrence of
  the specified string in the file.

  The search string must be specified exactly as it appears in the file;
  i.e. in uppercase or lowercase, etc.  The string must be specified in
  quotation marks.  If the /COLUMN qualifier is used, the string must
  appear in the file with its first character in the specified column.

  Normally, ZSET searches for the FIRST occurrence of the string, but the
  /OCCURRENCE and /SUCCEEDING qualifiers may be used to modify this.

  If the /STRING qualifier is used and the /LINE qualifier is not, then the
  line containing the string is saved in a DCL symbol.  If the /LINE=n qual-
  ifier is used, then the Nth line after that is saved instead.

  See the description of the /SYMBOL qualifier to see the names of the DCL
  Symbols that ZSET creates.

/SUCCEEDING

  /SUCCEEDING=n

  The /SUCCEEDING qualifier can only be used when the /STRING qualifier is
  also used.

  By default, ZSET searches for only one occurrence of the search string.
  Normally, it searches for the first occurrence, or the Kth occurrence if
  the /OCCURRENCE=k qualifier is present.

  If /SUCCEEDING=n is specified, then the N following occurrences of the
  string are also saved in DCL Symbols.

  See the description of the /SYMBOL qualifier to see the names of the DCL
  Symbols that ZSET creates.

  Note that there is a limit to the number of DCL Symbols which you can
  create.  Although the limit is normally quite large, you can reach it
  if you are not careful.

/SYMBOL

  /SYMBOL=symbol_name

  By default, ZSET saves the contents of the specified line of the file in
  local DCL Symbol ZSET_STRING.  If there is the possibility that more than
  one line may be saved (i.e. the /COUNT and/or /SUCCEEDING qualifiers are
  used), then the symbols are named ZSET_STRING_0, ZSET_STRING_1, etc.

  If the /SYMBOL qualifier is used, then it gives the DCL Symbol name to be
  used instead of ZSET_STRING (or ZSET_STRING_n).

  Example 1:  $ ZSET MYFILE.DAT /SYMBOL=XXX

         The contents of the first line of MYFILE.DAT are placed in local
         DCL Symbol XXX.

  Example 2:  $ ZSET MYFILE.DAT /SYMBOL=XXX /COUNT=2

         The contents of the first two lines of MYFILE.DAT are placed in
         local DCL Symbols XXX_0 and XXX_1.

  ZSET also creates a local DCL Symbol called ZSET_STATUS.  If no matching
  lines are found, ZSET_STATUS will be set to "F".  If one matching line
  is found, ZSET_STATUS will be set to "T1".  If N matching lines are
  found, ZSET_STATUS will be set to "Tn", where "n" is a decimal integer.

/VERSION

  This qualifier causes ZSET to display on the SYS$OUTPUT file its current
  version number and date, in the format:

        NSWC ZSET Rev n.nnn Created dd-mmm-yyyy hh:mm

  If /VERSION is used, ZSET does not allow you to specify the filename
  parameter on the command line, and exits after displaying its version.

