Click above to get retro games delivered to your door ever month!

N_XVARSTRU()
Define variant definition for current Btrieve file

Syntax
N_XVARSTRU('*', <cStructure>|<aStructure>)

Arguments
Refer to N_XUSE for definitions of <cStructure> and <aStructure>.

Remarks
Several vertical market applications have multiple definitions for some 
files.  The total record length is the same, however, the fields within the 
records may be specified differently.  For example, in one definition there 
may be a field ZIP (C9), while in a variant definition, it may be defined as 
two fields: ZIP5 (C5) and ZIP4 (C4).  

N_XVARSTRU allows you to specify a variant structure for the currently open 
file by specifying "*" as in place of <cTable>.  This is acceptable even if 
the file has been opened with USE VIA in the RDD.  File position, index 
order, filters, etc., are unchanged.

The variant definition should result in the same internal length 
(N_XSRECSIZ) as the primary record  definition or errors may result.  If 
necessary, pad the the variant definition with "filler" fields to bring the 
record to the required length.

We recommend that you restore the primary definition once you are done with 
the variant.

While a variant definition is active, fields in the original definition are 
undefined (unless they also appear in the variant).  In the Example below: 
referring to field ZIP9 while the variant definition is in effect will 
result in an error message.  Be aware that you can unintentionally refer to 
a non-existant field if it is part of a SET FILTER or SET RELATION.  In the 
Example below 
     SET FILTER TO ZIP5 = '10021'
is invalid while the variant definition is active.  Thus, we recommend 
deactivating any filters or relations associated with the record before 
switching to the variant definition, unless you know that the filters and 
relations will still be valid.

Note
If you are specifying a long structure in-line (i.e., not loading it from an 
RQB or some other file) then specifying the structure as entries in an array 
will cause much less memory fragmentation than specifying it as a series of 
concatenated strings.  If applicable, RELEASE the array memory variable 
after N_XVARSTRU.

Example
* example of use of a variant definition
cPrimary = 'Zip                 C     9.0  ;'
cVariant = 'Zip5                C     5.0  ;' +;
           'Zip4                C     4.0  ;'
* open file with primary structure
USE ZipTable VIA "RQBRDD" DEFINITION cPrimary
   - or -
N_XUSE("ZipTable.DTA",cPrimary)
* switch to variant structure
N_XVARSTRU("*",cVariant)
* switch back to primary
N_XVARSTRU("*",cPrimary)