Communicating with a program (EXTRACT, QEDIT)

The operator can pass information to the started program by issuing a STOP or a MODIFY command. In order to accept these commands, the program must be set up in the following manner.

The program must issue the EXTRACT macro to obtain a pointer to the communications ECB and a pointer to the first command input buffer (CIB) on the CIB chain for the task. The ECB is posted whenever a STOP or a MODIFY command is issued. The EXTRACT macro is written as follows, and returns what is indicated in Figure 1.

EXTRACT answer area,FIELDS=COMM

Figure 1. EXTRACT ECB Address, CIB Address, and Program Token

The CIB contains the information specified on the STOP, START, or MODIFY command. If the job was started from the console, the EXTRACT macro will point to the START CIB. If the job was not started from the console, the address of the first CIB will be zero. For more information on the contents of the command input buffer (CIB) and mapping macro IEZCIB, see z/OS MVS Data Areas in the z/OS Internet library.

If the address of the START CIB is present, use the QEDIT macro to free this CIB after any parameters passed in the START command have been examined. The QEDIT macro is written as follows:

QEDIT ORIGIN=address of pointer to CIB,BLOCK=address of CIB

Note:

The address of the pointer to the CIB is the contents of the answer area plus 4 bytes, as shown in Figure 1.
The address of the CIB must be the exact address returned by EXTRACT, not an address generated from copying the CIB to another location.

The CIB counter should then be set to allow CIBs to be chained and MODIFY commands to be accepted for the job. This is also accomplished by using the QEDIT macro:

QEDIT ORIGIN=address of pointer to CIB,CIBCTR=n

The value of n is any integer value from 0 to 255. If n is set to zero, no MODIFY commands are accepted for the job. However, STOP commands are accepted for the job regardless of the value set for CIBCTR. After a STOP command is issued, the system sets the value of CIBCTR to zero to prevent more modify CIB‘s from being chained. To continue processing modify‘s after a STOP command, you must use the QEDIT macro to set the CIBCTR to non-zero.

Note: When using the address or addresses returned from the EXTRACT macro as input to the QEDIT macro, you must establish addressability through the COM data area (mapped by IEZCOM), based on the address returned by the EXTRACT. For a description of the COM data area, see z/OS MVS Data Areas in the z/OS Internet library.

For the duration of the job, your program can wait on or check the communications ECB at any time to see if a command has been entered for the program. Check the verb code in the CIB to determine whether a STOP or a MODIFY command has been entered. After processing the data in the CIB, issue a QEDIT macro to free the CIB.

The communications ECB is cleared by QEDIT when no more CIBs remain. Care should be taken if multiple subtasks are examining these fields. Any CIBs not freed by the task are unchained by the system when the task is terminated. The area addressed by the pointer obtained by the EXTRACT macro, the communications ECB, and all CIBs are in protected storage and may not be altered.

The portion of the program follows the procedure outlined in the preceding paragraphs. It shows how you can code the EXTRACT and QEDIT macros to accept MODIFY and STOP commands. The full example would use reentrant code.

R1       EQU   1
R7       EQU   7
R9       EQU   9
R10      EQU   10
R14      EQU   14
         USING *,R10              MODULE ADDRESSABILITY
         LA    R9,COMADDR         GET COMMUNICATIONS AREA
*                                 ADDRESS AT COMADDR
*------------------------------------------------------------------*
*        OBTAIN ADDRESS OF THE CIB                                 *
*------------------------------------------------------------------*
         EXTRACT (R9),FIELDS=COMM,MF=(E,EXTRACT)
*                                 EXTRACT THE COMMUNICATIONS AREA
         L     R9,COMADDR         GET ADDRESS OF THE AREA
         USING COM,R9             USE R9 AS BASE ADDRESS OF COMM AREA
         ICM   R7,15,COMCIBPT     GET CIB ADDRESS FROM COM AREA
         BZ    NOCIB              NO CIB, TASK WAS NOT STARTED
         BAL   R14,DOCIB          PROCESS THE CIB
NOCIB    DS    0H
         QEDIT ORIGIN=COMCIBPT,CIBCTR=5   SET MODIFY LIMIT TO 5
         L     R1,COMECBPT        GET ADDRESS OF THE COMMUNICATION ECB
         O     R1,HIBITON         SET HIGH BIT - LAST ECB IN LIST
         ST    R1,MODECB          PUT ADDR OF MODIFY ECB IN LIST
*
*
*
WAIT     DS    0H
         WAIT  ECBLIST=ECBS       WAIT FOR A MODIFY/STOP
*
*  WHEN POSTED HERE, A MODIFY OR STOP HAS BEEN ISSUED
         ICM   R7,15,COMCIBPT     GET CIB ADDRESS FROM COM AREA
         USING CIB,R7             BASE CIB MAPPING
         CLI   CIBVERB,CIBMODFY   WAS IT A MODIFY?
         BNE   NOTMDFY            NO, GO FREE CIB
         BAL   R14,DOCIB          IT WAS A MODIFY, GO PROCESS COMMAND
*
*
*
*------------------------------------------------------------------ *
*        FREE THE CIB                                               *
*------------------------------------------------------------------ *
NOTMDFY  DS    0H
         BAL   R14,DELCIB         FREE CIB
         CLI   CIBVERB,CIBSTOP    WAS IT A STOP?
         BE    EXITRTN            BRANCH TO ROUTINE HANDLING ERRORS
         B     WAIT               WAIT FOR ANOTHER MODIFY
*        .
*        .
DELCIB   DS    0H
*        USE QEDIT TO FREE THE CIB
*        QEDIT WILL ALSO CLEAR THE ECB
*
         QEDIT ORIGIN=COMCIBPT,BLOCK=(R7)   FREE THE CIB
         BR    R14

DOCIB    DS    0H
*-------------------------------------------------------------------*
* YOUR ROUTINE TO HANDLE CIB PROCESSING WOULD GO HERE.              *
*-------------------------------------------------------------------*
*
*
*
*-------------------------------------------------------------------*
*  CONSTANTS                                                        *
*-------------------------------------------------------------------*
         DS    0F                 FULLWORD ALIGNMENT
HIBITON  DC    X'80000000'        USED TO TURN HIGH ORDER BIT ON
*-------------------------------------------------------------------*
*  FIELDS REQUIRED IN DYNAMIC STORAGE                               *
*-------------------------------------------------------------------*
ECBS     DS    0CL4               ECB LIST FOR WAIT
MODECB   DS    A                  ADDR(MODIFY/STOP ECB)
COMADDR  DS    F                  ADDR(COMAREA) FROM EXTRACT
SV       DS    18F                SAVE AREA
EXTRACT  EXTRACT MF=L             EXTRACT PARAMETER LIST
*-------------------------------------------------------------------*
*  REQUIRED DSECTs                                                  *
*-------------------------------------------------------------------*
COM      DSECT
         IEZCOM   ,                COM AREA
CIB      DSECT
         IEZCIB   ,                CIB
         END