ViGYAN's DESL

( CY) Details concerning the DESL diff command.

(See example(s) of the use of the diff command.)

[Jump to the list of available options.]

General description of the diff command :

The DESL "diff" function allows the user to display, or have written to a file, for two SIF files specified, a report of the named variables from each file whose differences are outside of the specified or implied tolerance bounds.

If a non-aligned ("align" not specified) report is desired then the file with the fewer number of qualifying records will determine the length of the report. There will be one entry in the report per record pair up to the number of records in the file with the fewer number of records. In each instance in which the existing variables exist report entries will be made in which the differences are outside of the tolerance. This type of report should be used when it is known that both of the files being compared have the same number of records.

If an aligned ("align" is specified) report is desired then the variable values whose differences are outside of the tolerance from the two files being compared will be included in the report IF there are corresponding variable values that are equal, as encountered as each file is read sequentially. Since the align variable values need to match for a record to be included in the report and since it is assumed that the align variable values are in an increasing order after the first records are read each file is read, in any alternating order required, in order to find matching values.
.
(Begin modifications on 111603)
It is also assumed that the FIRST file of the pair of files is the one that determines what the "next" value of the align variable is supposed to be. Therefore, missing records will always be, if there are any, from the SECOND file of the pair.
(End modifications on 111603)

The list of currently available options for the diff command is the following.

Any blinking names enclosed in brackets are required or are in a set of options, one of which must be specified. Any non-blinking names enclosed in brackets are optional or are in a set of options, only one of which can be specified.

In cases where the option name is one of a set each different set number is indicated by a red numeric set number superscript trailing the respectiveright bracket :

[align] [backward] [cset] [dnames]¹ [dnameset]¹ [elsek] [endifk] [eqtol] [files] [ifk] [lines] [noop] [output] [pathfile] [paths] [ratio] [tags] [tol]

[Top][Bottom][Option list]

(

CYalign) (Command :diff) Details for the align option.

[General syntax rules for this keyword.]

The presence of this option, followed by two variable variable names, indicates that the user wishes to have the two files being compared used in a manner in which the values for each named alignment variable per file must match exactly for the respective pair of records contribute to the difference report. The default situation is for there to be NO alignment variables. The records from each file are aligned, if possible, in the order in which they exist on the respective files by skipping records forward if necessary.

There is an implicit assumption that both of the files in each pair of files is ALREADY ordered in an INCREASING manner with respect to the values of each of the two alignment variables.

If records in one of the files are skipped in order to to try to attain an alignment then the label *** MISSING RECORDS *** will be included in the diff report.
.
(Begin modifications on 111603)
It is also assumed that the FIRST file of the pair of files is the one that determines what the "next" value of the align variable is supposed to be. Therefore, missing records will always be, if there are any, from the SECOND file of the pair.
(End modifications on 111603)

Example : align point pt

[Top][Bottom][Option list]

(

CYbackward) (Command :diff) Details for the backward option.

[General syntax rules for this keyword.]

Indicates that any searching for SIF variables will be done from back to front in the SIF records. The default condition is to search from front to back. If neither "names" nor "nameset" is specified, "backward" has the effect of reversing the order of printing for the lists of SIF file(s) names.

[Top][Bottom][Option list]

(

CYcset) (Command :diff) Details for the cset option.

[General syntax rules for this keyword.]

This option is used to specify "file-specific" conditions which, IN ADDITION to any other GLOBAL conditions which ALSO may have been specified, are to be applied to each SIF record processed from the respective SIF file. Just like global conditions, file-specific conditions act to limit the applicability of the DESL function being executed by requiring that ALL applicable "and" conditions be TRUE simultaneously or that at least ONE "or" condition be TRUE.

The item immediately following "cset" is the file sequence number in the "files" list for which the following up-to-20 conditions will be applicable.

Each file-specific 3-item condition, like its global 3-item condition counterpart, is made up of (1) a SIF variable name, (2) a 2-character logical conjunction, and (3) a second SIF variable name or a constant.

Example : cset 3 alpha gt phi mach lt 1.2

Here, the user has indicated that, along with whatever other GLOBAL conditions may have been specified, the pertinent DESL function, for the THIRD file specified or implied by the "files" list, will have its application ALSO limited to records which satisfy BOTH of the two conditions :

"ALPHA gt PHI" "MACH lt 1.2".

