Assignment - SUBSTR Pseudovariable

Purpose

Modifies only the substring.

Syntax

SUBSTR(r,i,j)=e;

SUBSTR(r,i)=e;

or

SUBSTR(array,i,j)=string_value;

Parameters

r: A reference to a character or bit-string variable.

I: A fixed-point integer-valued expression; the index of the first character or bit in r to change.

j: A fixed-point integer-valued expression; the number of bits or characters to be changed.

e: An expression that can be converted to a character string or bit string.

array: A character or bit string array, as in: susbtr (array(i,j) = string_value;

Description

The SUBSTR pseudovariable refers to a substring of a specific string variable reference.

Assignment to the SUBSTR pseudovariable modifies only the substring portion of r. If r identifies a varying string, the substring assignment does not modify the length component of that string.

If r identifies a varying string, w is the current length of r. If r identifies a nonvarying string, w is the declared length of the string variable. If j is omitted, j is assumed to be w-I+1. The value of e is assigned to the substring according to the assignment rules for nonvarying strings.

Example

DECLARE S CHARACTER(10);
   .
   .
   .
SUBSTR(S,3,4) = 'ABC';

After the assignment, the 3rd character of S is 'A', the 4th is 'B', the 5th is 'C', and the 6th is blank. The other characters of S are unchanged by the assignment.

Restrictions

The following restrictions on I, j, and w must be satisfied or the program may be in error, causing the ERROR condition to be generated if compiled with subscript checking enabled, or unpredictable results if compiled without subscript checking enabled.

1<=I<=w
I+j-1<=w 
j>0

The previous restrictions ensure that I is the index of a character or bit within the string, and that a substring of j characters or bits beginning with the Ith character or bit can be accessed without exceeding the length of the string. These formulas also ensure that I is less than or equal to the length of string r if j=0. If j is omitted, the substring begins with the Ith character or bit and extends to the end of the string. No other portion of the target string is affected by the assignment.

The substring described by I and j is assigned the converted value of the expression e as if the substring were a nonvarying string.