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

COPY PRESENTATION SPACE (5)

Purpose

Copies the contents of the host presentation space (PS) into a data string that you 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 function:

func Specifies the number of the function called; must be 5.
apistring Specifies the attributes of the API string; must be an allocated string of at least the maximum size of the PS (normally 1920 bytes). The size can vary due to 3270 model specification.
Note: Caution should be used when allocating buffer space for the PS. The buffer should be at minimum as large as the largest possible PS size regardless of the configured PS sizes.
len Does not apply for this function (length of the host PS is implied).
ret Does not apply for this function.

Returned Parameters

apistring Specifies the contents of the host PS.
ret The following codes are valid:
0 Specifies that the attempt was successful; the source PS was active, and the keyboard was unlocked.
1 Specifies that the attempt was unsuccessful; your program was not connected to the host session.
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.
9 Indicates a system error occurred.

Remarks

The COPY PRESENTATION SPACE function translates the characters from the host 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.

If you want to copy only a portion of the host PS, use the COPY PRESENTATION SPACE TO STRING (8) function.

The COPY PRESENTATION SPACE 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 of the leftmost bit in the byte is bit 0.

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, this byte is copied as a one-byte blank character.

The COPY PRESENTATION SPACE 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
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, COPY PRESENTATION SPACE TO STRING (8) function, SET SESSION PARAMETERS (9) function.

[ Previous | Next | Contents | Search ]