All file-specific conditions are implicitly joined by an "and" conjunction; ie, by default, all file-specific conditions would have to be true SIMULTANEOUSLY for the applicable record to be retained.

If one or more file-specific conditions following the file sequence number is to be connected to other file-specific conditions for the same file number by an "or" conjunction, then the 2-character item "or" must immediately follow the file number.

Example : cset 2 or alpha lt 0 alpha gt 4

Here, the user has indicated that, along with whatever other GLOBAL conditions may have been specified, the pertinent DESL function, for the SECOND file specified or implied by the "files" list, will have its application ALSO limited to records in which the value of the SIF variable "alpha" satisfies at least ONE of the conditions :

"ALPHA lt 0" "ALPHA gt 4".

Additionally, if the file number following the "cset" option is negative, the absolute value of this negative file number is used for the actual file number and the associated "and" or "or" condition(s) are NOT used in the traditional sense of filtering the records read but are ONLY used to indicate when READING of the associated file is to STOP. This ability is useful in preventing the reading of a long file when it is known that the data required is relatively near the beginning of the file.

Example : cset -1 or run eq 3 alpha gt 24

Here, the user has indicated that when a record is encountered for which either or both of the two conditions

"RUN = 3" "ALPHA gt 24"

is/are TRUE, reading of the current SIF file should end.

[Top][Bottom][Option list]

( CYeqtol) (Command :diff) Details for the eqtol option.
[General syntax rules for this keyword.]
Indicates the tolerance to be applied to any global or file-specific "eq" condition(s) which may have been specified. If the tolerance value specified is positive the value is in the units of the variable being used in the respective condition(s). If the tolerance value is negative the absolute value of the value is a PERCENT difference. The default value of tolerance is 0.
Example : eqtol .5
[Top][Bottom][Option list]

( CYfiles) (Command :diff) Details for the files option.
[General syntax rules for this keyword.]
Indicates the names of the TWO SIF file(s) to analyze. The differences between the specified variables from each files'records that lie outside of the default or specified tolerences will be reported.

This list of files can be implicitly extended via use of the <list argument which can appear among the specified file names. If one or more of the <list-type arguments are specified, where "list" is a currently defined file name list, the file names contained in the indicated file name list(s) will be included, at their respective point(s) of encounter, in the current file list. The referenced list(s) must have been produced by the "newfiles" and/or "newfilex" argument lists associated with one or more previously executed DESL commands. Each "list" name can be up to 15 characters long. File names can also include the {...} construct. This type specification within a file name implies that the list name given between the curly brackets ( {} ), is to be used to have each of its elements substituted in turn for the { ... }, inclusively, such that an implicit lengthening of the file list is accomplished, up to the maximum number of files allowed. Any time such a {...} usage occurs, all lists mentioned must exist; i.e., must have been previously defined in the current DESL session. Only one {...} construct can be included in a file name. Including more than one such construct will result in unpredictable results.
An example of this type of file name specification is the following :
t43r{runs}.sif
Here, the list "runs" will have its elements used, in turn, in place of the {runs} substring.
Each file name, whether it includes the {...} or not, can be a maximum of 256 characters long. If a file name is more than 16 characters long it must be enclosed in question marks (?) .
Two files must be explicitly or implicitly specified.
Example : files run16 [Top][Bottom][Option list]

( CYlines) (Command :diff) Details for the lines option.
[General syntax rules for this keyword.]
If other than the current default number of lines which can be contained in one "page" of the output report is desired, then this default can be overridden for the current execution of the "diff" function by including the desired number of lines after the "lines" option.
Example : lines 44
[Top][Bottom][Option list]

( CYdnames) (Command :diff) Details for the dnames option.
[General syntax rules for this keyword.]
Indicates the SIF variables, singularly (implying the second file's variable = the first file's) or in pairs, from each of the two named files, whose values to use as a basis of a comparison. Either "dnames" or "dnameset" must be specified. Up to 5000 names can be specified in pairs. A tolerance value may follow a (pair of) name(s). If so included in the argument list, this value will override the default tolerance in effect for the applicable variable.
Example : dnames alpha alphax beta beta -.01
[Top][Bottom][Option list]

