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

COPY STRING TO PRESENTATION SPACE (15)

Purpose

Copies an ASCII data string directly into the host Presentation Space (PS) at the location specified by the PS position parameter.

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 PRESENTATION SPACE function:

func Specifies the number of the function called; must be 15 for the COPY STRING TO PRESENTATION SPACE function.
apistring Specifies the string of ASCII data to be copied into the host PS.
len Specifies the length, in number of bytes, of the source data string. This parameter is overridden if in EOT mode.
ret Specifies the position in the host PS where the copy begins.

Returned Parameters

ret The following codes are valid:
0 Indicates the COPY STRING TO PRESENTATION SPACE function was successful.
1 Indicates 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 PS was protected or inhibited, or data that is not allowed was sent to target PS (such as a field attribute byte).
6 Specifies that the copy was completed, but the data was truncated.
7 Specifies that the host PS position was invalid or string length exceeds PS size.
9 Indicates a system error occurred.

Remarks

The COPY STRING TO PRESENTATION SPACE function is affected by the STRLEN/STREOT, and the EOT=c session options. For more information, see session options 1, 2, and 9 in SET SESSION PARAMETERS (9) function. The string ends when an end-of-transmission (EOT) character is encountered in the string (if you selected EOT mode by using the SET SESSION PARAMETERS (9) function).

Although the SEND KEY (3) function serves the same purpose as the COPY STRING TO PRESENTATION SPACE function, the latter is much faster in answering prompts and entering commands. The SEND KEY (3) function emulates a terminal operator typing data from the keyboard. However, this function is too slow for applications that require large amounts of data for each function. The COPY STRING TO PRESENTATION SPACE function provides a much faster input path to the host.

The keyboard mnemonics cannot be sent with the COPY STRING TO PRESENTATION SPACE function. (For information on keyboard mnemonics, see the SEND KEY (3) function.) Also, the source data (the string being copied) can be no larger than the maximum PS size.

Additional DBCS Remarks

The COPY STRING TO PRESENTATION SPACE function is affected by the STRLEN/STREOT, EOT=c, 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 additional 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 copied. If a character to be copied at the last position of the presentation space is SO/SI or the first byte of a DBCS character, it is not copied.

Control characters are copied 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 ]