copyStr()

The vgLib.copyStr() system function copies characters from one substring to another. Despite the name, you cannot use strings with this function.

vgLib.copyStr() is one of a number of functions maintained for compatibility with earlier versions. New code should use standard EGL operators for these purposes.

If the source substring is longer than the target substring, the source substring is truncated. If the source substring is shorter than the target substring, the source substring is padded on the right with spaces.

Syntax

  vgLib.copyStr(
    target CHAR | DBCHAR | MBCHAR | UNICODE | NUM inOut,
    targetSubstringIndex INT in,
    targetSubstringLength INT in,
    source CHAR | DBCHAR | MBCHAR | UNICODE | NUM in,
    sourceSubstringIndex INT in,
    sourcetSubstringLength INT in)
target
A character variable (excluding STRING) from which the target substring is derived.
targetSubstringIndex
Identifies the starting byte of the substring in target, given that the value of the first byte is 1. This index can be an integer literal or variable (INT or BIN(9)).
targetSubstringLength
Identifies the number of bytes in the substring that is derived from target. This length can be an integer literal or variable (INT or BIN(9)).
source
Character variable from which a source substring is derived. Can be a variable or a literal.
sourceSubstringIndex
Identifies the starting byte of the substring in source, given that the value of the first byte is 1. This index can be an integer literal or variable (INT or BIN(9)).
sourceSubstringLength
Identifies the number of bytes in the substring that is derived from source. This length can be an integer literal or variable (INT or BIN(9)).

Error considerations

If you use V6 exception compatibility (see Using V6 exception compatibility), the following values are returned in sysVar.errorCode:
8
Index less than 1 or greater than string length.
12
Length less than 1.
20
Index for a DBCHAR or UNICODE string points to the middle of a double-byte character.
24
Length in bytes for a DBCS or UNICODE string is odd (double-byte lengths must always be even).

Example

The following example copies the source characters into the middle of the target characters:

target, source CHAR (6); // index must be multiple of 2
target = "120056";
source = "34";
vgLib.copyStr(target,3,2,source,1,2); // target = "123456"

Feedback