Defining a substring

Use the &SUBSTR built-in function to request that a CLIST use only certain bytes of an indicated string when performing substitution. You indicate the starting and ending positions of the string from which the substitution is made.

For example, assuming a variable called &ANIMALS contains the character string "DOGSCATSSEALS", to set a variable called &FELINE to the character string "CATS", code the following:

SET FELINE = &SUBSTR(5:8,&ANIMALS)

Note that the character string "CATS" begins in the fifth position of &ANIMALS and ends in the eighth position.

A &SUBSTR built-in function can contain other built-in functions. Assume your CLIST receives input from the user and assigns it to a variable called &NAME. &NAME contains a person's first and middle initial followed immediately by the family name. To add a blank between the initials and the family name, you can set a variable called &NFIELD to a character string consisting of the following:

The first and middle initials
A blank
The family name.

SET NFIELD = &STR(&SUBSTR(1:2,&NAME) &SUBSTR(3:&LENGTH(&NAME)+ 
             ,&NAME))

If you want the substring to contain only one character, you can omit the colon and end-expression. For example, if you are interested only in the first letter of the family name, code the following:

SET FLTRLNAME = &SUBSTR(3,&NAME)

You can substitute variables for starting and ending expressions. For instance, to set the section of &STRING beginning at the second position and ending at the eighth position to a variable called &WIDGET, you can create a variable and substitute it in the SET statement. Assume that the substring data represents a part number.

SET PART# = &STR(2:8,)
SET WIDGET = &SUBSTR(&PART#&STRING)

When a variable is named in &SUBSTR, arithmetic evaluation of the variable's contents is suppressed, as in &STR. For example:

SET DIMENSNS = &STR(2*4)
SET X = &SUBSTR(1:2,&DIMENSNS)        /result: X = 2*

However, when another built-in function such as &LENGTH is specified in the &SUBSTR, the variable within the built-in function is evaluated before the &SUBSTR. To protect that variable from arithmetic evaluation, use &STR.

SET DIMENSNS = &STR(2*4)
SET X = &SUBSTR(1:&LENGTH(&STR(&DIMENSNS)),&DIMENSNS)
/* result: X = 2*4

If a string contains data of the double-byte character set (DBCS), &SUBSTR counts each DBCS character as two bytes, and counts each DBCS delimiter as one byte. For example, using d1d2 to denote two DBCS characters and using < and > to denote the DBCS delimiters X'0E' (shift-out) and X'0F' (shift-in):

SET X = &SUBSTR(8:9(A<d1d2>BC)       /* result:  X = BC

When &SUBSTR returns DBCS data, &SUBSTR encloses the data between the DBCS delimiters X'0E' and X'0F'. &SUBSTR attempts to return the exact bytes requested. However, when the starting or ending positions of the substring are DBCS data or DBCS delimiters, &SUBSTR makes the following adjustments:

If the substring:	&SUBSTR does the following:
Starts on the first byte of a DBCS character	Replaces that byte with a single-byte blank and the right-next byte with a shift-out delimiter
Starts on the second byte of a DBCS character	Replaces that byte with a shift-out delimiter
Starts on a shift-in delimiter	Replaces that byte with a single-byte blank
Ends on shift-out delimiter	Replaces that byte with a single-byte blank
Ends on the first byte of a DBCS character	Replaces that byte with a shift-in delimiter
Ends on the second byte of a DBCS character	Replaces that byte with a single-byte blank and the left-next byte by a shift-in delimiter.

In addition, if the adjustment causes a not valid DBCS character, or a contiguous pair of DBCS delimiters, &SUBSTR replaces those by single-byte blanks. However, SUBSTR does not change any contiguous pairs of DBCS delimiters that were part of the original data string.

The following are several examples of the adjustment process. In the examples, the characters s, Dn, <, >, and b denote a single-byte character, double-byte character, shift-out delimiter, shift-in delimiter, and single-byte blank.

&SUBSTR(4:10,ss<D1D2D3D4>)    /* result:    b<D2D3>

&SUBSTR(5:11,ss<D1D2D3D4>)    /* result:    <D2D3>b

&SUBSTR(6:10,ss<D1><D3D4>)    /* result:    b<D3>

&SUBSTR(1:3,ss<D1D2D3D4>)     /* result:    ssb

&SUBSTR(3:5,ss<D1D2D3D4>)     /* result:    bbb

Because &SUBSTR may truncate data in DBCS strings, you can use &SYSCSUBSTR as an alternative to &SUBSTR for DBCS data.