DESL

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

( CJ) Details concerning the DESL translate command.

(See example(s) of the use of the translate command.)
[Jump to the list of available options.]
General description of the translate command :

The DESL translate function can be used to convert a data file from one format to another.

All of the DESL functions except the translate function must work with files which are of the SIF form. The structure of SIF files as well as all of the other allowable data file formats which translate can read/write are described here.

The legitimate file formats which translate can read and write are the following :

  1. sif : binary Standard Interface File (one physical record / record, up to 100,000 items per record)
  2. ffsif : Free - Field SIF, blank delimited ASCII file (one/more physical record / record, up to 4096 characters/line, up to 32 characters per numeric string > single precision number)
  3. tsv : Tab-separated variable ASCII file (one physical record / record, up to 4096 characters / record, up to 32 characters per numeric string > single precision number)
  4. csv : Comma-separated variable ASCII file (one physical record / record, up to 4096 characters / record, up to 32 characters per numeric string > single precision number)
  5. bsv : Blank-separated variable ASCII file (one physical record / record, up to 4096 characters / record, up to 32 characters per numeric string > single precision number)

The ASCII file formats mentioned above represent the forms equivalent to a binary SIF file which are suitable for transmittal between dissimilar computers which otherwise would not be able to deal with a foreign binary SIF file directly.

.

(Begin modifications on 021303)

It cannot be stressed enough that the preferred manner in which to transfer (ftp) files between dissimilar platforms is in one of the ASCII formats.

There are instances when a binary SIF file can be transferred to a dissimilar platform. In these cases the two platforms treat binary data the same way.

The table below shows the binary SIF file compatibility between dissimilar plaforms. A "Yes" indicates a binary SIF file transfer can be made from the "FROM" platform to the "TO" platform and DESL will be able to read the transferred file correctly. A "No" indicates a binary SIF file transfer can not be made; DESL will not be able to read the file properly.

        From      
    PC Solaris SGI HP Linux Mac OS-X
  PC   No No No No No
  Solaris No   Yes Yes No Yes
TO SGI No Yes   Yes No Yes
  HP No Yes Yes   No Yes
  Linux No No No No   No
  Mac OS-X No Yes Yes Yes No  

 

(End modifications on 021303)

In general, it is unknown when reading a data file whether a NAME or DATA type record will be read next. DESL has the logic to deal with this situation. (See the discussion of Data files .)

New files which are produced by translate can contain any combination of the following :

  1. shorter records, ie, records containing fewer variables than are contained in records being translated
  2. records with newly-named variables
  3. fewer records than were contained in the files being translated (as a result of conditional record filtering)
The list of currently available options for the translate 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 :

[allfrom] [allto] [altvars] [at] [backward] [cols] [cset] [elsek] [endifk] [eqtol] [files] [format] [from] [ifk] [integer] [mapfile] [names] [newfiles] [newfilex] [noheaders] [nonames] [noop] [pathfile] [paths] [setval] [subtype] [tags] [textfile] [tformat] [tfreq] [to]

[Top][Bottom][Option list]

( CJallfrom) (Command :translate) Details for the allfrom option.

[General syntax rules for this keyword.]

Indicates the default form of the files being translated. The default form is "sif".

[Top][Bottom][Option list]

( CJallto) (Command :translate) Details for the allto option.

[General syntax rules for this keyword.]

Indicates the default form to translate files to. The default form is "ffsif".

[Top][Bottom][Option list]

( CJaltvars) (Command :translate) Details for the altvars option.

[General syntax rules for this keyword.]

Switch for alternate SIF variable name file use

The presence of this option indicates that IF there is an active composite alternate SIF variable name file (as established via the "variables" DESL command) then this composite file will be used to attempt to assign an alternate SIF variable name if a SIF variable would otherwise not be found on the file(s) being processed.

[Top][Bottom][Option list]

( CJat) (Command :translate) Details for the at option.

[General syntax rules for this keyword.]

The "at" option is followed by the variable name which will serve as a parameter, or trigger, upon which to determine the times, during translation "to" "ffsif" files, to write the names and values of a group of up to 20 specified SIF variables. The trigger variable name should be followed by a tolerance value. The default tolerance value is -5, meaning 5 percent. The tolerance value is the maximum amount by which the trigger variable's values can vary from record to record without causing the output of one or more records containing the names and values of a group of up to 20 specified SIF variables. If the tolerance value is specified as a positive number, the magnitude is in the units of the "at" trigger parameter.

