HP OpenVMS Systems Documentation

The following qualifiers can be used in specification files. (The high-performance Sort/Merge utility does not support specification files. Implementation of this feature is deferred to a future OpenVMS Alpha release.) Note that these qualifiers are valid only within a Sort/Merge specification file.

/CDD_PATH_NAME="cdd-path-name"

Identifies fields and attributes defined for use with the Common Data Dictionary (CDD/Plus) using the CDD/Repository command. Once the fields have been identified, they can then be used later with other specification file qualifiers, such as /KEY, /CONDITION, /INCLUDE, or /OMIT.
/CDD_PATH_NAME can be used in place of or in conjunction with /FIELD statements.
The "cdd-path-name" value is the CDD/Plus record definition within CDD/Plus. You can use the /CDD_PATH_NAME qualifier only if your system has CDD/Plus installed.
Example

/CDD_PATH_NAME="customer"

The /CDD_PATH_NAME qualifier identifies the customer record, which had been defined previously in CDD/Plus.

/[NO]CHECK_SEQUENCE

(Applies to the MERGE command only.) Specifies whether or not the sequence of records in the input file is checked. By default, Merge checks the sequence of records.
Example

/NOCHECK_SEQUENCE

The /NOCHECK_SEQUENCE qualifier overrides the Merge utility's default behavior.

/COLLATING_SEQUENCE=(SEQUENCE=sequence-type
[,MODIFICATION=("char1" operator "char2")] [,IGNORE=character or character range,...] [,FOLD] [,[NO]TIE_BREAK])

Specifies one of three predefined collating sequences (ASCII, EBCDIC, or Multinational) or a user-defined sequence for character key fields. Allows you to modify any of the predefined collating sequences or any previously defined user-defined sequences.
See Section 11.3 for information about using the ASCII, EBCDIC, and Multinational collating sequences.
You can specify the following qualifier values:

SEQUENCE	Specification files support the ASCII, EBCDIC, multinational, and user-defined collating sequences. See Section 11.3 for information about these collating sequences.
MODIFICATION	Specifies a change to the collating sequence specified in the SEQUENCE option. You can modify the ASCII, EBCDIC, Multinational, or user-defined sequence. The sequence being modified must be specified with the SEQUENCE qualifier even if the sequence is the default (ASCII). character Specifies a character in the collating sequence. operator Specifies the operator used to compare the characters. You can specify greater than (>), less than (<), or equal to (=).
	The following kinds of changes are permitted in the MODIFICATION option: -- A single or double character can be equated to a single character that has already been assigned a collating value ("a"="A"). -- A single or double character can collate after a single character that has already been assigned a collating value ("CH">"C"). -- A single or double character can collate before a single character that has already been assigned a collating value ("D"<"A"). -- A double character can be equated to a previously defined double character ("CH" = "SH"). -- A single character can be equated to a double character sequence ("C" = "CH").
IGNORE	Specifies that Sort/Merge ignore a character or character range in the collating sequence when making an initial comparison. Note that, when tie-breaking takes place, Sort/Merge considers the characters specified with the IGNORE value.
FOLD	Specifies that all lowercase letters be given the collating value of their uppercase equivalents. For ASCII, EBCDIC, and user-defined sequences, the lowercase letters are a to z.
	Because the lowercase letters in the Multinational sequence already have the collating value of their uppercase equivalents, using FOLD is unnecessary.
[NO]TIE_BREAK	Specifies whether or not Sort/Merge should use numeric values to break any ties between characters that have equivalent values. By default, tie-breaking occurs with the Multinational sequence. Specifying NOTIE_BREAK overrides this default and ensures that no further comparisons are made after the initial comparison.
	A TIE_BREAK option must be specified for the ASCII, EBCDIC, and user-defined sequences in order for tie-breaking to occur. TIE_BREAK should be used when specifying the FOLD or MODIFICATION value for the these sequences.

Examples
See Section 11.3 and Section 11.7 for examples of the use of collating sequences in specification files.

/CONDITION=(NAME=condition-name,
TEST=(field-name operator test-condition [logical-operator...]))

