SINSERT
PLBCMP Only
The SINSERT instruction provides a means of inserting data from a character string variable into another character string variable. The transfer shifts all data in the destination variable to the right, one position for each byte inserted. The instruction uses the following format:
|
|
|
|
|
Where:
label
Optional. A Program Execution Label.
dest
Required. A previously defined Character String Variable into which {source} bytes are transferred.
sep
Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.
source
Required. A previously defined Character String Variable from which bytes are transferred into {dest}.
count
Required. A previously defined Numeric Variable, Expression, or decimal constant indicating the number of bytes to transfer.
Flags Affected: LESS, OVER, ZERO
Note the following:
SINSERT attempts to insert {count} bytes of the Logical String of {source} into {dest} beginning at the Form Pointer of {source}. If {count} is not specified, the entire Logical String of {source} is used. Both the Form Pointer and Length Pointer of {dest} are incremented for each byte inserted, up to the Physical Length.
If {dest} is a Null String, the LESS Condition Flag is set and no action occurs.
If {source} is a Null String and {count} was specified, blanks are inserted for the designated number of bytes. Otherwise, the ZERO Condition Flag is set.
If {count} is greater than the Logical String of {source}, {dest} is blank-filled from the end of the Logical String of {source} through the designated number of bytes.
If {count} equals zero, the ZERO Condition Flag is set and no operation occurs.
If significant (non-blank) data could be lost in {dest} as a result, the OVER Condition Flag is set and no operation occurs.
The SINSERT instruction is obsolete and the SPLICE instruction should be used instead.
Example 1:
|
|
|
|
|
|
Variable |
PL |
FP |
LP |
Contents |
|
Before: |
DEST |
20 |
6 |
11 |
John Public········· |
|
|
FILLER |
10 |
1 |
8 |
Quentin··· |
|
| |||||
|
After: |
DEST |
20 |
14 |
19 |
John Quentin Public· |
|
|
FILLER |
10 |
1 |
8 |
Quentin··· |
No Condition Flags are set (all FALSE).
Example 2:
|
|
|
|
|
|
Variable |
PL |
FP |
LP |
Contents |
|
Before: |
DEST |
20 |
6 |
20 |
John Public········· |
|
|
FILLER |
10 |
1 |
7 |
Quentin··· |
|
|
COUNT |
2 |
|
|
·1 |
|
| |||||
|
After: |
DEST |
20 |
7 |
20 |
John-QPublic········ |
|
|
FILLER |
10 |
1 |
7 |
Quentin··· |
|
|
COUNT |
2 |
|
|
·1 |
No Condition Flags are set (all FALSE) since no significant (non-blank) data was lost.
Example 3:
|
|
Variable |
PL |
FP |
LP |
Contents |
|
Before: |
DEST |
20 |
6 |
11 |
John-Public········· |
|
|
FILLER |
10 |
0 |
0 |
Quentin··· |
|
|
COUNT |
2 |
|
|
·7 |
|
| |||||
|
After: |
DEST |
20 |
13 |
18 |
John········Public·· |
|
|
FILLER |
10 |
0 |
0 |
Quentin··· |
|
|
COUNT |
2 |
|
|
·7 |
No Condition Flags are set (all FALSE). FILLER is blank filled since it was null (Form Pointer is zero).
Example 4:
|
|
|
|
|
|
|
|
|
|
|
|
|
John Public········· |
|
|
|
|
|
|
Quentin··· |
|
|
|
|
|
|
·0 |
|
| |||||
|
|
|
|
|
|
John-Public········· |
|
|
|
|
|
|
Quentin··· |
|
|
|
|
|
|
·0 |
The EOS Condition Flag is set since COUNT was equal to zero.
Example 5:
|
|
|
|
|
|
|
|
|
|
|
|
|
Jonathan Public····· |
|
|
|
|
|
|
Quentin-Adams |
|
|
|
|
|
|
·8 |
|
| |||||
|
|
|
|
|
|
Jonathan-Public····· |
|
|
|
|
|
|
Quentin-Adams |
|
|
|
|
|
|
·8 |
The LESS Condition Flag is set since DEST is null.
Example 6:
|
|
|
|
|
|
|
|
|
|
|
|
|
Jonathan Public····· |
|
|
|
|
|
|
Quentin Adams |
|
|
|
|
|
|
·8 |
|
| |||||
|
|
|
|
|
|
Jonathan Public····· |
|
|
|
|
|
|
Quentin Adams |
|
|
|
|
|
|
·8 |
The OVER Condition Flag is set since significant data would be lost (lic). Therefore, no operation was performed.
See Also: SDELETE, Character String Instructions
|
|