If the tolerance value is specified as a negative number, the absolute magnitude of the value is in percent. If the value of the trigger variable, from record to record as each file is read, changes by more than the tolerance value, in trigger parameter units or percent, output records are generated. The names of the up to 20 SIF variables whose names and values are to be printed in the free-field SIF file as comments when triggered by the "at" situation are specified after the "at" tolerance value. After any name a legitimate F, E, or G real format specification can be given. The default format is G12.5.

Example : at run 1 alpha f6.2 cl cd

[Top][Bottom][Option list]

( CJbackward) (Command :translate) Details for the backward option.

[General syntax rules for this keyword.]

Switch for reversed order SIF variable searches

Indicates that any searching for SIF or SIF-type variables will be done from back to front in the SIF or SIF-type records. The default condition is to search from front to back. This option has no effect if "names" is not also given.

[Top][Bottom][Option list]

( CJcols) (Command :translate) Details for the cols option.

[General syntax rules for this keyword.]

If specified, the following value establishes an upper limit of line width, in columns, when translating "to"/"from" a "ffsif" file. The default value is 80. The value specified must lie within the limits of 30 and 4096 columns. For translating "from" a "ffsif" file up to 4096 columns can be interpreted/writ as a "line" of input/output.

Example : cols 110

[Top][Bottom][Option list]

( CJcset) (Command :translate) Details for the cset option.

[General syntax rules for this keyword.]

File-specific conditions for DATA record retention

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]

( CJdformat) (Command :translate) Details for the dformat option.

[General syntax rules for this keyword.]

Normally, the DESL "translate" function determines the actual Fortran format structure which will be used to print the desired variable data. This constructed format string can be overridden entirely by the specification of a string after "dformat". The specified data format string can be up to 128 characters long.

Example : dformat ?(3(2x, g14.7)) ?

[Top][Bottom][Option list]

( CJeqtol) (Command :translate) 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]

( CJfiles) (Command :translate) Details for the files option.

[General syntax rules for this keyword.]

Indicates the list of file(s) to be translated.

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.

.

(Begin modifications on 052102)

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 (?) .

(End modifications on 052102)

Up to 200 files can be explicitly or implicitly specified.

Example : files ffs1 thru ffs4 <eplist eps1 sif1

[Top][Bottom][Option list]

( CJformat) (Command :translate) Details for the format option.

[General syntax rules for this keyword.]

If other than the current default format specification, E14.7, for value printing is desired then a new default format can be set via the "format" option and associated argument. The format must be a real format specification of type E, G, or F. This new default format specification is, however, only valid for the current execution of the "translate" function.

Example : format g12.5

[Top][Bottom][Option list]

( CJinteger) (Command :translate) Details for the integer option.

[General syntax rules for this keyword.]

Toggles the ability to convert from real format without decimal places to an equivalent integer format for variables specified via "names". Following "integer", "on" or "off" must appear. If the "integer" state is "on", it is desired that all values being written into ASCII file forms be displayed as integers if their associated formats had NO decimal places specified. For example, a value which would have been printed in "f6.0" format, if "integer" has been specified, will be printed, effectively, with an "i6" format.

Example : integer on

[Top][Bottom][Option list]

( CJfrom) (Command :translate) Details for the from option.

[General syntax rules for this keyword.]

Indicates, in a 1:1 correspondence with the "files" arguments, the types of files in the specified or implied "files" argument list. Allowable types are "sif", "ffsif", "tsv", "csv" and "bsv" . The "from" file type CANNOT be the same as the specified or implied "to" file type. Up to 200 "from" file types can be specified. Strings beginning with "null" are essentially not reset from the default. The default type of file to translate from is "sif".

Example : from ffsif sif ffsif sif

[Top][Bottom][Option list]

( CJmapfile) (Command :translate) Details for the mapfile option.

[General syntax rules for this keyword.]

Indicates a file to be used for constructing a table for mapping (external) variable names of up to 16 characters to the equivalent (internal) names of up to 8 characters. This option is ONLY applicable when the translation is FROM any ASCII type SIF file equivalent except "ffsif".
.

(Begin modifications on 060808)

This option is ALSO applicable when the translation is TO any ASCII type SIF file equivalent except. "ffsif".

(End modifications on 060808)

Each line in a mapfile should contain comments or two strings. Comment lines begin, as is customary within DESL, with an asterisk and at least one blank. Lines containing two strings are assumed to imply that the first string is the internal label for a variable and the second string is the external label for the corresponding variable. The internal name can be up to 8 characters; DESL uses only binary SIF files that have NAMEs records that contain variable names of 8 or less characters each. The external name can be up to 16 characters.

