Skip to content
CA IDMS Reference - 19.0
Documentation powered by DocOps

Invoking DCMT and DCUF Commands from Programs

Last update July 27, 2017

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.
Note: The program names end with two zeroes.

This article describes the following information:

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

Was this helpful?

Please log in to post comments.