( CYdnameset) (Command :diff) Details for the dnameset option.
[General syntax rules for this keyword.]
Indicates the SIF variables, from the specified file sequence number (1 or 2), whose values to use as a basis of a comparison. Either "dnames" or "dnameset" must be specified. Up to 5000 names names can be specified for a file. A tolerance value may follow each name. If so included in the argument list, this value will override the default tolerance in effect for the applicable variable. The first tolerance value specified resets the default tolerance value for the respective variable name.
Example : dnameset 2 alpha beta -.01
[Top][Bottom][Option list]

( CYnoop) (Command :diff) Details for the noop option.
[General syntax rules for this keyword.]
A dummy option which allows one or more GLOBAL conditions to follow. This option has NO OTHER FUNCTION.
[Top][Bottom][Option list]

( CYoutput) (Command :diff) Details for the output option.
[General syntax rules for this keyword.]
By default, the standard output device will be the recipient of the report issued by the "diff" function. If an alternate file is named via the "output" option all report type output will, instead, be written to the named file. If the named file already exists, the current system "overstore" state governs whether the output file can overstore the existing file. If NO overstore is allowed output will revert back to the standard device.
Example : output out1
[Top][Bottom][Option list]

( CYpathfile) (Command :diff) Details for the pathfile option.
[General syntax rules for this keyword.]
If specified, any up-to-16-charact string specified via the "paths" option and argument list can be translated to an up-to-64-charact string. If a specified "paths" string matches a string in the left column in the path file, then the (potentially longer) string in the right column in the same line in the path file is substituted for the original string. The rules for the syntax of a path file are the following :

all lines are ASCII
any line beginning with "* " is a comment and is ignored (asterisk + one or more blanks)
blank lines are ignored
only 2 items per line per translation : the first up to 16 characters and the second up to 64 characters. Any string longer than 16 characters MUST be enclosed in question-mark (?) delimiters.
free-field interpretation, therefore embedded blanks require the "?" delimiters
first item is name to be translated; must match VERBATIM with path name specified or implied via "paths" argument list
second item is the corresponding path name translation

An example of such a file is the following :

* * Example path file for test xxx * * item 1 = path to be translated : MUST * match VERBATIM with name given * specified/implied via "paths" * * item 2 = resulting name translation * data56 ? \usr\home2\ people\test56\ ? up ?..\? way-up ? ..\..\..\ Temp46\?

Example : pathfile pathA
[Top][Bottom][Option list]

( CYpaths) (Command :diff) Details for the paths option.
[General syntax rules for this keyword.]
Indicates, in a 1:1 correspondence with the list of files specified, directory locations for the specified files. These locations supersede the current directory. If a file location thus specified is not empty ("null...") a search for the respective file will be made at the indicated location before a search is made at any other alternate locations which have been made effective via a previous execution of the "path" command. By default, all path names are blank. Up to 200 path names can be specified.
Example : paths ..\ ..\Main\ sub1\
.
(Begin modifications on 082606)

[Top][Bottom][Option list]

( CYratio) (Command :diff) Details for the ratio option.
[General syntax rules for this keyword.]
Indicates that instead of the absolute difference of the respective values from the two files being compared to the "tol" a ratio of the file #1 value over the file #2 value is compared to the "tol" value. In the case of a ratio being used the "tol" option indicates the absolute of the difference from 1.0 that is allowable before the comparison situation is seen as a violation and is added to the diff report. Regardless of the sign of the "tol" value its absolute value is used and no "percent" type comparison is made.
(End modifications on 082606)

[Top][Bottom][Option list]

( CYtags) (Command :diff) Details for the tags option.
[General syntax rules for this keyword.]
Indicates the variable names, in pairs, which, if present on the SIF files being processed, will have their values displayed ahead of each new SIF record's report entries.
Example : tags run run point pt
[Top][Bottom][Option list]

( CYtol) (Command :diff) Details for the tol option.
[General syntax rules for this keyword.]
The item following this option is the default tolerance value. Sets the tolerance to be used as a basis of comparison between the two files' respective variable pairs. If the specified tolerance value is negative, it is assumed to be a tolerance in percent, and the tolerance percent value is the absolute magnitude of the number specified. The default tolerance is 0.
Example : tol .5
[Top][Bottom][Option list]

DESL Home | Website Outline | Commands | Examples | Download | Contacts

ViGYAN, Inc.
DESL Manager at ViGYAN, Inc.

30 Research Drive
Hampton, VA 23666
Voice: (757) 865-1400
Toll Free: (800) 288-3998
FAX: (757) 865-8177

© 1998 ViGYAN, Inc.