Technical Notes

HLLAPI Custom Compatibility Mask in Reflection 2007
Technical Note 2176
Last Reviewed 06-Jul-2007
Applies To
Reflection for IBM 2007
Summary

This technical note describes Reflection for IBM 2007 HLLAPI custom compatibility mask feature.

About HLLAPI

HLLAPI (High-Level Language Application Programming Interface) is a widely-used API that enables Windows applications to communicate with mainframe applications using the HLLAPI support provided by a 3270 or 5250 terminal emulation program, such as Reflection for IBM 2007.

HLLAPI terminal emulation software is not all the same. Each implementation of HLLAPI has slightly different behavior. Reflection for IBM 2007 provides several options that enable you to specify how HLLAPI behaves.

Access the HLLAPI Settings

To access the Reflection HLLAPI settings, follow the steps below.

1. In the Reflection Workspace, click the Document Settings icon.

2. Under Host Connection, click Configure Advanced 5250 (or 3270) Settings.
3. Jump to the HLLAPI section.

HLLAPI Compatibility

If you are migrating from a legacy EXTRA! or Reflection product, and your application uses the default HLLAPI compatibility settings, simply select Reflection or EXTRA! from the Compatibility drop-down list. This configures the HLLAPI support in Reflection for IBM 2007 to match the default settings found in those applications.

If your application requires custom HLLAPI compatibility settings, select Custom from the Compatibility drop-down menu. Once Custom is selected, the Custom Compatibility Mask field becomes writeable. Use the information in the following section to determine the correct value to enter in the Compatibility Mask field.

Note: For details about the HLLAPI Short name and Long name settings, refer to the Reflection online help.

HLLAPI Custom Compatibility Mask

The possible numeric values for the custom compatibility mask style are "bit masks" that contain separate bits of information about Reflection's HLLAPI configuration. Each style is equated to a decimal and hexadecimal value. A list of the styles and values is shown in the table below.

To create a compatibility mask, add the decimal or hexadecimal values of each style and enter the sum into the Compatibility Mask field. Values can be entered in either decimal or hexadecimal format; however, when using hexadecimal values, replace the "0x" at the front of the value with "&H." For example, to use hexadecimal value 0x5380, enter &H5380 in the Compatibility Mask field.

For example, to turn on the Propagate EAB (decimal value = 1), Input Inhibited Position (decimal value = 8), and Don't Wrap at PS End (decimal value = 512), add these three numbers (1 + 8 + 512 = 521) and enter the total into the Compatibility Mask field.

The following predefined constants are available from the Compatibility drop-down menu:

Name of Constant	Decimal Value	Hexadecimal Value *
EXTRA!	21376	0x5380
Reflection	297	0x129
Custom	<enter value>	<enter value>

* When entering hex value, replace "0x" with "&H"

HLLAPI Compatibility Mask Styles

HLLAPI style bit masks, their definitions and values are shown in the following table.

Style	Decimal Value	Hexadecimal Value
Propagate EAB When this bit is on, executing a Copy Presentation Space or Copy Presentation Space to String function, with the EAB and NOXLATE session parameters, causes each extended attribute specified at the start of a field to be copied to all characters in the field that do not have the corresponding extended attribute explicitly on. When this bit is off, the attribute is not copied to such characters. This bit applies only to 3270 sessions.	1	0x0001
Query Host Update Protocol When this bit is on, Query Test Update functions report changes to the presentation space only if they are initiated by the host. When this bit is off, functions report changes initiated from the host or from the keyboard.	2	0x0002
Input Inhibited Position This bit determines the position of the "input inhibited" indicator in the string returned from Copy OIA. When it is on, the indicator appears at position 9. When it is off, the indicator appears at position 5.	4	0x0004
Copy PS to String Beyond End This bit determines what happens when the Copy Presentation Space to String function specifies a string that goes beyond the end of the presentation space. When it is on, no error is reported, the data from the position specified to the end of the presentation space is copied, and the remainder of the result string is set to binary zeros. When it is off, Reflection returns an error (APIPARAMETERERROR, value 2).	8	0x0008
Wait a Second When this bit is on, HLLAPI waits one second beyond the last host-initiated presentation space modification before attempting to return a result. When it is off, HLLAPI does not wait. This affects functions Copy OIA, Query Host Update, Copy Presentation Space to String, and Copy Presentation Space.	16	0x0010
Modify Protected Field When this bit is on, the Copy Presentation Space to String function can be used to copy to protected fields. When it is off, such copies are disallowed.	32	0x0020
Translate 5250 Attributes to 3270 When this bit is on, attributes copied by the HLLAPI application from the 5250 presentation space are translated to 3270 attributes. When it is off, Reflection returns 5250 attribute values (with the high order 2 bits on).	64	0x0040
Always Blank When this bit is on, data characters found in the presentation space (by Copy Presentation Space to String or Copy Presentation Space) that can not be translated to ASCII are always translated to spaces. When it is off, the ATTRB setting is used to specify what should be done with such characters (if ATTRB is on, they are passed as their original value; if it is off, they are translated to spaces).	128	0x0080
Transmit Modified Protected Fields This bit is relevant when HLLAPI modification of protected fields is allowed (see Modify Protected Field). When it is on, the modified protected field is not sent to the host in response to a read modified command. When it is off, the modified protected field is sent.	256	0x0100
Don't Wrap at PS End This bit determines what happens if, on a copy from a string to the presentation space, the end of the presentation space is reached before the string is completely copied. If this bit is on, the operation terminates and returns an APITRUNCATED error. If it is off, copying continues at the beginning of the presentation space.	512	0x0200
Error on Bad Escape When this bit is on, undefined escape sequences passed to Send Key are reported by returning APIPARAMETERERROR. When it is off, such errors are ignored.	2048	0x0800
Terminate Send Key at AID The default behavior for Send Key is to divide strings to be sent into segments terminated by an AID key, and then to send these segments sequentially, reporting an error only if the emulator objects (through input inhibited or busy status). When this bit is on, HLLAPI terminates the send after the first such segment, reporting an error if Error on Send Key Past AID is on. When this bit is off, HLLAPI does not report an error under such circumstances.	4096	0x1000
Error on Send Key Past AID When this bit is on, the HLLAPI application reports an error if Send Key continues to send characters after a transmitted AID key. When it's off, the application does not report an error under such circumstances.	8192	0x2000
Return Zero Length Fields If this bit is set, Find Field Position (31) returns APIOK and position of next field (in the position parameter) for a zero length field. Otherwise, it returns APIZEROLENFIELD and a 0 in the position parameter.	16384	0x4000
Caching Off When set on, this bit disables the caching mechanism that increases performance. If you are having problems with your application synching with the Reflection screen, try turning on this bit. After enabling this bit, you may notice some degradation in HLLAPI performance.	32768	0x8000
Old Flashpoint Flashpoint versions 3.1 and earlier expect consecutive CopyPS calls to include or not include attributes regardless of how attributes are set. Turning on this bit makes HLLAPI accept this behavior.	65536	0x10000
DOS ASCII Converter This bit converts a HLLAPI character to DOS ASCII format.	131072	0x20000
Rumba Style Reflection's HLLAPI configuration is like Rumba's.	297	0x0129
Extra Style Reflection's HLLAPI configuration is like EXTRA!'s.	21376	0x5380

Related Technical Notes

2183	Developer Tools for Attachmate Products
2211	Reflection for IBM 2007 Technical Notes