COPY FIELD TO STRING (34)

3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

COPY FIELD TO STRING (34)

Purpose

Transfers characters from a field in the host-connected presentation space (PS) to a string.

Prerequisite Calls

This function requires a prerequisite call to the CONNECT PRESENTATION SPACE (1) function.

Syntax

hllc (func, apistring, len, ret)
int *func;
char *apistring;
int *len;
int *ret;

Supplied Parameters

Supply the following parameters to invoke the COPY FIELD TO STRING function:

func	Specifies the number of the function called; must be 34 for the COPY FIELD TO STRING function.
apistring	Specifies preallocated target data string.
len	Specifies number of bytes to copy. (Length of data string.)
ret	Identifies the source, which can be the PS position of any byte within the source. The COPY FIELD TO STRING function always starts at the beginning of the field.

Returned Parameters

len

A string containing data from the identified field in the host PS. The first byte in the returned data string is the beginning byte of the identified field in the host PS. The number of bytes in the returned data string is determined by the smaller of the following:

Number of bytes specified in the len parameter.
Number of bytes in the identified field in the host PS.

ret

The following return codes are valid:

0	Indicates the COPY FIELD TO STRING function was successful.
1	Specifies that your program is not currently connected to the host session.
2	Indicates an error was made in specifying parameters.
6	Specifies that the data to be copied and the source were not the same size. The data is truncated if the string length was smaller than the field copied.
7	Indicates the host PS position is invalid.
9	Indicates that a system error occurred.
24	Specifies that the host PS is unformatted.

Remarks

Before transferring characters from a field in the host-connected PS to a string, you should locate field position and length information. Find field position and length information by using the FIND FIELD POSITION (31) and FIND FIELD LENGTH (32) HLLAPI functions. Use the COPY FIELD TO STRING function with either protected or unprotected fields, but only in a field-formatted host PS.

The string ends when one of the following conditions occurs:

The length of the target string is exceeded.
The end of the field is reached.
Note: If the field at the end of the host PS wraps, the COPY FIELD TO STRING function continues at the start of the PS.

DBCS Remarks

If the target string ends at the first byte of a DBCS character, this byte is transferred as a one-byte blank character.

Related Information

CONNECT PRESENTATION SPACE (1) function, FIND FIELD POSITION (31) function, and FIND FIELD LENGTH (32) function.

[ Previous | Next | Contents | Search ]