APPEND
The APPEND instruction appends source data to a character string. The instruction uses the following formats:
|
|
|
|
|
|
|
|
|
|
Where:
label
Optional. A Program Execution Label.
source
Required. A previously defined Character String Variable, National Character String Variable, Literal, National Character String Literal,, Numeric Variable , or String Expression that is appended to the {dest} variable when using syntax format 1. When using syntax format 2, the source data is appended to source1 and the resulting string is moved to {dest}.
source1
Required. A previously defined Character String Variable, National Character String Variable, Literal, National Character String Literal,, Numeric Variable , or String Expression which contains the initial data that is being appended to when using syntax format 2. In this case, the source data is appended to the source1 data and the resulting string is moved to {dest}.
sep
Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.
dest
Required. A previously defined Character String Variable, or National Character String Variable that receives the APPEND result.
Flags Affected: EOS
Note the following:
When using syntax format 1, the {source} is appended to {dest} immediately after the Form Pointed character. The Form Pointer and Length Pointer both point to the last character appended. If the Physical Length of {dest} is exhausted before the APPEND is complete, the EOS Condition Flag is set.
When using syntax format 2, the {source} data is appended to the {source1} data and the resulting string is moved to {dest}. Transfer of the resulting string begins at the first Physical character of {dest}. The Form Pointer of {dest} is set to one (1), and the Length Pointer is set to the last character transferred. If the Physical Length of {dest} is exhausted before the complete resulting string is transferred, the EOS Condition Flag is set.
When a Character String Variable is used as a {source} or {source1} operand, only its Logical String participates in the APPEND operation.
When a Numeric Variable is used as a {source} or {source1} operand, its entire Physical String participates in the APPEND operation.
When using syntax format 2, a NULL {source} or {source1} operand contributes no characters to the append operation. If only one operand is NULL, the resulting string consists of the non-NULL operand data.
When using syntax format 2, if both {source} and {source1} are NULL strings, the resulting string is NULL. No characters are transferred to {dest}, the Form Pointer of {dest} is set to zero (0), the Length Pointer remains unchanged, and the EOS Condition Flag is not set.
The {source} and {source1} remains unchanged.
Enhanced ARRAY processing is supported for the APPEND instruction.
The National Character String Variables can ONLY contain valid UTF-8 characters. Otherwise, a F14 error occurs.
Example 1:
|
|
|
|
|
|
Variable |
PL |
FP |
LP |
Contents |
|
Before: |
SEND(3) |
10 |
4 |
6 |
ABCDEF···· |
|
|
RECVING |
12 |
4 |
4 |
1234········ |
|
| |||||
|
After: |
SEND(3) |
10 |
4 |
6 |
ABCDEF···· |
|
|
RECVING |
12 |
7 |
7 |
1234DEF····· |
No Condition Flags are set (all FALSE).
Example 2:
|
|
Variable |
PL |
FP |
LP |
Contents |
|
Before: |
SEND(3) |
10 |
1 |
8 |
ABCDEFGH·· |
|
|
RECVING |
12 |
8 |
8 |
12345678···· |
|
| |||||
|
After: |
SEND(3) |
10 |
1 |
8 |
ABCDEFGH·· |
|
|
RECVING |
12 |
12 |
12 |
12345678ABCD |
The EOS Condition Flag is set. RECVING was too small.
See Also: PACK, PACKKEY, REMOVE, Character String Instructions
|
|