DQSCHEMEAPPLY Function

Applies a scheme and returns a transformed value.

Valid in: DATA step, PROC SQL, and SCL
Requirements: If specified, the locale must be loaded into memory as part of the locale list.
Schemes using SAS format are required in the z/OS operating environment.

Syntax

Required Arguments

char

specifies a character constant, variable, or expression that contains the value to which the specified scheme is applied.

scheme

identifies the scheme that is applied to the input value. For schemes using SAS format, the scheme argument includes both the path and the filename of the SAS data set, in quotation marks.

For schemes using QKB scheme file format, the scheme argument is the name of an existing fileref in quotation marks. For all operating environments other than z/OS, the fileref must reference a file specification that includes both the path and the filename that ends in .sch.bfd.
Requirement Lowercase letters are required.
Note In the z/OS operating environment, the normal naming conventions apply for the partitioned data set (PDS) that contains the scheme.

scheme-format

identifies the file format of the scheme. Valid values are as follows:

BFD

indicates that the scheme is stored in QKB scheme file format. This is the default value.

NOBFD

indicates that the scheme is stored in SAS format.

See Applying Schemes

Optional Arguments

mode

specifies how the scheme is to be applied to the values of the input character variable.

If the value of scheme-lookup-method is USE_MATCHDEF, and a value is not specified for mode, the default value of mode (PHRASE) is used.
Valid values for mode are as follows:

PHRASE

compares the entire input character value to the entire length of each of the DATA values in the scheme. When the value of the scheme-lookup-method is USE_MATCHDEF, the match code values of the entire input value are compared to the match codes of DATA values in the scheme. A transformation occurs when a match is found between an element in the input value and a DATA value in the scheme.

ELEMENT

compares each element in the input character value to each of the DATA values in the scheme. When the value of the scheme-lookup-method is USE_MATCHDEF, the match code of the entire input value is compared to the match codes of the scheme's DATA values. A transformation occurs when a match is found between an element in the input value and a DATA value in the scheme.

Default The mode that is stored in the scheme. If a mode is not stored in the scheme, the default value of PHRASE is used.

scheme-lookup-method

specifies one of three mutually exclusive methods of applying the scheme.

EXACT

(default value) specifies that the input value is to be compared to the DATA values in the scheme without changing the input value in any way. The transformation value in the scheme is written into the output data set only when the input value exactly matches a DATA value in the scheme. Any adjacent blank spaces in the input value are replaced with single blank spaces before comparison.

IGNORE_CASE

specifies that capitalization is to be ignored when the input value is compared to the DATA values in the scheme. Any adjacent blank spaces in the input value are replaced with single blank spaces before comparison.

USE_MATCHDEF

specifies that the match code of the input value is to be compared to the match code of the DATA values in the scheme. A transformation occurs when the match codes are identical.

Specify USE_MATCHDEF to enable locale, match-definition, and sensitivity.
Default EXACT
Restriction The arguments locale, match-definition, and sensitivity are valid only when the value of scheme-lookup-method is USE_MATCHDEF.
See Applying Schemes

match-definition

the name of the match definition. The definition must exist in the locale that is used to create match codes during the application of the scheme. If USE_MATCHDEF is specified and a match definition is not stored in the scheme, then a value is required for the match-definition argument.

Default If USE_MATCHDEF is specified and the match-definition argument is not specified, then the default match definition is the one that is stored in the scheme.
Restriction The match-definition argument is valid only when the value of the scheme-lookup-method argument is USE_MATCHDEF.
See Meta Options

sensitivity

specifies the amount of information in the match codes that are created during the application of the scheme. With higher sensitivity values, two values must be increasingly similar to create the same match code. At lower sensitivity values, values can receive the same match code despite their dissimilarities.

Default When use_matchdef is specified and the sensitivity argument is not specified, the default sensitivity is the sensitivity value that is stored in the scheme. When USE_MATCHDEF is specified and a sensitivity value is not stored in the scheme, the default sensitivity value is 85.
Range 50 to 95
Restriction The sensitivity argument is valid only when the value of the scheme-lookup-method argument is USE_MATCHDEF.
Note To return a count of the number of transformations that take place during a scheme application, use the DQSCHEMEAPPLY CALL routine.
See Meta Options

locale

specifies a character constant, variable, or expression that contains the locale name.

Default The default locale is the first locale in the locale list. If no value is specified, the default locale is used.

Details

The locale argument is valid only when the value of the scheme-lookup-method argument is USE_MATCHDEF. The DQSCHEMEAPPLY function transforms an input value by applying a scheme. The scheme can be in SAS format or QKB scheme file format. SAS format schemes can be created with the DQSCHEME procedure. Create schemes using the QKB scheme file format with the DQSCHEME procedure or with DataFlux Data Management Studio software.

Example: DQSCHEMEAPPLY Function

The following example generates a scheme with the DQSCHEME procedure and then applies that scheme to a data set with the DQSCHEME function. The example assumes that the ENUSA locale has been loaded into memory as part of the locale list.
/* Create the input data set. */P
data suppliers;
   length company $ 50;
   input company $char50.;
datalines;
Ford Motor Company
Walmart Inc.
Federal Reserve Bank
Walmart
Ernest & Young
TRW INC - Space Defense
Wal-Mart Corp.
The Jackson Data Corp.
Ernest & Young
Federal Reserve Bank 12th District
Ernest and Young
Jackson Data Corp.
Farmers Insurance Group
Kaiser Permantente
Ernest and Young LLP
TRW Space & Defense
Ford Motor
Jackson Data Corp
Federal Reserve Bank
Target
;
run;

/* Assign a fileref to the scheme file. */
filename myscheme 'c:\temp\company.sch.bfd';

/* Create the scheme. */
proc dqscheme data=suppliers bfd;
  create matchdef='Organization (Scheme Build)'
    var=company scheme=myscheme
    locale='ENUSA';
run;

/* Apply the scheme and display the results. */
data suppliers;
   set suppliers;
   length outCompany $ 50;
   outCompany=dqSchemeApply(company,'myscheme','bfd','phrase','EXACT');
   put 'Before applying the scheme: ' company /
       'After applying the scheme:  ' outCompany;
run;