Passing input to your program, using call GSREAD

GDDM V3R2 Base Application Programming Guide

Passing input to your program, using call GSREAD

GDDM V3R2 Base Application Programming Guide
SC33-0867-01

A single action by the end user can generate up to five types of input, depending on which logical devices are enabled. For instance, pressing a PF key could create:

Choice input consisting of a code representing the key.
Locator input consisting of the position of the cursor.
Pick input consisting of the identities of the primitive and segment over which the cursor is positioned.
String input consisting of a character string typed by the end user.
Stroke input consisting of the preceding track of the cursor.

GDDM presents the input to your program as a queue, with one element, or record, for each enabled type of logical input device. Making the records on the queue available to your program is a second function of the GSREAD call, in addition to its I/O function. This is how it works:

If the input queue is empty, then, unless you specify otherwise, a GSREAD call sends the data to the terminal, waits for input, and when the input is received, adds one or more records to the input queue. It then removes the top record from the queue, and makes it available for your program to query.
If the input queue is not empty, a GSREAD call simply removes the next record from the queue and makes it available for querying. It does not do any I/O.

In addition, GSREAD reads any alphanumeric data that the end user may have typed in.

When GSREAD has made a record available, you may inspect it by issuing a query call, namely GSQCHO, GSQLOC, GSQPIK, GSQSTR, or GSQSTK. Your program is in error if the query is not the appropriate one for the currently available record. The order of the records is undefined, so if you have more than one logical input device enabled, it is essential to test the second parameter of GSREAD before issuing a query.

It is important to remember that GSREAD does no I/O unless the queue is empty. In other words, GSREAD does not update the screen while there are any records on the queue. To avoid problems, the recommended technique is to empty the queue immediately after it has been created, as shown in "Handling the input queue" in topic 11.9.

GDDM ensures that a GSREAD call issued when the input queue is empty always results in at least one input record being created. If the end user causes an interrupt that does not create an input record, GDDM rejects it. No input record is created if, for instance, the end user presses the CLEAR key when this has not been enabled as a choice device. In such cases, GDDM sounds the terminal alarm and waits for another interrupt.

Subtopics:

11.8.1 Checking for further graphics input records using call GSQSIM

Notices | Terms of use | Support | Contact z/OS