Defining the Interface Communications Area (DSQCOMM)

QMF provides an interface communications macro for each supported programming language. This macro contains the following information:

The interface communications area (DSQCOMM) or communications variables
Definitions of return and reason codes
Definition of the function calls to QMF

This macro defines some storage that contains the variables described in the preceding list. This storage is the callable interface communications area, and the variables stored in this area are accessible to both QMF and the callable interface application, although only QMF should alter the values. The application program should view these variables as read only.

The REXX callable interface uses interface communications variables provided by QMF rather than using a communications area.

The QMF callable interface communications area is required for all callable interface calls. Storage for the callable interface communications area is allocated by the program that is using QMF.

The START command establishes a unique instance or occurrence of a QMF session. The START command can establish only one QMF session:

In a TSO address space
In a single CMS virtual machine
From a single CICS transaction

When running the START command, QMF updates the interface communications area or variables.

The interface communications area or variables must never be altered by the application program, with the following exceptions:

DSQ_COMM_LEVEL: Set DSQ_COMM_LEVEL to the value of DSQ_CURRENT_COMM_LEVEL to identify the level of DSQCOMM. This does not apply to REXX.
DSQ_INSTANCE_ID: If you call a callable interface program from within QMF, you need to set the DSQ_INSTANCE_ID to zero (0) on the first call so that QMF resets the variable to the value set by the initial START command.

All calls that follow the START command must pass the address of the interface communications area that corresponds to the QMF instance. The application program is responsible for pointing to the correct interface communications area.

Each supported language has a unique communications macro that describes the interface communications area. Application programs must reference variables by variable name rather than value if they are to be portable, because the values can be different on other systems.

The interface communications area or variables contain the information in Table 3, which must not be altered by the calling program:

Table 3. DSQCOMM fields that must not be altered
Field	Description
Return code	Indicates the status of QMF processing after QMF processes a command.
Instance identifier	Identifies the instance of QMF that was started by the START command.
Completion message ID	Contains the message ID of the message that QMF displays at the user's terminal, if the command were issued there. This field is set at the completion of every QMF command. It contains the message QMF displays at the end of a command.
Query message ID	Contains the message ID of a QMF message resulting from a RUN QUERY command. This is the message ID of the message that is displayed in a user's query. This field is set when an error occurs while a query is running. It contains the message QMF displays within the query object at the end of a command.
START command parameter in error	Contains the parameter in error when the START command fails because of a parameter error.
Cancel indicator	Indicates if the user canceled the command processing while QMF was running the command.
Completion message	Contains the completion message that QMF displays at the user's terminal.
Query message	Contains the query message text that resulted from a RUN QUERY command. This is the text that QMF displays in a user's query. For example, if you run a query object with an error, QMF displays a message describing the error that prevented the query from running. Query message then contains this error message text.

[ Previous Page | Next Page | Contents | Index ]