A specification file can be used to change the relative order of a record or to alter the contents of certain fields in a record. You must first use the /CONDITION qualifier to define a conditional test. Once you define a test using the /CONDITIONAL qualifier, you can use that same test with the /KEY or /DATA qualifier to change the order of record. You can also use the test with the /OMIT or /INCLUDE qualifier to change the contents of a record.
If you want to change the order of records in the output file, first specify a condition name with the /CONDITION qualifier and set up a test for what meets that condition. Then, specify the relative order with the /KEY qualifier of the form:

/KEY=(IF condition-name THEN value ELSE value)

You can use any values to specify the relative order of the records.
The /CONDITION qualifier also permits you to change the contents of a field in the output records. First specify a condition name, and then set up a test for what meets the condition. Specify the contents you want in the field in a /DATA qualifier of the form:

/DATA=(IF condition-name THEN "new-contents" ELSE "new-contents")

You can specify the following qualifier values:

NAME

Specifies the name of the condition that you are testing. This condition-name can be used in /KEY, /DATA, /OMIT, and /INCLUDE qualifiers after it has been defined using the /CONDITION qualifier.

TEST

Specifies the conditional test. field-name Specifies the name of the field you are testing. The field-name must be defined previously by the /FIELD qualifier. operator Specifies the logical or relational operator used in the conditional test. The logical operators that you can use are AND and OR. The relational operators that you can specify are as follows: EQ = Equal to NE = Not equal to GT = Greater than GE = Greater than or equal to LT = Less than LE = Less than or equal to test-condition Specifies the constant or field-name against which you are testing. A constant is specified with the following format: Decimal_digits (default) %Ddecimal_digits %Ooctal_digits %Xhexadecimal_digits "character"   Normally, you do not need to specify the radix operator (%D); however, test-condition will assume the same data type as the field-name.

Examples
See Section 11.7 for examples of the use of the /CONDITION qualifier in specification files.

/DATA=field-name
/DATA=(IF condition THEN "new contents" ELSE "new contents")

Use the /DATA qualifier to eliminate or reorder fields from the output record. Specify the data fields in the order you want them to appear in the output record. A /DATA qualifier must identify every field in the records you are directing to the output file. Only those fields identified by the /DATA qualifier are to be directed to the output file.
You can conditionally change the contents of a field in the output records by first specifying a condition name and then setting up a test for what meets the condition in a /CONDITION qualifier. You then specify the contents you want in the field in a /DATA qualifier of the form:

/DATA=(IF condition-name THEN "new-contents" ELSE "new-contents")

You can specify the following qualifier values:

field-name	Specifies the name of a field in a record. The field-name must be defined previously in a /FIELD qualifier.
condition-name	Specifies a condition-name that has been defined previously in a /CONDITION qualifier.
new-contents	Specifies how the record is to be altered. The new-contents can be a constant or a field-name that has been defined in a /FIELD qualifier.

Examples
See Section 11.7 for examples of the use of the /DATA qualifier in specification files.

