String COPY

Syntax

Command
Mandatory parameter
Optional parameter
Mandatory keyword
Optional keyword

<Destination> := <Source>.COPY (<Position>[, <Length>])

Description

Copies a part of an alphanumeric variable into another variable. If no length is specified, the substring value is copied from the specified position until the end of the variable.

The String COPY command is similar to the COPY command but it is based on the C# String.Copy method.
One difference to the COPY command is how it handles type conversion, see the remarks section below.

Diagram

Returned value type

Realstring

Parameters

Parameter	Description
<Destination>	Variable into which the result value is copied.
<Source>	Alphanumeric variable from which the substring is copied.
<Position>	Expression giving the position of the substring. If an invalid position (e.g. a value higher than the <Item> length) is returned, the system item RESOK will be set to "FALSE". If a valid position is specified, RESOK will retain its current value.
<Length>	Expression giving the length of the substring.

Remarks

The copied substring will always be handled according to the type of the specified <Source>. This means that if the <Source> is a string and the substring contains trailing spaces, these spaces will be omitted.


The AMT Developer studio will give a warning when the copy command is using a literal value as length which is greater than the length of the destination variable.


When copying alphas to numerics the substring should contain only numbers or spaces. Leading and trailing spaces will be ignored, spaces between numbers will be interpreted as zeros. This is a different behaviour than the COPY command, see examples D in both commands.

When copying alphas to numerics the substring should contain only numbers or spaces.
Leading and trailing spaces will be ignored, spaces between numbers will be interpreted as zeros.

This is a different behaviour than the COPY command, see examples D in both commands.

Examples

A
    str  := 'abcdef'
    str2 := str.copy (4, 2)
    // The value for str2 becomes "de"

B
    str  := 'abcdef'
    str2 := str.copy (length(str) - 1)
    // The value for str2 becomes the last two characters of str
    // i.e. "ef"

C
var
    sa-10 : alpha 10
    sn-3  : numeric 3 value 23

routine main
    str2 := sa-10.copy (sn-3, 1)
    // The position in sn-3 (23) is invalid for
    // the source item sa-10. ResOk will be set to False

D
var

    sa-5 : alpha 5
    sn-3 : numeric 3

routine main
begin_routine

    sa-5 := '123'
    sn-3 := sa-5.copy (3, 3)
    // When copying into a numeric, leading and trailing spaces will be ignored
    // Result: sn-3 is '003'