transvar routine

transvar routine

Date: 10 Oct 95 20:32:00 EDT
Subject: Proposed transvar routine-first cut

Subroutine transvar Document version 1.1 10 Oct 95. WJS


Normal usage:

1 call to transvaropen, followed by 1 call to transvarinit, followed by arbitrary number of calls to transvar and/or transvarcomment (may be mixed). Optionally followed by 1 call to transvarclose


transvaropen ([translation_file])


name of translation file. Optional-defaults to no translation file (transvar used only to check uniqueness). Character string-read only

Function returns:

system code of attempted file open if argument present; 0 else. Integer


open translation file transvarinit ([separator_character_list], [JGOFS_variable_list], [include_exclude_switch])


Function returns:

bit-encoded status (see below) Integer-32 bits

Possible values:

  1. 0. Normal.
  2. Embedded comment found and ignored. Normal.
  3. System error during read. Fatal. A missing call to transvaropen will probably result in one of these
  4. User variable translated to impermissible JGOFS variable name. Warning
  5. 2 or more user variable names translate to 1 JGOFS variable name. Warning
  6. 1 user variable name appears more than once. Warning


Initializes translation table and impermissible JGOFS variable lists to null strings. If translation file in use, reads entire all of it, saving header comments and creating translation table. Analyzes translation table and reports result to calling program. Closes translation file. See translation file format for details. If no translation file, returns.

	transvar (data_variable_name,buffer_for_JGOFS_variable_name)
			1) Name of variable to translate
			   Character string-read only
			2) User buffer to contain translated name
			   Character string-write
		Function returns: bit-encoded status
			Integer-32 bits
				Possible values:
			1) 0. Normal. Translated variable returned 
			2) Argument 1 not found in translation table. Normal.
			   Null string returned.
			3) Argument 1 translated to impermissible JGOFS
			   variable name. Error.  Impermissible name returned
			4) Argument 1 translated to 2 or more different JGOFS 
			   variable names.  Error.  1 of the JGOFS names
			Translate variable names according to table.
			Untranslated user variable names are added to the list
			of impermissible JGOFS variable names so that reuse
			will be flagged
	transvarcomment (Buffer_for_comment_string)
			User buffer to contain next comment line. 
			Character string-write
		Function returns: bit-encoded status
			1) 0. Normal. Next comment line returned, without
			   initial #, with trailing newline
			2) EOF. Normal. Null string returned
			3) User buffer overflow.  Error. Truncated comment
			   string returned, with trailing newline.
		Purpose: return next comment line from beginning of file
	transvarclose ()
		No arguments
		Function returns: 0
		Purpose: Close translation file.  A file close will be done,
			but status will be ignored.

Bit encoded status:

Format of translation file:

Lines are either comment lines beginning with a #, or data lines.

Comment lines:

Although comment lines can appear anywhere, only comment lines preceding the first non-comment line are available to the JGOFS system. Individual comment lines are limited to 80 characters each. The initial # and the newline separator do not count against the 80 character limit. The total number of comment characters available to the JGOFS system is 2400; any others will be ignored.

Data lines:

Data lines consist of variable names found in the user data (option- ally preceded by blanks or tabs), followed by one or more separator characters (blanks or tabs), followed by the name of the JGOFS variable that this partic- ular user variable represents.

User variable names:

Not every user variable name in a dataset needs to appear in the file. Similarly, not every user variable name in the file needs to correspond to a variable name in a particular user dataset.

A particular user variable name should not appear more than once in the file. Depending on the application, an error will result or only the first occurrence will be used.

The total length of the user variable names in the file is limited to 5000 characters.

JGOFS variable names:

It is simplest if each JGOFS variable name appears only once in the file. If it appears more than once, then only one of the user variable names that translate to it may appear in a particular dataset.

The total length of the user variable names in the file is limited to 5000 characters.