OVRLAY: Overlaying a Character String

How to:

The OVRLAY function overlays a base character string with a substring. The function enables you to edit part of an alphanumeric field without replacing the entire field.

Syntax: How to Overlay a Character String

OVRLAY(source_string, length, substring, sublen, position, output)

where:

source_string

Alphanumeric

Is the base character string.

stringlen

Integer

Is the number of characters in source_string and output, or a field that contains the length. If this argument is less than or equal to 0, unpredictable results occur.

substring

Alphanumeric

Is the substring that will overlay source_string.

sublen

Integer

Is the number of characters in substring, or a field that contains the length. If this argument is less than or equal to 0, the function returns spaces.

position

Integer

Is the position in source_string at which the overlay begins. If this argument is less than or equal to 0, the function returns spaces. If this argument is larger than stringlen, the function returns the source string.

output

Alphanumeric

Is the name of the field that contains the result, or the format of the output value enclosed in single quotation marks. If the overlaid string is longer than the output field, the string is truncated to fit the field.

Note that if the overlaid string is longer than the output field, the string is truncated to fit the field.

Example: Replacing Characters in a Character String

OVRLAY replaces the last three characters of EMP_ID with CURR_JOBCODE to create a new security identification code and stores the result in NEW_ID:

TABLE FILE EMPLOYEE
PRINT EMP_ID AND CURR_JOBCODE AND COMPUTE
NEW_ID/A9 = OVRLAY(EMP_ID, 9, CURR_JOBCODE, 3, 7, NEW_ID);
BY LAST_NAME BY FIRST_NAME
WHERE DEPARTMENT EQ 'MIS';
END

The output is:

LAST_NAME        FIRST_NAME  EMP_ID     CURR_JOBCODE  NEW_ID
---------        ----------  ------     ------------  ------
BLACKWOOD        ROSEMARIE   326179357  B04           326179B04
CROSS            BARBARA     818692173  A17           818692A17
GREENSPAN        MARY        543729165  A07           543729A07
JONES            DIANE       117593129  B03           117593B03
MCCOY            JOHN        219984371  B02           219984B02
SMITH            MARY        112847612  B14           112847B14

Example: Overlaying a Character in a String With MODIFY

This MODIFY procedure prompts for input using a CRTFORM screen and updates first names in the EMPLOYEE data source. The CRTFORM LOWER option enables you to update the names in lowercase, but the procedure ensures that the first letter of each name is capitalized.

MODIFY FILE EMPLOYEE
CRTFORM LOWER
  "ENTER EMPLOYEE'S ID: <EMP_ID"
  "ENTER FIRST_NAME IN LOWER CASE: <FIRST_NAME"
MATCH EMP_ID
 ON NOMATCH REJECT
 ON MATCH COMPUTE
  F_UP/A1  = UPCASE(1, FIRST_NAME, 'A1');
  FIRST_NAME/A10 = OVRLAY(FIRST_NAME, 10, F_UP, 1, 1, 'A10');
  ON MATCH TYPE "CHANGING FIRST NAME TO <FIRST_NAME "
  ON MATCH UPDATE FIRST_NAME
DATA
END

The COMPUTE command invokes two functions:

  • UPCASE extracts the first letter and converts it to uppercase.
  • OVRLAY replaces the original first letter in the name with the uppercase initial.

The procedure processes as:

  1. The procedure prompts you from a CRTFORM screen for an employee ID and a first name. Type the following data and press Enter:

    Enter the employee's ID: 071382660

    Enter the first name in lowercase: alfred

  2. The procedure searches the data source for the ID 071382660. If it finds the ID, it continues processing the transaction. In this case, the ID exists and belongs to Alfred Stevens.
  3. UPCASE extracts the letter a from alfred and converts it to the letter A.
  4. OVRLAY overlays the letter A on alfred. The first name is now Alfred.
    ENTER EMPLOYEE'S ID:
    ENTER FIRST_NAME IN LOWER CASE:
    CHANGING FIRST NAME TO Alfred
  5. The procedure updates the first name in the data source.
  6. When you exit the procedure with PF3, the transaction message indicates that one update occurred:
    TRANSACTIONS:         TOTAL =     1  ACCEPTED=     1  REJECTED=     0
    SEGMENTS:             INPUT =     0  UPDATED =     1  DELETED =     0