Copy Field to String (34)

 Top  Previous  Next

The Copy Field to String function transfers characters from a field in the host-connected presentation space into a string.

 

The Copy Field to String function translates the characters in the host source presentation space into American National Standard Code for Information Interchange (ASCII). Attribute bytes and other characters not represented in ASCII normally are translated into blanks.

 

3270

5250

Yes

Yes

 

 

Prerequisite Calls

 

Connect Presentation Space (1)

 

 

Call Parameters

 

 

Standard Interface

Function Number

Must be 34

Data String

Preallocated target data string. When the Set Session Parameters (9) function with Extended Attribute Bytes (EAB) option is issued, the length of the data string must be at least twice the length of the field.  DBCS Only: When Extended Attributes Double-byte (EAD) option is specified, the length of the data string must be at least three times the length of the field. When both EAB and EAD options are specified, the length of the data string must be at least four times the length of the field.

Length

Number of bytes to copy (the length of the data string).

PS Position

Identifies the target field. This can be the PS position of any byte within the target field. Copy always starts at the beginning of the field.

 

 

Return Parameters

 

This function returns a data string, length, and a return code.

 

Data String

 

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

 

Length

 

The length of the data returned.

 

Return Code

 

The following codes are defined:

 

Return Code

Explanation

0

The Copy Field to String function was successful.

1

Your program is not connected to a host session.

2

An error was made in specifying parameters.

6

The data to be copied and the target field are not the same size. The data is truncated if the string length is smaller than the field copied.

7

The host presentation space position is not valid.

9

A system error was encountered.

24

Unformatted host presentation space.

 

 

Remarks

 

1.The field position and length information can be found by using the Find Field Position (31) and Find Field Length (32) functions. The Copy Field to String function can be used with either protected or unprotected fields, but only in a field-formatted host presentation space.
2.The copy is ended when one of the following conditions is encountered when the end of the field is reached and when the length of the target string is exceeded.
3.DBCS Only: If the target string is ended at the higher byte of the DBCS character, the byte is translated into a blank. If the EAD option is set to on, three bytes are returned for each character. If both the EAB and EAD options are set to on, four bytes are returned for each character. When the field wraps at the end of the presentation space, wrapping occurs when the end of the presentation space is reached.
4.DBCS Only: The Set Session Parameters (9) function EAD option is used with this function to return a 2-byte EAD. If the EAD option is specified instead of the EAB option, EAD is returned preceding each character. If both the EAB and EAD options are specified, EAD is returned preceding the EAB.
5.An EAB can be returned when the Set Session Parameters (9) function EAB option is used. EAB is related to each character in the presentation space and is returned preceding each character.
6.The Copy Field to String function is affected by the ATTRB/NOATTRB/NULLATTRB, the EAB/NOEAB, the XLATE/NOXLATE, the DISPLAY/NODISPLAY, the DISPLAY/NODISPLAY, the EAD/NOEAD (for DBCS only), and the NOSO/SPACESO/SO (for DBCS only) session options.
7.To use this function, preallocate memory to receive the returned data string parameter. The statements required to preallocate this memory vary depending on the language in which your application is written.