RevMedia

The XLATE processor. This is actually a very useful tool for more than just standard extractions of descriptions from code files et al. The full syntax of XLATE is

XLATE(file,rec,field,action,levels.drop)

and it is the variants of field that make this function more powerful than it might at first seem. To deal with the options in turn:

    file    this can be a literal or a variable (but not a file variable).
            It can also be a dict file.

    rec     this is the key of the record that is to be extracted from the
            file.  It can be any valid expression and it can be multivalued.
            If it is multivalued all of the records specified will be read
            and the values returned in a multivalued array.

    field   this can be of four types:
            Number   this just returns the field specified from the record
                     and is the standard use for XLATE.
            Zero     this does not return a field but rather returns the
                     key. This is VERY useful in conjunction with the X
                     action code. If we request a field number in place of a
                     0 we have no way of knowing if the record was on file
                     or not as with an X a "" would be returned if the field
                     was null OR if the record did not exist. With a field
                     number of 0 we can perform a Verifile operation easily.
                     If the record is there the id will be returned, if it
                     is not on file a "" will be returned E.G.

                     IF NOT(XLATE("CODES",@ANS,0,"X")) THEN
                        CALL MSG("Code not found","","","")

            Null ("") this returns the entire record instead of a field. It
                     can be used to save having to open a file for a quick
                     one off utility program or used in conjunction with the
                     levels.drop (q.v.) it can form a quick way of taking
                     entire records to form a multivalued array (e.g. for
                     stuffing a popup etc.). If we set levels.drop to 1, the
                     record will be returned as a multivalued array and thus
                     require no further processing to treat as a multivalue.
                     E.G.

                     POP.LIST=XLATE("LISTS","TEMP","","X",1)
                     IF POP.LIST THEN
                        WRITEV POP.LIST ON POPS,ID,4

            Field Name can be used in place of field number and is more
                     readable although slower. Has the great advantage that
                     it can be used to extract symbolics.

    action  can be X or C.  X means return null if record not found, C means
            return the ID.  Note that omitting X and C will be treated as
            an C.

    levels.drop this tells the system how to treat delimiters found in the
            field/record being XLATED to. This could be useful in the above
            example where we extracted an entire record using a null field
            as it changed the field marks to value marks (and of course any
            value marks to sub-value marks). It is also very useful when
            XLATEing from a multivalued field to a multivalued field.. This
            is best illustrated by reference to a list statement - in this
            example every record on the main file can store multiple parts.
            Every part is available in a number of colours. The symbolic
            Colour.Choice simply extracts the corresponding choices from the
            parts file. Firstly using

               @ANS=XLATE("PARTS",{PNO}, "COL","X")

            we get

            Key.. Parts................    Colour Choice
            1     P123                     Red
                  P200                     Blue
                  P300                     Green
                  P400                     Yellow
                  P563                     Purple
                  P789                     Blue
                                           Red
                                           Green
                                           Lilac
                                           Cyan

            Now using

               @ANS = XLATE("PARTS",{PNO},"COL" ,"X",1)

            we get

            Key..     Parts............    Colour Choice
            1         P123                 Red
                                           Blue
                      P200                 Green
                      P300                 Yellow
                                           Purple
                                           Blue
                      P400                 Red
                      P563                 Green
                      P789                 Lilac
                                           Cyan

            a much more meaningful list because the multivalues in the
            target have been dropped one level to sub-values and the LIST
            processor recognises this.

            Note that under certain circumstances XLATEs can be more
            efficient than straightforward READs as they have their own
            buffers in the FRAME array.