DQSCHEMEAPPLY CALL Routine

Applies a scheme and returns a transformed value and a transformation flag.

Valid in: DATA step 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
Optional Arguments
Details
Example
See Also

Syntax

CALL DQSCHEMEAPPLY('char', 'output-variable', 'scheme', 'scheme-format '
<,mode> <, 'transform-count-variable'> <,'scheme-lookup-method'>
<,match-definition> <,sensitivity> <, 'locale'>);

Required Arguments

char

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

output-variable

the character variable that receives the transformed input value.

scheme

the scheme that is applied to the input value. A SAS format scheme is a filename specification that includes a pathname and the SAS data set name enclosed in quotation marks.

QKB scheme file format scheme includes 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 pathname and the filename that ends in .sch.bfd.
Requirement Lowercase letters.
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 format of the scheme. The valid formats are as follows:

BFD

the QKB scheme file format.

Default BFD

NOBFD

the SAS data format. See Schemes for more information.

Optional Arguments

mode

specifies how the scheme is to be applied to the values of the input character variable. The default value of mode is the mode that is stored in the scheme. If a mode is not stored in the scheme, the default value of mode, is PHRASE.

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.

transform-count-variable

identifies the numeric variable that receives the returned number of transformations that were performed on the input value.

If the input variable is transformed, then the value is a positive integer that represents the number of elements in the input value that are transformed.
Interactions If the value of mode is PHRASE and the input value is not transformed, then the value of the transform-count-variable is 0.
If the input variable is transformed, the value of transform-count-variable is 1.
If the value of the mode is ELEMENT and the input value is not transformed, then the value of the transform-count-variable is 0.
The transformation count might appear to be inaccurate if the transformation value in the scheme is the same as the input value (or any element in the input value).

scheme-lookup-method

specifies one of three mutually exclusive methods of applying the scheme. Valid values for scheme-lookup-method are as follows:

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 two match codes are identical.

Specifying USE_MATCHDEF enables you to modify the values of locale, match-definition, and sensitivity.
Note: The locale, match-definition, and sensitivity values are valid only when the value of the scheme-lookup-method is USE_MATCHDEF.

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.

Interactions If USE_MATCHDEF is specified and match-definition is not specified, the default match definition is stored in the scheme.
The match-definition value is valid only when the value of the scheme-lookup-method is USE_MATCHDEF.
If USE_MATCHDEF is specified and a match-definition is not stored in the scheme, then a value is required for match-definition.

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, two values receive the same match code despite their dissimilarities.

Default 85
Range 50 to 95
Interactions Sensitivity is valid only when the value of the scheme-lookup-method is USE_MATCHDEF.
If sensitivity is not in the scheme and USE_MATCHDEF is specified, the sensitivity value that is stored in the scheme is used.

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.
Note The locale is valid only when the value of the scheme-lookup-method is USE_MATCHDEF.

Details

The DQSCHEMEAPPLY CALL routine transforms an input value by applying a scheme. The scheme can be in SAS format or QKB scheme file format. Schemes that use SAS format can be created with the DQSCHEME procedure. Schemes that use the QKB scheme file format can be created with the DQSCHEME procedure or with DataFlux Data Management Studio software.

Example: DQSCHEMEAPPLY CALL Routine

The following example generates a scheme using QKB scheme file format with the DQSCHEME procedure and then applies that scheme to a data set with the DQSCHEMEAPPLY CALL routine. The example assumes that ENUSA has been loaded into memory as the default locale. 
/* Create the input data set. */
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;
/* Create the scheme. */
proc dqscheme data=suppliers nobfd;
  create matchdef='Organization (Scheme Build)'
    var=company scheme=work.myscheme
    locale='ENUSA';
run;
/* Print the scheme. */
proc print data=work.myscheme;
title 'Organization Scheme';
run;
/* Apply the scheme and display the results. */
data suppliers;
   set suppliers;
   length outCompany $ 50;
   call dqSchemeApply(company, outCompany,'work.myscheme','nobfd',
       'phrase', numTrans);
   put 'Before applying the scheme: ' company /
       'After applying the scheme:  ' outCompany /
       'Transformation count:       ' numTrans /;
run;
The value of the NUMTRANS variable is 0 if the organization name is not transformed. The value is 1 if the organization name is transformed. In the following example, a transformation count of 1 is shown in instances, when no transformation appears to have been made. This is shown in the PROC PRINT output. 
Before applying the scheme: Jackson Data Corp
After applying the scheme: Jackson Data Corp
Transformation count:       1
Instances such as these are not errors. In these cases the transformation value is the same as the input value.

See Also

DQSCHEME Procedure
Copyright © SAS Institute Inc. All Rights Reserved.