TRANS(), XLATE(), RTRANS()

Top  Previous  Next

 

The TRANS() function returns a field or the entire record from a named data file. It is normally only used in dictionary I-type items. The synonym XLATE() may be used.

 

The RTRANS() function is similar but has a slight difference described below for closer compatibility with some other environments.

 

 

Format

 

TRANS({DICT} file.name, record.id, field, action)

RTRANS({DICT} file.name, record.id, field, action)

 

where

 

file.nameevaluates to the name of the file from which data is to be retrieved. The optional DICT prefix specifies that the dictionary portion of the file is to be used. Alternatively, the file.name expression may include the uppercase word DICT before the actual file name and separated from it by a single space.

 

In a QMBasic program, file.name is evaluated in the same way as any other expression. In a dictionary I-type record, file.name may be specified as a quoted string or as the actual name of the file, optionally preceded by the DICT qualifier.

 

record.idevaluates to the id of the record to be retrieved. When used in a QMBasic program, this must be the actual record id. When used in an I-type dictionary expression, this may be

the name of a D or I-type item defined in the same dictionary which contains the id of the record to be retrieved.

a literal record id enclosed in quotes.

 

fieldidentifies the field to be returned. A field value of zero returns the record id and can be used to check the existence of a record. A field value of -1 indicates that the entire record is to be returned. When used in a dictionary I-type expression this can also be

A D or I-type field name as defined in the target file's dictionary.

A field number

@RECORD or -1 to return the entire record.

An expression that evaluates to the field position. This must be enclosed in brackets to avoid potential syntactic ambiguity.

 

actiondetermines the action taken if the record does not exist or the required field is null. This may evaluate to:

 

CReturn the record id.
VPrint a warning message and return a null value.
XReturn a null value (default).

 

The TRANS() function returns the specified data with any mark characters lowered by one level (e.g. value marks become subvalue marks).

 

If record.id is multi-valued, the TRANS() function extracts each requested record and returns a multi-valued result with the data from each record separated by a value mark.

 

The RTRANS() function is identical to TRANS() except that it does not lower the mark characters. This makes it impossible to distinguish between the results of retrieving a multivalued field from a single record and retrieving a single valued field from multiple records.

 

 

Examples

 

TOTAL.VALUE = QTY * TRANS('STOCK', PART.NO, 'PRICE', 'X')

 

The above statement reads from the STOCK file a record (or list of records) whose id(s) can be found in the PART.NO variable. The X error code causes the TRANS() function to return a null value for any record that cannot be found.

 

 

X = TRANS(DICT 'ORDERS', 'DISCOUNT', 'X')

X = TRANS('DICT ORDERS', 'DISCOUNT', 'X')

 

Both of the above statements perform the same action. Either might be used, for example, to retrieve an I-type item named DISCOUNT from the dictionary of the ORDERS file.