/FIELD=(NAME=field-name,POSITION:n,SIZE:N,[DIGITS:n,]data-type /FIELD=(NAME=field-name,VALUE:n,SIZE:N,[DIGITS:n,]data-type)

Defines the fields in the input files when you are altering the order or format of output records. These fields include key fields, fields to be compared, and fields to be directed to the output file. You identify each field by specifying a name, its position and size in the record, and its data type.
Field names must be unique; no duplicate field names are allowed. In addition, you cannot use more than 255 field definitions.
You can also use /FIELD to define a constant and assign it a value of any valid Sort/Merge data type for use in /CONDITION, /DATA, and /KEY statements.
You can specify the following qualifier values:

NAME	Specifies the name of the field. The field-name cannot have any embedded spaces, must begin with an alphabetic character, and can be no longer than 31 characters.
POSITION: n	Specifies the position of the field in the record.
VALUE: n	Assigns a value to a constant field for use in a /CONDITION, /DATA, or /KEY statement. If you specify VALUE: n, do not specify /POSITION: n because the field is a constant and not part of an input record.
SIZE: n	Specifies the size of a field containing character or binary data. In the specification file, SIZE implies byte lengths. The data type determines what values are acceptable, as follows: -- For character data, the size must not exceed 32,767 characters. -- For binary data, the size specified must be 1, 2, 4, 8, or 16 bytes. -- For floating-point data, no size is specified.
DIGITS: n	Specifies the size of a field containing decimal data. The size of a field containing decimal data must not exceed 31 digits. Note that DIGITS:n is used only when describing a field containing decimal data.
data-type	Specifies the data type of the field. You are not required to specify the data-type if it is character; Sort assumes character data type by default. See Section 11.2.1 for a list of the data types recognized by Sort/Merge.

Example

/FIELD=(NAME=SALARY,POSITION:10,DIGITS:8,DECIMAL)

This /FIELD qualifier identifies a field in a record by the name SALARY, specifies that it starts in position 10 of the record, is 8 digits long, and consists of decimal data.

/INCLUDE=(CONDITION=condition[,KEY=...] [,DATA=...])

You can specify that records are to be conditionally included in an output file. After defining a condition in a /CONDITION qualifier, specify record selection in an /INCLUDE qualifier requesting that records satisfying the condition are to be included in the output file.
You can specify multiple /INCLUDE and /OMIT qualifiers in a specification file. The order in which you specify them determines the order the input records are tested for inclusion. After the last /INCLUDE qualifier, all records that have not already been included or explicitly omitted are omitted.
You can unconditionally include any records not previously omitted or included by specifying the /INCLUDE qualifier without a condition.
When sorting multiple record formats, one /INCLUDE qualifier should be specified for each different record format among the records to be sorted. If you do not specify a KEY option within the INCLUDE qualifier, Sort assumes the default key definitions. If the KEY is specified in the /INCLUDE qualifier, the default key definitions are not used. The order of the KEY fields in the /INCLUDE qualifier determines how the internal key is built for sorting. The order of the DATA fields in the /INCLUDE qualifier determines the way the output record is formatted. If you specify a key or data field in an /INCLUDE qualifier, you must define all other key or data fields in the record.
You can specify the following qualifier values:

CONDITION	Refers to the condition-name specified in a previous /CONDITION qualifier.
KEY	Defines a key field because the default record type defined in the /KEY qualifier is not being used.
DATA	Defines a data field because the default record type defined in the /DATA qualifier is not being used.

Example

/FIELD=(NAME=ZIP,POSITION:20,SIZE:6) /CONDITION=(NAME=LOCATION, TEST=(ZIP EQ "01863")) /INCLUDE=(CONDITION=LOCATION)

These /CONDITION and /INCLUDE qualifiers specify that records with the zip code 01863 will be included in the output file.

/KEY=field-name
/KEY=(field-name,order) /KEY=([IF condition THEN value ELSE]...) value [,order]

Specify the key fields to be used in the Sort operation. If you are sorting the entire record using character data, there is no need to specify your key field. Otherwise, specify a /KEY qualifier for each of the keys, in the order of their priority. You can sort on as many as 255 key fields.
There are three ways to use the /KEY qualifier:

• To identify the key field name.
• To identify the key field name and to specify sorting order. In this case, enclose the field name and the order option in parentheses.
• As a conditional qualifier, to change the order of records in the output file. First, specify a condition-name in a /CONDITION qualifier, and set up a test for what meets that condition. Then, specify the relative order in a /KEY qualifier of the form:

  /KEY=(IF condition-name THEN value ELSE value)

  
  You can use any values to specify the relative order of the records.

You can specify the following qualifier values:

field-name	Specifies the name of the key field. The field-name has been previously specified in a /FIELD qualifier.
order	Specifies the order of the sort. The ASCENDING option specifies ascending order for a Sort or Merge operation. This option is the default. The DESCENDING option specifies descending order for a Sort or Merge operation.
value	Specifies the key. The value can be a constant or a field-name that has been defined in a /FIELD qualifier.

Examples

1. /FIELD=(NAME=SALARY,POSITION:10,DIGITS:8,DECIMAL) /KEY=(SALARY,DESCENDING)

   
   This /KEY qualifier specifies that the key field is SALARY and that the sorting order is descending.

2. /FIELD=(NAME=ZIP,POSITION:20,SIZE:6) /CONDITION=(NAME=LOCATION, TEST=(ZIP EQ "01863")) /KEY=(IF LOCATION THEN 1 ELSE 2)

   
   In this example, all the records with the zip code 01863 are to appear at the beginning of the sorted output file. The conditional test LOCATION (defined in a /CONDITION qualifier) is on the ZIP field (named in a /FIELD clause). The values of 1 and 2 in this /KEY clause signify a relative order for those records that satisfy the condition and those that do not.

/OMIT=(CONDITION=condition-name)

Specifies that records are to be omitted from the output file based on a condition defined with a /CONDITION qualifier.
First, you must define a condition with the /CONDITION qualifier. Specify your records with an /OMIT qualifier to request any records that satisfy the condition be omitted from your Sort operation. By default, Sort/Merge includes all the other input records in the output file.
You can specify multiple /OMIT and /INCLUDE qualifiers in your specification file. The order in which you specify them determines the order in which the input records are tested for omission. All the records that have not already been included or omitted after the last /OMIT qualifier are included. You can unconditionally omit any records not previously omitted or included by specifying the /OMIT qualifier only.
Example

/FIELD=(NAME=ZIP,POSITION:20,SIZE:6) /CONDITION=(NAME=LOCATION, TEST=(ZIP EQ "01863")) /OMIT=(CONDITION=LOCATION)

These /CONDITION and /OMIT qualifiers specify that records with the zip code 01863 are to be omitted from your output file.

/PAD=single-character

Specifies the character Sort will use to expand, or "pad," a string when reformatting records or when comparing strings of unequal length. By default, Sort uses the null character for padding, ensuring conformity with the previous versions. Double characters that can be defined as single characters ("ch" > "c") cannot be used as pad characters. Characters, decimal, octal, or hexadecimal digits can be used.
The pad character should be specified as follows:

• Use quotation marks for a character. For example, " # " would specify the number sign.
• Use decimal radix for decimal digits. For example, %D35 would specify the decimal number 35.
• Use octal radix for octal digits. For example, %O043 would specify the octal number 043.
• Use hexadecimal radix for hexadecimal digits. For example, %X23 would specify the hexadecimal number 23.

Example

/PAD="."

This example of a /PAD qualifier specifies that records will be padded with periods.

/PROCESS=type

(Applies to the SORT command only.) Defines the processing method (record, tag, address, or index) for the sorting operation. If you intend to reformat the output records, you cannot use address or index sort. Specify the process type as RECORD, TAG, ADDRESS, or INDEX.
See Section 11.8.1 for a comparison of the four types of process.
Example

/PROCESS=tag

This example of the /PROCESS qualifier specifies that Sort use a tag sorting process.

/[NO]STABLE

Specifies that records with equal keys are directed to the output file in their input file order. The default condition is /NOSTABLE.
By default, when records are sorted with identical keys, the order of those records in the output file may not be the same as they appeared in the input file. Specifying the /STABLE qualifier in a specification file arranges records with equal keys in the output file in the order of the input files as specified in the command line. If you use this qualifier when sorting multiple input files, on output, records with equal keys in the first file will precede those from the second file and so on.
Example

/STABLE

This example of the /STABLE qualifier ensures that records with equal keys will have the same order in the input and output files.

/WORK_FILES=(device[,...])

(Applies to the SORT command only.) Reassigns work files to different disk-structured devices to improve performance. Using the /WORK_FILES qualifier in a specification file makes it unnecessary to assign logicals prior to invoking Sort at the command or program level.
Unlike the DCL qualifier /WORK_FILES=n, the specification file qualifier /WORK_ FILES=(device[,...]) specifies work file assignments, not the number of work files.
See Section 11.8.3 for more information about the use of work files.
Example

/WORK_FILES=("WRKD$:")

This example of a /WORK_FILES qualifier assigns one of Sort's work files to the device WRKD$: because that device has the most space available.