%SUBSTRING built-in function

The substring built-in function (%SUBSTRING or %SST) produces a character string that is a subset of an existing character string. This function can only be used within a CL program or procedure.

In a Change Variable (CHGVAR) command, the %SST function can be specified in place of the variable (VAR parameter) to be changed or the value (VALUE parameter) to which the variable is to be changed. In an If (IF) command, the %SST function can be specified in the expression.

The format of the substring built-in function is shown in this example:

%SUBSTRING(character-variable-name starting-position length)

It can also be formatted as shown in this example:

%SST(character-variable-name starting-position length)

You can code *LDA in place of the character variable name to indicate that the substring function is performed on the contents of the local data area.

The substring function produces a substring from the contents of the specified CL character variable or the local data area. The substring begins at the specified starting position (which can be a variable name) and continues for the length specified (which can also be a variable name). Neither the starting position nor the length can be 0 or negative. If the sum of the starting position and the length of the substring are greater than the length of the entire variable or the local data area, an error occurs. The length of the local data area is 1024.

The following examples are about the substring built-in function:

If the first two positions in the character variable &NAME are IN, the program INV210 is called. The entire value of &NAME is passed to INV210 and the value of &ERRCODE is unchanged. Otherwise, the value of &ERRCODE is set to 99.
```
DCL &NAME *CHAR VALUE(INVOICE)
DCL &ERRCODE *DEC (2 0)
IF (%SST(&NAME 1 2) *EQ 'IN') +
THEN(CALL INV210 &NAME)
ELSE CHGVAR &ERRCODE 99
```

If the first two positions of &A match the first two positions of &B, the program CUS210 is called.

DCL &A *CHAR VALUE(ABC)
DCL &B *CHAR VALUE(DEF)
IF (%SST(&A 1 2) *EQ %SUBSTRING(&B 1 2)) +
CALL CUS210

Position and length can also be variables. This example changes the value of &X beginning at position &Y for the length &Z to 123.
```
CHGVAR %SST(&X &Y &Z) '123'
```
If &A is ABCDEFG before this CHGVAR command is run, &A is
```
CHGVAR %SST(&A 2 3) '123'
```
A123EFG after the command runs.
In this example, the length of the substring, 5, exceeds the length of the operand YES to which it is compared. The operand is padded with blanks so that the comparison is between YESNO and YESbb (where b is a blank). The condition is false.
```
DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO)
.
.
.
IF (%SST (&NAME 1 5) *EQ YES) +
  THEN(CALL PROGA)
```
If the length of the substring is shorter than the operand, the substring is padded with blanks for the comparison. For example:
```
DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO)
.
.
.
IF (%SST(&NAME 1 3 ) *EQ YESNO) THEN(CALL PROG)
```
This condition is false because YESbb (where bb is two blanks) does not equal YESNO.
The value of the variable &A is placed into positions 1 through 10 of the local data area.
```
CHGVAR %SST(*LDA 1 10) &A
```
If the concatenation of positions 1 through 3 of the local data area plus the constant 'XYZ' is equal to variable &A, then PROCA is called. For example, if positions 1 through 3 of the local data area contain 'ABC' and variable &A has a value of ABCXYZ, the test is true and PROCA is called.
```
IF (((%SST*LDA 1 3) *CAT 'XYZ') *EQ &A) THEN(CALLPRC PROCA)
```

This procedure scans the character variable &NUMBER and changes any leading zeros to blanks. This can be used for simple editing of a field before displaying in a message.

      DCL &NUMBER *CHAR LEN(5)
      DCL &X *DEC LEN(3 0) VALUE(1)
      .
      .
LOOP:IF (%SST(&NUMBER &X 1) *EQ '0') DO
      CHGVAR (%SST(&NUMBER &X 1)) ' '  /* Blank out */
      CHGVAR &X (&X + 1)  /* Increment */
      IF (&X *NE 4) GOTO LOOP
      ENDDO

The following procedure uses the substring built-in function to find the first sentence in a 50-character field &INPUT and to place any remaining text in a field &REMAINDER. It assumes that a sentence must have at least 2 characters, and no embedded periods.

Note: By using the code example, you agree to the terms of the Code license and disclaimer information.

        PGM (&INPUT &REMAINDER)   /*  SEARCH  */
        DCL &INPUT     *CHAR LEN(50)
        DCL &REMAINDER *CHAR LEN(50)
        DCL &X *INT  /* INDEX            */
        DCL &L *INT  /* REMAINING LENGTH */

        DOFORL:
        DOFOR &X 3 50
          IF (%SST(&INPUT &X 1) *EQ '.') THEN(DO)
             CHGVAR &L (50-&X)
             CHGVAR &X (&X+1)
             CHGVAR &REMAINDER %SST(&INPUT &X &L)
             LEAVE
             ENDDO
        ENDDO
ENDPGM

The procedure starts by checking the third position for a period. Note that the substring function checks &INPUT from position 3 to a length of 1, which is position 3 only (length cannot be zero). If position 3 is a period, the remaining length of &INPUT is calculated. The value of &X is advanced to the beginning of the remainder, and the remaining portion of &INPUT is moved to &REMAINDER.

If position 3 is not a period, the procedure checks to see if it is at position 49. If so, it assumes that position 50 is a period and returns. If it is not at position 49, the procedure advances &X to position 4 and repeats the process.