Invoking DCMT and DCUF Commands from Programs

You can invoke DCMT and DCUF commands from application programs. The procedures for invoking these commands are similar: your program invokes the DCUF or DCMT command by linking to the same program that is invoked when the command is entered from a terminal. Unless the programs are changed on site by the database administrator, their names are as follows:
idmscu19
You can invoke DCMT and DCUF commands from application programs. The procedures for invoking these commands are similar: your program invokes the DCUF or DCMT command by linking to the same program that is invoked when the command is entered from a terminal. Unless the programs are changed on site by the database administrator, their names are as follows:
  • RHDCMT00 -- Invokes all DISPLAY and VARY DCMT commands.
  • RHDCUF00 -- Invokes all SET and SHOW DCUF commands.
The program names end with two zeroes.
This article describes the following information:
2
2
Linking to RHDCMT00 and RHDCUF00
RHDCMT00/RHDCUF00 handles all output. Therefore, you must specify the NONOVERLAYABLE option for RHDCMT00/RHDCUF00 on the system generation PROGRAM statement.
RHDCMT00 Link Statement
The calling program links to the DCMT program RHDCMT00, passing the addresses of INREC and OUTREC as parameters:
#LINK PGM='RHDCMT00',PARMS=(INREC,OUTREC)
RHDCUF00 Link Statement
The calling program then links to the DCUF program RHDCUF00, passing the addresses of INREC and OUTREC as parameters:
#LINK PGM='RHDCUF00',PARMS=(INREC,OUTREC)
Parameters
The application program must allocate storage for two parameters, INREC and OUTREC, before calling RHDCMT00 or RHDCUF00.
  • INREC -- Contains the command, prefixed by a halfword with the length of the command.
  • OUTREC -- Contains control information such as return code and output handling and where text output may be returned.
