4.111 sddsxref

• description: sddsxref creates a new data set by adding selected rows from one data set to another. Rows are selected by matching string or numeric values in a column present in both input data sets. Users may specify which columns of the second data set to take or leave and may transfer parameter and array data. sddsmxref is a variant that permits multiple -match and -equate options.
• examples:
  sddsxref input.sdds xRef.sdds output.sdds -match=Name -take=Value  
  sddsxref data.sdds xRef.sdds -equate=Index -reuse=rows -fillIn  
      

• synopsis:
  sddsxref [-pipe[=input][,output]] [input] [xRefFile] [output]  
           [-equate=columnName | -match=columnName]  
           [-reuse[=rows][,page]] [-fillIn]  
           [-take=columnName,...] [-leave=columnName,...]  
           [-transfer={parameter | array},name[,name...]]  
           [-ifis={column | parameter | array},name[,name...]]  
           [-ifnot={column | parameter | array},name[,name...]]  
      

• files: input is the data set to which data is being added. xRefFile is the data set from which data is taken. Warning: if output is not given and if -pipe=out is not specified, input is overwritten. For pipe input, the first file listed is taken to be xRefFile. For pipe input and output, the only file listed is xRefFile.
• switches:
  • -equate=columnName, -match=columnName — These options specify the name of a column that exists in both input and xRefFile. For match the column must contain string data, while for equate the column must contain numeric data. For each row in input, sddsxref searches xRefFile to find the first row for which the match column is identical or the equate column is equal, as appropriate. If neither option is given, rows are taken sequentially from xRefFile for each row of input.
  • -reuse[=rows][,page] — By default, each row from xRefFile is matched to one row in input. If -reuse=rows is given, each row from xRefFile may be matched to any number of rows in input. Also by default, each page of input is matched with the corresponding page of xRefFile. If -reuse=page is given, each page of input is matched anew to the first page of xRefFile. The two qualifiers may be given together.
  • -fillIn — Normally if there is no match in xRefFile for a row in input, that row will not appear in output. If -fillIn is given, the row will appear, but the values for the columns that are being transferred from xRefFile will be filled with zeros and empty strings, as appropriate.
  • -take=columnName,..., -leave=columnName,... — These options specify which columns of xRefFile to extract from a matching or equal row for addition to a row of input. Wildcards may be given in the column names. By default, all columns not in input are taken. If take is employed, only the named columns will be taken. In either case, no column specified under leave will be taken. -leave=* causes no columns to be taken.
  • -transfer={parameter | array},name[,name...] — This option, which may be given multiple times, specifies the names of parameters and arrays to be transferred. Wildcards are not presently supported in this option.
  • -ifis={column | parameter | array},name[,name...], -ifnot={column | parameter | array},name[,name...] — These options allow conditional execution. If any column named under ifis is not present, execution aborts. If any column named under ifnot is present, execution aborts.
• see also:
  • Data for Examples
  • sddsselect()
  • sddsmxref()
• author: M. Borland, L. Emery, H. Shang, R. Soliday ANL/APS.