During the course of translation, a non-empty mapfile table built from this type file is checked to see, for a translation from a valid ASCII file form, if a variable name matches an external name. If so, the name is changed and stored internally to be that of the corresponding internal name. After the use of a mapfile to change incoming variable names, the external names cannot be reestablished as the variable names. As is the norm in DESL, the current state of the namecase system flag will control whether the variable names in the map file are translated to upper case or not. The traditional use of SIF files (binary or ASCII) is that the default case translation is used : always translate to upper case.

.

(Begin modifications on 060808)

When writing a valid non-ffsif ASCII form, a SIF variable (internal name) is compared against the "internal" mapfile table name. If there is a match, the external make of up to 16 characters, verbatim, is written to the ASCII file.

(End modifications on 060808)

Example contents of a map file are the following : 





*
* internal name         external name
*
alt                   altitude_long
alpha                 Angle_of_attack
BETA                  Sideslip_Angle
new_name              old_long_name
*

Example : mapfile map11

[Top][Bottom][Option list]

( CJnames) (Command :translate) Details for the names option.

[General syntax rules for this keyword.]

Indicates the SIF or SIF-type variables to retain from each "record" being translated. Variables can be renamed via the " new name = old name " construct. Each name specified individually (not with "thru") can be followed by a legifimate real format : either E, F or G. Example : G12.5. Having the variables' values included in an ASCII type file in formats expressed within the "names" argument list is only possible when writing the tsv, csv and bsv type files; it is not possible when writing the ffsif type ASCII file. The default format for all names to be written is either E14.7 or a replacement format as specified by the format option. The default condition, ie, if no "names" are specified, is to retain all variables from records being translated. Up to 1000 names can be specified.

Example : names test run f6.0 point mach f5.2 alpha beta

[Top][Bottom][Option list]

( CJnewfiles) (Command :translate) Details for the newfiles option.

[General syntax rules for this keyword.]

Indicates the desired names for new files being produced. There is an understood 1:1 correspondence between files in the "files" list and files in the "newfiles" list. A new file name prefixed with the 4-character string "null" can be used as a place holder in the "newfiles" file names list. This type of name is converted to a blank string before it is used; ie, using a "null" prefixed name is equivalent to having not specified that name at all. By default, all files explicitly named via this "newfiles" list will be flagged as a file "to be RETAINED" at cleanup. (See the "cleanup" command.) The default file name generated for a new file not explicitly named via "newfiles" or "newfilex" begins with a 3-character prefix : "gen" if newfile is SIF, and "ffs" if newfile is "ffsif". This three-character prefix is followed by a unique numeric suffix. Up to 200 new files can be specified.

The list of the names of the new files actually produced can be saved via the use of the ">list"- or ">>list"- type argument, which can appear among the specified new file names. If a ">list"- or ">>list"-type argument is specified, where "list" is the specified file name list, the names of the new files which DESL actually produces during the execution of the current command will be saved in the specified file name list.

This file name list can later be referenced by the "files"/"xfiles" options to imply the file names contained therein. Up to 200 new file names can be saved in any one list. If the ">list" argument is specified the named list will be created if it does not already exist, or will overwrite a like-named list if one exists. If the ">>list" argument is specified the named list will be appended to if it exists or will be created if it does not exist. All file name lists are in existence for the current DESL session only. Each "list" name can be up to 15 characters long.

In all but a few noted cases, it is acceptable to use the ">list" or ">>list"-type argument without specifying a full complement of actual new file names. Any new file produced whose NAME is GENERATED by DESL is ALWAYS marked as a file to "PURGE at cleanup".

A suffix which may be in effect as established via the filesuffix DESL command will be added to any expressed or implied new file name. New 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 new file list is accomplished, up to the maximum number of new 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 new file name. Including more than one such construct will result in unpredictable results.

An example of this type of new 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.

.

(Begin modifications on 052102)

Each new file name, whether it includes the {...} or not can be a maximum of 256 characters long. If a newfile name is more than 16 characters long it must be enclosed in question marks (?).

(End modifications on 052102)

Example : newfiles new10 thru new20 >tlist2

[Top][Bottom][Option list]

( CJnewfilex) (Command :translate) Details for the newfilex option.

[General syntax rules for this keyword.]

This option has exactly the same function as the option "newfiles" except that all new files created via a "newfilex" name are flagged as files to "PURGE at cleanup". (See "newfiles" option. See "cleanup" command.) Up to 200 new files can be specified.

