[ Previous | Next | Contents | Search ]
3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

COPY STRING TO FIELD (33)

Purpose

Transfers a string of characters into a specified field in the host-connected Presentation Space (PS). This function can be used only in a field-formatted host PS.

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 STRING TO FIELD function:

func Specifies the number of the function called; must be 33 for the COPY STRING TO FIELD function.
apistring Specifies the string containing the data to be transferred to a target field in the host PS.
len Specifies the length, in bytes, of the source data string. This parameter is not applicable if in EOT mode.
ret Identifies the target field. This field can be the PS position of any byte within the target field. The copy always starts at the beginning of the field.

Returned Parameters

ret The following codes are valid:
0 Indicates the COPY STRING TO FIELD function was successful.
1 Indicates that your program was not connected to the host session.
2 Identifies a parameter error; a string length of 0 was specified.
5 Specifies that the target field was protected or inhibited, or data that is not allowed was sent to the target field (such as a field attribute).
6 Specifies that the copy was completed, but data was truncated.
7 Indicates the host PS position was invalid.
9 Indicates a system error occurred.
24 Indicates the host PS was unformatted.

Remarks

The COPY STRING TO FIELD function is affected by the STRLEN/STREOT, EAB/NOEAB, and the EOT session options. See session options 1, 2, and 9 of the SET SESSION PARAMETERS (9) function for more information. Keyboard mnemonics cannot be sent with the COPY STRING TO FIELD function. (For information on keyboard mnemonics, see the SEND KEY (3) function.) The first byte of the data to be transferred is always placed at the beginning of the field that contains the specified PS position.

The string to be transferred is specified with the calling data string parameter. The string ends when one of the following conditions occurs:

If the field at the end of the host PS wraps, the COPY STRING TO FIELD function continues at the start of the PS.

Additional DBCS Remarks

The COPY STRING TO FIELD function is affected by the STRLEN/STREOT, EAB/NOEAB, EOT, and the EAD/NOEAD session options.

DBCS characters can be included in the string. SO/SI is added accordingly. When SBCS and DBCS characters are used, the length in EBCDIC can be longer than in ASCII because of addiitional SO/SI . Some data may be truncated. If the last character of the source data string is the first byte of a DBCS character, it is not transferred.

Control characters are transferred to a one-byte character or two-byte character according to the field condition. NULL + control character between SO and SI is handled as a control character.

Related Information

CONNECT PRESENTATION SPACE (1) function. SEND KEY (3) function and SET SESSION PARAMETERS (9) function.

[ Previous | Next | Contents | Search ]