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

COPY PRESENTATION SPACE TO STRING (8)

Purpose

Copies all or part of the host-connected Presentation Space (PS) into a data string defined in your HLLAPI application program.

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

func Specifies the number of the function called; must be 8 for the COPY PRESENTATION SPACE TO STRING function.
apistring Specifies the attributes of the API string; must be a previously allocated target data string.
len Specifies the length of the target data string.
ret Specifies the position in the host PS where the copy begins; between 1 and the maximum PS size.

Returned Parameters

apistring Specifies the contents of the host PS.
ret The following codes are valid:
0 Specifies that the attempt was successful; the host PS contents were copied to the application program. The target PS was active, and the keyboard was unlocked.
1 Specifies that the attempt was unsuccessful; your program was not connected to the host session.
2 Indicates that a string length of 0 was specified.
4 Specifies that the attempt was successful; the connected host PS was waiting for host response.
5 Specifies that the attempt was successful; the keyboard was locked.
7 Indicates the host PS position is invalid.
9 Indicates that a system error occurred.

Remarks

The COPY PRESENTATION SPACE TO STRING function translates the characters in the host source PS into ASCII format. Attribute bytes and other characters not represented in ASCII are translated into blanks. If you do not want the attribute bytes translated into blanks, use the ATTRB option under the SET SESSION PARAMETERS (9) function.

The EXTENDED ATTRIBUTES BYTES (EAB) option under the SET SESSION PARAMETERS (9) function can be used with this function to return EABs. An EAB is associated with each character on the presentation space and follows each character when this option is used.

The XLATE option is not supported.

The input PS position is the offset into the host PS. This offset is based on a layout in which the upper-left corner (row 1, column 1) is position 1. The bottom-right corner of the host PS has the highest position number.

The COPY PRESENTATION SPACE TO STRING function is affected by the ATTRB/NOATTRB, and EAB/NOEAB options. See the command description in SET SESSION PARAMETERS (9) for more information.

The return of attributes by the various COPY (5, 8, and 34) functions is affected by the SET SESSIONS PARAMETERS (9) function. The involved SET SESSION PARAMETERS options have the following effect:

Set Session Parameter Effect on the COPY Functions
NOEAB Attributes are not returned. Only text is copied from the presentation space to the user buffer.
EAB and NOXLATE Attributes are returned as defined.

The returned character attributes are defined. The attribute bit positions are in the format with bit 0 as the leftmost bit in the byte.

3270 Field Attributes
Bit position Meaning
0-1 Character highlighting 00   Normal 01   Blink 10   Reverse Video 11   Underline
2-4 Character color (Color remap may override this color definition.) 000   Default 001   Blue 010   Red 011   Pink 100   Green 101    Turquoise 110    Yellow 111   White
5-7 Reserved (not used)

DBCS Remarks

The EAD option under the SET SESSION PARAMETERS (9) function can be used with this function to return two-byte EADs. An EAD follows each character when this option is used without the EAB option and follows each EAB when it is used with the EAB option.

If a copied multibyte character is larger than two bytes, EAB or EAD of the second byte of the DBCS character in the presentation space is returned for the third byte and after.

If the copy starts at the second byte of a DBCS character or ends at the first byte of a DBCS character, this byte is copied as a one-byte blank character.

3270 Field Attributes

The COPY PRESENTATION SPACE TO STRING function is affected by the ATTRB/NOATTRB, EAB/NOEAB, EAD/NOEAD, and the SPACESO/SO/NOSO options. See the command description in SET SESSION PARAMETERS (9) for more information.

Set Session Parameter Effect on the COPY Functions
NOEAB and NOEAD Attributes are not returned. Only text is copied from the presentation space to the user buffer.
EAB and NOXLATE Attributes are returned as defined.
EAD DBCS attributes are returned as defined.
SPACESO/SO/NOSO NOSO works as SPACESO. Therefore the length of returned presentation space is unchanged.
3270 Field Attributes
Bit position Meaning
5-6 Character set attributes 00   Default 11   Double-byte character
7 Reserved (not used)

DBCS attributes

Byte 1
Bit position Character position Field attributes position
0 Double-byte character Reserved
1 First byte of Double-byte character Reserved
2 SO Pair of SO/SI exists
3 SI Reserved
4 Unusable position Reserved
5 Reserved SO/SI creation enable
6 Reserved Character attributes exists
7 Reserved Reserved
Byte 2
Bit position Character position Field attributes position
0 Reserved Left vertical line(field attributes)
1 Reserved Over line(field attributes)
2 Reserved Right vertical line(field attributes)
3 Reserved Under line(field attributes)
4 Left vertical line Left vertical line
5 Over line Over line
6-7 Reserved Reserved

Related Information

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

[ Previous | Next | Contents | Search ]