Calls to most of the interfaces can result in a direct I/O operation, or in the storing of commands in a command buffer. The command buffer provides a way of saving the commands so that multiple operations can be specified and performed in a single I/O operation. DSM performs error handling as much as possible prior to issuing an I/O operation. For example, if a request is made to place the screen in wide mode, and the display does not support this mode, DSM detects and reports the error condition before performing an I/O operation. This way of handling errors is particularly useful in the case where multiple commands have been saved in a buffer. Otherwise, there is no obvious way to determine which command was in error when the I/O operation fails.
The errors that can occur for each operation are listed with the operation. If an error message indicates that the error is issued for a negative response code, this means that the error was not detected by DSM and occurred on the I/O operation.
Note: When you are using the i5/OS(TM) TELNET display station emulation, an unsuccessful I/O operation may be undetected initially, but will be reported on the next operation.
The 5250 Query command is used to determine the valid commands for a particular device. This command is issued for the current device at the start of each DSM session and the information is saved for subsequent queries. If the 5250 Query command is not supported, the base data stream support as documented in the 5250 Functions Reference is assumed, with color and wide support being determined by the device type.
The low-level interfaces operate within an environment that can be defined using the Create Low-Level Environment (QsnCrtEnv) API. The low-level environment defines the operating modes, such as DBCS support and the window mode. The environment is passed as a parameter to most of the low-level services APIs. There is no need to define a low-level environment unless you need a specific operating environment that is different from the default. The default low-level environment is indicated on the low-level service APIs by specifying the environment handle as zero.
Many of the low-level APIs accept an optional command buffer as a parameter. For such APIs, the command buffer can be used to store and accumulate a group of requested operations. The accumulated operations can then be written to the screen in a single I/O operation. Better performance can be achieved because a group of repetitive operations can be issued to the screen without having to recall the sequence of individual APIs for each repeated operation.
A direct operation is one that omits the command buffer. The requested operation takes place immediately. For most APIs, specifying the command buffer results in an indirect operation. No I/O operation takes place and the operation is simply stored in the command buffer. Several of the screen input APIs, however, do perform a direct operation when the command buffer is specified. This semantic is discussed in Read Input Fields (QsnReadInp) API.
You can write DBCS data enclosed with SO/SI to the screen, and when the underlying display supports it, graphic DBCS using the Write Data (QsnWrtDta) API to specify the data stream Write Extended Attribute order. (See the 5250 data stream documentation for further details.) You can define fields as being DBCS through the Set Field (QsnSetFld) API using the appropriate field control word. DBCS data can be written to such fields as described above. If you specify DBCS support on the low-level environment description, (see Format of the Low-Level Environment Description), the APIs will handle the parsing of DBCS data and fields appropriately.
The APIs do not provide any special processing of DBCS data, such as adding SO/SI to DBCS graphic data when graphic data is not supported by the display. For example, if you want to define a field as graphic DBCS and write graphic DBCS data to it, code the QsnSetFld API specifying a control word of QSN_FCS_DBCS_PURE (x'8220') and then write the graphic data to a command buffer using the QsnWrtDta API. Precede and follow this data with Write Extended Attribute orders to add the extended NLS SO/SI attributes. If you want to write a graphic data value to a non-graphic DBCS field, you must enclose the graphic DBCS data with SO/SI prior to calling the QsnWrtDta API.
The following operations can incur overhead and adversely affect the performance of your application:
Specifying translation of x'3f' to x'1f' can incur overhead because all outgoing data must be checked for this value. This option should be specified only if CDRA is on and translation between the code pages will result in a x'3f' occurrence in data to be displayed.
This operation results in the entire contents of the screen being read, which can adversely affect response time. This is typically about 3KB, but could be up to 28KB.
This operation writes the result of a save screen back to the device, which can adversely affect response time.
If you have GUI support, you can put additional commands after the QsnSavScr or QsnRstScr APIs to reduce I/O operations and improve performance.
Deleting structures associated with handles, such as command buffers, prior to exiting a program will improve performance for the programs that use APIs that create handles.
The following limitations or restrictions apply to the low-level interfaces:
| Top | Dynamic Screen Manager APIs | APIs by category |