|
The copyFieldToString function transfers characters from a field in the host-connected presentation space into a string.
Prerequisite Calls
connectPresentationSpace
Call Parameters
Parameter name
|
Explanation
|
position
|
Identifies the target field. This can be the Presentation Space position of any byte within the target field. Copy always starts at the beginning of the field.
|
length
|
Number of bytes to copy (the length of the data string).
|
params
|
An object containing a subset of Session Options parameters, which values will take precedence over the defaults for the execution context of this function.
|
Return Properties
Property name
|
Explanation
|
returnCode
|
A numeric code indicating the execution status of the function. Please refer to the Return Code table below for all possible values.
|
length
|
The length of the data returned.
|
data
|
A string containing data from the identified field in the host presentation space. The first byte in the returned data string is the beginning byte of the identified field in the host presentation space. The number of bytes in the returned data string is determined by the smaller of:
| • | Number of bytes specified in the calling length parameter. |
| • | Number of bytes in the identified field in the host presentation space. |
|
Return Code
The following values are defined for the 'returnCode' property:
Return Code
|
Explanation
|
0
|
The copyFieldToString function was successful.
|
1
|
Your program is not connected to a host session.
|
2
|
An error was made in specifying parameters.
|
4
|
Successful connection was achieved, but the host presentation space is busy.
|
5
|
Successful connection was achieved, but the host presentation space is locked (input inhibited).
|
7
|
The host presentation space position is not valid.
|
28
|
Field length of 0 bytes.
|
Remarks
| 1. | This function is equivalent to HLLAPI Function Number 34. |
| 2. | The field position and length information can be found by using findFieldPosition and findFieldLength. The copyFieldToString function can be used with either protected or unprotected fields, but only in a field-formatted presentation space. |
| 3. | The copy is ended when the end of the field is reached. |
| 4. | An EAB can be returned when EAB option has been included in the 'params' Session Parameters options. EAB is related to each character in the presentation space and is returned preceding each character. |
| 5. | The copyFieldToString function is affected by the ATTRB/NOATTRB/NULLATTRB, the EAB/NOEAB, the XLATE/NOXLATE and DISPLAY/NODISPLAY session options. |
|