Example : newfilex new10 thru new20

[Top][Bottom][Option list]

( CJnoheaders) (Command :translate) Details for the noheaders option.

[General syntax rules for this keyword.]

If this option is specified all translations TO the "ffsif" file format will result in a new file WITHOUT the leading asterisk-begun comment lines.

[Top][Bottom][Option list]

( CJnonames) (Command :translate) Details for the nonames option.

[General syntax rules for this keyword.]

If this option is specified all translations TO the
.

(Begin modifications on 041403)

"ffsif" or "tsv" or "csv" or "bsv" file formats

(End modifications on 041403)

will result in a new file WITHOUT any variable names which typically appear before the first DATA record.

[Top][Bottom][Option list]

( CJnoop) (Command :translate) 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]

( CJpathfile) (Command :translate) Details for the pathfile option.

[General syntax rules for this keyword.]

List of paths for SIF file searches

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 :

  1. all lines are ASCII
  2. any line beginning with "* " is a comment and is ignored (asterisk + one or more blanks)
  3. blank lines are ignored
  4. 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.
  5. free-field interpretation, therefore embedded blanks require the "?" delimiters
  6. first item is name to be translated; must match VERBATIM with path name specified or implied via "paths" argument list
  7. 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]

( CJpaths) (Command :translate) 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. Path names can be up to 16 characters long. Up to 200 path names can be specified.

Example : paths ..\ ..\Main\ sub1\

[Top][Bottom][Option list]

( CJsetval) (Command :translate) Details for the setval option.

[General syntax rules for this keyword.]

Indicates the substitution value to use for variables which would ordinarily have an associated illegal or out of range value. The default value is -999.
.

(Begin modifications on 021603)

If the translation from an ASCII form encounters an illegal number (NaN, Inf) is translated to the current "setval" value. Conversely, upon writing an ASCII form, any type of illegal number will be written as the current "setval" value.

(End modifications on 021603)

Example : setval 7000

[Top][Bottom][Option list]

( CJsubtype) (Command :translate) Details for the subtype option.

[General syntax rules for this keyword.]

If a translation is being made TO a "ffsif" file and this option is specified followed by the argument "keys", immediately before EACH name and data record printed lines containing "NAME ##" or "DATA ##", respectively, where "##" is the number of elements in each record in the file being written. Also in this situation, the leading asterisk-begun comment lines are omitted.

Example : subtype keys

[Top][Bottom][Option list]

( CJtags) (Command :translate) Details for the tags option.

[General syntax rules for this keyword.]

Indicates the parameters which, if present on the SIF file(s) being translated TO "ffsif", are to be included in comment lines to be inserted ahead of DATA records at the indicated frequency ("tfreq"). Up to 20 tag names can be specified and each can be followed by a "f", "g", or "e" real format specification. If a format specification does follow a name, the respective name will use that format rather than the default format.

Example : tags run alpha

[Top][Bottom][Option list]

( CJtextfile) (Command :translate) Details for the textfile option.

[General syntax rules for this keyword.]

If specified, names a file whose contents will be prefixed to each "ffsif" new file produced.

Example : textfile MacAIRtext

[Top][Bottom][Option list]

( CJtformat) (Command :translate) Details for the tformat option.

[General syntax rules for this keyword.]

Indicates, for translations TO "ffsif", the default format in which to print any "tag" items which could be specified. The default default tag format specification is "g14.7".

Example : tformat f6.2

[Top][Bottom][Option list]

( CJtfreq) (Command :translate) Details for the tfreq option.

[General syntax rules for this keyword.]

If specified, the following value indicates the desired frequency at which to print, in the form of comment lines, any specified "tag" variable names and data IF the translation is TO "ffsif". The default frequency is 1; ie, before each DATA record. A frequency of 3, for example, would only print the tagged variable names and data before every third DATA record.

Example : tfreq 3

[Top][Bottom][Option list]

( CJto) (Command :translate) Details for the to option.

[General syntax rules for this keyword.]

Indicates, in a 1:1 correspondence with the "files" arguments, the types of files in the specified or implied "newfiles/newfil argument list. Allowable types are "sif", "ffsif", "tsv", "csv" and "bsv" . The "to" file type CANNOT be the same as the specified or implied "from" file type. Up to 200 "to" file types can be specified. Strings beginning with "null" are essentially not reset from the default. The default type of file to translate to is "ffsif".

Example : to ffsif sif sif ffsif sif

[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.