INREC Format
The format is identical for RHDCUF00 and RHDCMT00.
Field
Length
Type
Length of DCMT/DCUF command
2 bytes
Binary
DCMT/DCUF command, left-justified
Any number of bytes
Character
OUTREC Format
The format is identical for RHDCUF00 and RHDCMT00.
Field
Length
Type
return-area-length:
*
Length of the
returned-text-area
allocated by the calling program at the end of OUTREC. The calling program must specify this value. If
return-area-length
and
output-code
are set to zero, all DCMT/DCUF text output is discarded. DCMT VARY and DCUF SET commands are still performed.
4 bytes
Binary
return-code:
**
0 -- Request accepted and processed
4 -- Invalid syntax
8 -- Invalid request (for example, SHUTDOWN, ABORT)
12 -- Security violation
16 -- Processing error
20 -- The
output-code
is 0 or 2 and the
return-area-length
is less than
output-length
. All complete lines whose total length (including a one-byte line-length indicator for each line) is less than or equal to
return-area-length
are stored in
returned-text-area
. The value of
output-code
determines how any remaining output lines are handled. If
output-code
= 0, the lines are discarded. If
output-code
= 2, the lines are written to scratch.
2 bytes
Binary
output-code:
*
Halfword code indicating DCMT output target as follows:
0 -- The
returned-text-area
at the end of OUTREC.
1 -- The scratch area with a scratch ID of "DCMT" or "DCUF" depending on the called program. Each line is written as a separate scratch record.
2 -- Any complete lines of output whose total length (including a one-byte line-length indicator per line) is less than or equal to
return-area-length
are written to
returned-text-area
. Remaining output is written to the scratch area with a scratch ID of "DCMT."
2 bytes
Binary
output-length:
**
Total length required for DCMT/DCUF output. It includes the total length all text lines plus one byte (line-length indicator) for each line.
Note:
Each line-length indicator byte is counted as part of the
output-length
regardless of whether the record is written to the
returned-text-area
, written to scratch, or discarded.
The line-length indicator byte is inserted before each text line written to the
returned-text-area
. The line-length indicator is not written into scratch records. Using the #GETSCR or GET SCRATCH command with the appropriate parameters, you can determine the length of a individual scratch record.
4 bytes
Binary
returned-output-length:
**
Total length of text lines inserted into the
returned-text-area
. The length includes a one-byte line-length indicator for each text line.
4 bytes
Binary
returned-text-area:
**
Area where the DCMT/DCUF is to return text output. Each text line is preceded by a one-byte field which contains the length of the text line (excluding the line-length indicator) as a hexadecimal value. Only lines whose total length is less than
return-area-length
are written into the
returned-text-area
. Other lines are discarded or written to the scratch area depending on the value of
output-code
.
DCMT/DCUF prefills this field with blanks up to the lesser value of the length specified in
return-area-length
or 256 bytes. If
return-area-length
is greater than 256 bytes, and
returned-output-length
is less than
return-area-length
any remaining storage in
returned-text-area
is not updated and remains as it was when RHDCMT00/RHDCUF00 was called.
Note: To avoid storage overlays, the number of bytes allocated for the
returned-text-area
must be greater than or equal to the value assigned to
return-area-length
.
Variable
Character
Notes:
*
-- Information supplied by the calling program.
**
-- Information supplied by RHDCMT00/RHDCUF00.
Usage
Queued Requests
RHDCMT00 can process commands such as VARY AREA, but it may queue the action. Thus, a return code of zero does not always indicate that a VARY has occurred. The text returned to the output area denotes the status of the request. You can recheck the status of the request by including a SET TIMER POST or SET TIMER WAIT (#SETIME TYPE=POST or #SETTIME TYPE=WAIT in Assembler) statement in your program. After the interval has expired, you can reissue the VARY or issue a DISPLAY statement and check the returned text to determine the status of the request.
Using Scratch Area for Output
If you do not know the exact size of the output, you can specify to send it to the scratch area. This is also a useful method for dealing with possible future changes in output.
Examples
DCMT Example
The following example invokes RHDCMT00 to execute the DCMT VARY ACTIVE TASK command specified in INREC and to handle an invalid command:
  DCMT     TITLE 'SAMPLE DRIVER TO CALL DCMT' CALLDCMT CSECT          LR    R12,R15          USING CALLDCMT,R12          B     BEGIN          #MOPT CSECT=CALLDCMT,ENV=USER BEGIN    DS    0H          #GETSTG LEN=WORKDSL,PLIST=*,ADDR=(R2),TYPE=(USER,LONG),       X                INIT=X'00'     GET WORK AREA FOR REENTRANCY.         USING WORKDS,R2 *  FOLLOWING CODE ISSUES A VALID COMMAND TO CHANGE MAX TASKS. *  RESULTING STATUS CODE, RETURNED LENGTH, AND RETURNED DATA *  ARE DISPLAYED.          MVC   INRECLN,=AL2(L'INRECTXT)  SET COMMAND LENGTH.          MVC   INRECTXT,GOODCOMM         SET COMMAND.          MVC   OUTRECLN,=AL4(L'OUTRECTX) SET MAXIMUM OUTPUT LENGTH.          SR    R1,R1                     SET OUTPUT TYPE TO 0.          STH   R1,OUTRECOD               REQUEST OUTPUT TO STORAGE.          ST    R1,OUTRECTL               INITIALIZE RETURNED LENGTH.          ST    R1,OUTRECAL               INITIALIZE RETURNED LENGTH.          LA    R1,99                     INITIALIZE RETURN CODE.          STH   R1,OUTRECRC          BAL   R8,CALLDISP               CALL DCMT AND DISPLAY RESULTS. *  FOLLOWING CODE ISSUES A COMMAND WITH INVALID SYNTAX. *  RESULTING STATUS CODE, RETURNED LENGTH, AND RETURNED DATA *  (ERROR MESSAGES) ARE DISPLAYED.          MVC   INRECLN,=AL2(L'INRECTXT)  SET COMMAND LENGTH.          MVC   INRECTXT,BADCOMM          SET COMMAND.          MVC   OUTRECLN,=AL4(L'OUTRECTX) SET MAXIMUM OUTPUT LENGTH.          SR    R1,R1                     SET OUTPUT TYPE TO 0.          STH   R1,OUTRECOD               REQUEST OUTPUT TO STORAGE.          ST    R1,OUTRECTL               INITIALIZE RETURNED LENGTH.          ST    R1,OUTRECAL               INITIALIZE RETURNED LENGTH.          LA    R1,99                     INITIALIZE RETURN CODE.          STH   R1,OUTRECRC          BAL   R8,CALLDISP               CALL DCMT AND DISPLAY RESULTS. *  DONE WITH DISPLAYS.  TERMINATE PROGRAM.          #RETURN          EJECT *  SUBROUTINE TO CALL DCMT AND DISPLAY RESULT. * CALLDISP DS    0H          #LINK PGM='RHDCMT00',PARMS=(INREC,OUTREC)          MVC   WORKRCLN,STATLIT          LH    R15,OUTRECRC              GET RETURN CODE.          CVD   R15,WORKDBL               MAKE IT PRINTABLE.          UNPK  WORKRC,WORKDBL          OI    WORKRC+L'WORKRC-1,X'F0'          L     R5,OUTRECAL               GET LENGTH OF OUTPUT.          CVD   R5,WORKDBL                MAKE IT PRINTABLE.          UNPK  WORKLEN,WORKDBL          OI    WORKLEN+L'WORKLEN-1,X'F0'          #LINEOUT OUTLEN=80,OUTAREA=WORKRCLN          LTR   R5,R5                     ANY RETURNED DATA?          BZ    RETURN                    NO.          LA    R4,OUTRECTX               GET A(OUTPUT). PUTLINE  DS    0H                        PUT OUT ONE LINE.          SR    R3,R3                     GET LENGTH OF ONE LINE.          IC    R3,0(,R4)          LA    R4,1(,R4)                 GET A(LINE TEXT)          #LINEOUT OUTLEN=(R3),OUTAREA=(R4)          AR    R4,R3                     POINT TO NEXT LENGTH BYTE.          SR    R5,R3                     REDUCE OUTPUT LENGTH.          BCTR  R5,0                      ACCOUNT FOR LENGTH BYTE.          LTR   R5,R5                     STILL MORE OUTPUT?          BP    PUTLINE                   GET LENGTH OF OUTPUT. RETURN   DS    0H          BR    R8 GOODCOMM DC    CL80'VARY ACTIVE TASK MAX TASK 43' BADCOMM  DC    CL80'BAD SYNTAX IN THIS COMMAND' STATLIT  DS    CL80' '                   TEMPLATE FOR STATUS LINE          ORG   STATLIT                   REDEFINE STATUS LINE          DC    CL13'RETURN CODE: '       RETURN CODE LITERAL          DC    CL2' '                    SPACE FOR RETURN CODE          DC    CL20'.  RETURNED LENGTH: ' LENGTH LITERAL          DC    CL4' '                    SPACE FOR RETURN CODE          DC    CL1'.'                    SPACE FOR RETURN CODE          ORG   STATLIT+80                DONE WITH REDEFINE          LTORG          EJECT WORKDS   DSECT SYSPLIST DS    10F                       PLIST AREA WORKDBL  DS    D                         TEMP WORK AREA WORKRCLN DS    CL80                      OUTPUT LINE FOR RETURN CODE          ORG   WORKRCLN                  REDEFINE STATUS LINE          DS    CL13                      RETURN CODE LITERAL WORKRC   DS    CL2                       SPACE FOR RETURN CODE          DS    CL20                       LENGTH LITERAL WORKLEN  DS    CL4                       LENGTH OF RETURNED DATA          DS    CL1                       SPACE FOR ENDING PERIOD          ORG   WORKRCLN+80               DONE WITH STATUS LINE INREC    DS    0F                        INPUT TO DCMT INRECLN  DS    H                         INPUT LENGTH INRECTXT DS    CL80                      INPUT COMMAND          DS    H                         FILLER OUTREC   DS    0F                        OUTPUT FROM DCMT OUTRECLN DS    F                         MAXIMUM ALLOWED OUTPUT LENGTH OUTRECRC DS    H                         RETURN CODE OUTRECOD DS    H                         OUTPUT TYPE OUTRECTL DS    F                         TOTAL LENGTH OF DCMT OUTPUT OUTRECAL DS    F                         ACTUAL LENGTH RETURNED OUTRECTX DS    CL132                     TEXT OUTPUT AREA WORKDSL  EQU   *-WORKDS          SPACE 2          END
DCUF Example
The following example invokes RHDCUF00 to execute the DCUF SET PRINT CLASS command specified in INREC:
       #LINK PGM='RHDCUF00',PARMS=(INREC,OUTREC)  .  .  . INREC    DS    0F                   Input to DCUF INRECLN  DC    Y(L'INRECTXT)           - length INRECTXT DC    C'SET PRINT CLASS 01'   - command * OUTREC   DS    0F                   Output from DCUF OUTRECLN DC    A(L'OUTRECTX)           - maximum allowed length OUTRECRC DC    H'0'                    - return code OUTRECOD DC    H'0'                    - output type OUTRECTL DC    F'0'                    - total length OUTRECAL DC    F'0'                    - actual length OUTRECTX DS    CL132                   - actual output text