Subject: Proposed transvar routine-first cut
Subroutine transvar Document version 1.1 10 Oct 95. WJS
Purpose:
- 1) allow recoding of variable names from names in user data
to their corresponding JGOFS variable names
- 2) verify uniqueness of JGOFS variable names
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
Entries:
transvaropen ([translation_file])
Argument:
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
Purpose:
open translation file
transvarinit ([separator_character_list],
[JGOFS_variable_list],
[include_exclude_switch])
Arguments:
- 1) List of characters which separate data variable
names from JGOFS variable names. Optional-defaults
to blank and tab
Character string-read only
- 2) List of JGOFS variable names. Optional-defaults
to null string.
Character string-read only.
List of names, separated by null characters
- 3) Switch. Optional-defaults to "exclude"
Character string-read only
One of 2 strings. "only" specifies that user
variables after translation, if any, are to be
restricted to the list specified by argument 2.
"exclude" specifies that user variables after
translation, if any, may not be any of the variables
in the list specified by argument 2.
If argument 3 is "exclude", 1) Blank and null
are always excluded as JGOFS variable names &
2) untranslated user variable names, as they are
received by transvar, are added to the list specified
by argument 2.
Function returns:
bit-encoded status (see below)
Integer-32 bits
Possible values:
- 0. Normal.
- Embedded comment found and ignored. Normal.
- System error during read. Fatal.
A missing call to transvaropen will probably
result in one of these
- User variable translated to impermissible
JGOFS variable name. Warning
- 2 or more user variable names translate to
1 JGOFS variable name. Warning
- 1 user variable name appears more than once.
Warning
Purpose:
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)
Arguments:
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
returned.
Purpose:
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)
Argument:
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:
- Status of 0 represents normal completion of this routine.
- If status is non-zero, the most significant bit is used to
distinguish between statuses generated by this program and pass-through
statuses from routines this program calls (eg, system calls)
- 0 - pass-through
- 1 - program-generated
- If the status was generated by this program, the 2 least significant
bits are used to indicate severity. The least significant bit may be used
as a go/no-go flag; the next bit provides more information.
- 0 - success
- 1 - error
- 2 - warning
- 3 - fatal error
- If the error was generated by this program, the remaining 29 bits
are a numeric code representing the status being reported.
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.