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.nameis the name of the file from which data is to be retrieved. The allowable forms of the file.name differ between use in a dictionary I-type or use in a QMBasic program:

In a QMBasic program, file.name is evaluated in the same way as any other expression.

In a dictionary I-type record, the file.name may be specified with or without quotes. If file.name is an expression that evaluates to the file name, it must be enclosed in parentheses.

In all usage, if the evaluated file name commences with DICT (case insensitive) separated from the actual name by a single space, the dictionary of the named file is used.

 

 

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.

 

fieldan expression that evaluates to the field number of 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 data item (A/C/D/E/I/S-type) defined in the target file's dictionary. If the field name does not follow the rules for construction of QMBasic variable names, it must be quoted. This form is not valid when the file.name is an expression.

A field number

@RECORD or -1 to return the entire record.

If field is given as expression that evaluates to the field position, this must be enclosed in brackets to avoid potential syntactic ambiguity.

 

actiondetermines the action taken if the file cannot be opened, 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).

In addition,

BCauses the file to be opened in binary mode with mark mapping suppressed (directory files only).

 

 

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 multivalued, the TRANS() function extracts each requested record and returns a multivalued 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 used in a dictionary I-type record 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. When using TRANS() in a QMBasic program, the field argument must be an expression that evaluates to the field number. For example:

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

 

 

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

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

 

Both of the above statements perform the same action. Either might be used, for example, to retrieve a record named DISCOUNT from the dictionary of the ORDERS file.