Skip to content
CA Datacom Tools - 15.1
Documentation powered by DocOps

Communications

Last update January 31, 2019

CA Datacom® CICS Services does not allow an application program to directly issue such commands as CONNECT, DISCONNECT, IMMEDIATE, OPEN and CLOSE. However, there are situations and procedures which require that an application control environmental conditions. For example, a master menu application might control all transaction executions. To satisfy such special requirements, use one of the following methods of communicating with CA Datacom® CICS Services:

Communication Method Purpose Output
Standard CA Datacom Tools - Source Call Issuing CONNECT, DISCONNECT, IMMEDIATE, LOAD, DELETE, RESTART,DEFER, AUTO, OPEN, and CLOSE commands for a specific MUF or User Requirements Table (URT) or issuing an inquiry for a specific URT.

Provides output to the Message Log file (DBOCPRT).

Provides a special return code having limited meaning (see Return Codes).

CICS Link Issuing CONNECT, DISCONNECT, IMMEDIATE, LOAD, DELETE, RESTART, AUTO, DEFER, OPEN and CLOSE commands for a specific MUF or User Requirements Table (URT).
Provides a standard CA Datacom®/DB return code indicating the results of the command.
CICS XCTL Issuing any DBOC command or DBEC command. Initiate DBTS or DBUG process.

Provides output to the terminal.

Provides output to the Message Log file (DBOCPRT).

Provides no response to the linking application.

CICS Interval Control Start

(started task)

Issuing any DBOC command or inquiry or any DBEC command.

Provides output to the Message Log file (DBOCPRT).

Provides no response to the starting task.

MVS CONSOLE Issuing any URT or MUF action excluding inquiry. Provides output to the DBOCPRT file. For DBEC in remote mode, it is the CICS DBOCPRT where the reuest was routed.
Note: The commands passed to CA Datacom® CICS Services using any of the previous methods are checked for MSTOPR authorization before being allowed to execute.

This page contains the following topics:

Standard CA Datacom®/DB Call

If an application needs to issue a CA Datacom® CICS Services command, the simplest method is to use the CA Datacom®/DB Request Area. This method does not return a response or produce output. It does provide a special return code with limited meaning in the CA Datacom®/DB Request Area. Any response from CA Datacom® CICS Services which would normally appear on a terminal is written only to the Message Log file (DBOC). The failure or success of the command is not returned to the issuing application.

Procedure

Use the following procedure to issue a CA Datacom® CICS Services transaction with a CA Datacom®/DB call.

  1. Place DBOC in the command field of the Request Area. It is presumed that the command field is set to DBOC. No validation of the field is done by CA Datacom® CICS Services.
  2. Place the length (in hexadecimal) of the command text in the first two bytes of the Work Area, followed by the command text beginning with the transaction ID followed by a space. The wildcard character ? (a question mark) is not supported in this mode.

Example Work Area

In the following example, DBOC CLOSE=nnnn is the CA Datacom® CICS Services command (character) and the nn (in nnDBOC) is the length of command text (hexadecimal).

 ----+----1----+----2----+----3----+----4----+----5----+----6


 nnDBOC CLOSE=nnnn

If the DISCONNECT, CONNECT, and IMMEDIATE commands are used, they must be coded exactly as shown following:

  • nnDBOC DISCONNECT=mm where nn is X'0014' or greater and mm is the MUF number
  • nnDBOC CONNECT=mm where nn is X'0011' or greater and mm is the MUF number
  • nnDBOC IMMEDIATE=mm where nn is X'0013' or greater and mm is the MUF number.

Return Codes

When issuing CA Datacom® CICS Services transactions with a standard CA Datacom®/DB call, CA Datacom® CICS Services returns a code to the CA Datacom®/DB Request Area return code field. Access information about these return codes through the Messages page.

Sample COBOL Program

The following sample program demonstrates how the request and work area are completed when using the CA Datacom®/DB Request Area to issue a CA Datacom® CICS Services command.

       IDENTIFICATION DIVISION.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
         ..

       01  WRK-USER-ID.
           02  WRK-UID-PGM         PIC X(8)           VALUE 'PGMNAME '.
           02  WRK-UID-FILLER      PIC X(24)          VALUE SPACES.
         ..

       01  WRK-RQ-AREA.
           02  WRK-RQ-CMD          PIC X(5)           VALUE 'DBOC '.
           02  WRK-FILLER          PIC X(8)           VALUE SPACES.
           02  WRK-RQ-RTCODE       PIC XX             VALUE SPACES.
           02  WRK-REMINDER        PIC X(241)         VALUE SPACES.
         ..

       01  WRK-WORK-AREA.
           02  WRK-CMD-LTH         PIC S9999  COMP    VALUE +0.
           02  WRK-CMD             PIC X(80)          VALUE SPACES.
        ..

       PROCEDURE DIVISION.
        ..

       START-UP SECTION.
           MOVE 'DBOC OPEN=0010' TO WRK-CMD.
           MOVE +13             TO WRK-CMD-LTH.
           CALL 'DBNTRY' USING WRK-USER-ID, WRK-RQ-AREA, WRK-WORK-AREA.
           IF WRK-RQ-RTCODE IS NOT EQUAL TO SPACES GO TO ERR-RTN.
        ..

       SHUT-DOWN SECTION.
           MOVE 'DBOC CLOSE=0010' TO WRK-CMD.
           MOVE +14              TO WRK-CMD-LTH.
           CALL 'DBNTRY' USING WRK-USER-ID, WRK-RQ-AREA, WRK-WORK-AREA.
           IF WRK-RQ-RTCODE IS NOT EQUAL TO SPACES GO TO ERR-RTN.

        ..

       ERR-RTN SECTION.

        ..

        ..

With Return Response

An application can issue OPEN and CLOSE commands for a specific MUF or URT. In response, the application receives a standard CA Datacom®/DB return code indicating the results of the command. Details on using a CICS link with a communication area are provided following.

When you need to know the results of a CONNECT, DISCONNECT, IMMEDIATE, LOAD, DELETE, RESTART, DEFER, AUTO, OPEN or CLOSE, use a CICS link to DCCOCPR with a communication area (DFHCOMMAREA). This method accepts only one MUF or URT ID per request and returns the CA Datacom®/DB return code for that MUF or URT.

Procedure

Complete the DFHCOMMAREA as follows:

Column Contents
1 -- 4 DBLC -- (Required) No other format is accepted.
6 -- 80 Code either CONNECT=muf, DISCONNECT=muf, LOAD=urt, DELETE=urt, RESTART=urt, DEFER=urt, AUTO=urt, OPEN=urt or CLOSE=urt. No other commands are accepted. Express the URT ID as a 4-digit number, for example, use 0001 for URT 1. Each transaction opens or closes one and only one URT. Express the MUF ID as a 2-digit number relative to the order of the DBCSID macros in the DBCVTPR, for example, use 01 for MUF 1 (the default MUF). Each transaction disconnects, connects, or disconnects immediate one and only one MUF. You cannot use a wildcard or delimiter character.
81 -- 82
Blank. Upon completion, CA Datacom® CICS Services places a standard CA Datacom®/DB return code here.

Example

DFHCOMMAREA

Before executing the link, complete the 82-byte communication area as shown following. Each field is position dependent. Place blanks in the Return Code field (positions 81-82).

 ----+----1----+----2----+----3----+----4----+----5 . . . +----8--


 DBLC OPEN=0001                                      . . .

                                                               |  |

                                                              Return

                                                               Code

                                                               Field

After Link

After the command is completed, control returns to the linking program and the DFHCOMMAREA is changed. CA Datacom® CICS Services places a message (if any) in positions 1-80 and the standard CA Datacom®/DB return code in positions 81-82. Information about the CA Datacom® CICS Services messages and return codes are accessible from the Messages page. For multiple calls to CA Datacom® CICS Services, the program must reestablish the communication area before each call.

 ----+----1----+----2----+----3----+----4----+----5 . . . +----8--


 DC00177E  URT 0001 OPEN ERROR, RC=25               . . .       25

 |                                 |                           |  |

  CA Datacom CICS Services                                    Return

        Error Message                                          Code

Return Codes

Interpret this return code as follows:

Return Code Meaning
blank The command processed successfully.
nonblank Access information about these message codes through the Messages page.

Sample COBOL Program

The following sample program demonstrates how the communication area is completed to command CA Datacom® CICS Services to OPEN URT 0001.

Note: For an assembler example, the delivered DCCALPR sample program provides examples of the various DBLC commands and can be modified to test different functions.

       IDENTIFICATION DIVISION.

         ..

       ENVIRONMENT DIVISION.

       DATA DIVISION.

       WORKING-STORAGE SECTION.

         ..

       01  COMM-AREA.

           02  COMM-AREA-ID      PIC  X(05)       VALUE SPACES.

           02  COMM-AREA-COMMAND PIC  X(75)       VALUE SPACES.

           02  COMM-AREA-RTNCDE  PIC  X(02)       VALUE SPACES.

         ..

         ..

       PROCEDURE DIVISION.

         ..

         ..

           MOVE 'DBLC ' TO COMM-AREA-ID.

           MOVE 'OPEN=0001'     TO COMM-AREA-COMMAND.

           EXEC CICS LINK PROGRAM('DCCOCPR') COMMAREA(COMM-AREA)

                LENGTH(82)  END-EXEC.

           IF COMM-AREA-RTNCDE EQUAL TO SPACES

                 GO TO NO-ERR.

           MOVE COMM-AREA-COMMAND  TO WORKCMDO.

           MOVE COMM-AREA-RTNCDE   TO WORKCDEO.

           EXEC CICS SEND MAP('XXXXXXX') MAPSET('XXXXXX')

                ERASE END-EXEC.

       NO-ERR.

         ..

CICS XCTL

With this method, your application may initiate:

  • Any DBOC Command
  • Any DBEC Command
  • The DBUG Facility
  • The DBTS Facility

If you want to develop a menu driver or initiate a DBOC command, use a CICS XCTL to DCCOCPR with a communication area completed as described here. For DBEC, XCTL to DCCECPR.

Procedure for DBOC or DBEC Commands

The communication area (DFHCOMMAREA) must be at least 80 bytes in length.

  • Supply the command in the same format as you would type on a terminal.
  • Issue an EXEC CICS XCTL to program DCCOCPR for DBOC or to DCCECPR for DBEC. This program examines the communication area and performs the command, overwriting any panel or data on the terminal with the response of the command.
  • Once the command is complete, DCCOCPR or DCCECPR returns control to CICS.

Procedure for DBUG Command

The communication area (DFHCOMMAREA) must be at least 80 bytes in length.

  • Supply the DBUG transaction as you would on a terminal. You can follow the transaction ID with any valid operand.
  • Issue an EXEC CICS XCTL to program DCCFBPR. This program examines the communication area and displays the DEBUG Criteria Selection Panel, overwriting any panel or data on the terminal. If the criteria has been supplied with the transaction, the message is displayed that the request has been serviced and overwrites any panel or data on the terminal.
  • Press Clear after all interaction is completed. DCCFBPR returns control to CICS.

Procedure for DBTS

The communication area (DFHCOMMAREA) must be at least 80 bytes in length.

  • Supply the DBTS transaction as you would on a terminal.
  • Issue an EXEC CICS XCTL to program DCUTSPR. This program examines the DFHCOMMAREA to determine that DBTS is required.
  • Place the transaction ID (DBTS) in the DFHCOMMAREA.
  • DBTS is displayed and sent to the terminal where you can interact with the DBTS facility.
  • Press Clear after all interaction is completed. DCUTSPR returns control to CICS.

Example

DFHCOMMAREA

 ----+----1----+----2----+----3----+----4----+----5 . . . +----8


 DBOC RESTART=????  (for example)

  or

 DBTS

  or

 DBUG or DBUG BOTH (for example)

  or

 DBEC P,MSIDNAME(DBSIDPR),DISCONNECT,SYSID(CZDS) (for example)


Sample COBOL Program

The following sample program demonstrates how to address and format the DFHCOMMAREA to command CA Datacom® CICS Services to open URTs or to initiate the DBUG or DBTS facility.

       IDENTIFICATION DIVISION.
         ..

       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
         ..

       01  COMM-AREA.
           02  COMM-AREA-ID      PIC  X(05)       VALUE 'DBOC '.
           02  COMM-AREA-COMMAND PIC  X(75)       VALUE SPACES.
           02  COMM-AREA-RTNCDE  PIC  X(02)       VALUE SPACES.
         ..

         ..

       PROCEDURE DIVISION.
         ..

         ..

           MOVE 'OPEN=0001'     TO COMM-AREA-COMMAND.
           EXEC CICS XCTL PROGRAM('DCCOCPR') COMMAREA(COMM-AREA)
                LENGTH(82)  END-EXEC.
         ..
         ..
         ..
       END-PGM.
         ..

CICS Interval Control Start

Use this method to issue any DBOC or DBEC command as a separate CICS task. With this method, CA Datacom® CICS Services provides no return code or response. When CA Datacom® CICS Services processes the command, it writes any response to the Message Log file (DBOCPRT) and to the terminal, if one is specified.

When using an Interval Control Start, provide a data area containing the command in the same format as you would type on a terminal. For details about using an Interval Control Start, see the CICS application programming documentation. Use the terminal ID parameter to identify the output display, if one is available.

Interval Control Start Data Area

 ----+----1----+----2----+----3----+----4----+----5 . . . +----8

DBOC OPEN=0001

Sample COBOL Program

The following sample program demonstrates issuing a CA Datacom® CICS Services command as a separate task using the CICS Interval Control Start.

IDENTIFICATION DIVISION

    ..  
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
         ..
       01  WORK-AREA.
           02  WORK-AREA-COMMAND PIC  X(80)       VALUE SPACES.
         ..
         ..
       PROCEDURE DIVISION.
         ..
      *---------------------------------------------------------------*
      *    EXAMPLE WITHOUT TERMID                                     *
      *---------------------------------------------------------------*
           MOVE 'DBOC OPEN=0001'   TO WORK-AREA-COMMAND.
           EXEC CICS START TRANSID('DBOC')
                FROM(WORK-AREA) LENGTH(80)  END-EXEC.
         ..
      *---------------------------------------------------------------*
      *    EXAMPLE WITH TERMID                                        *
      *---------------------------------------------------------------*
           MOVE 'DBOC OPEN=0001'   TO WORK-AREA-COMMAND.
           EXEC CICS START TRANSID('DBOC') TERMID('XXXX')
                FROM(WORK-AREA) LENGTH(80)  END-EXEC.
         ..

Note: If you have modified the DBOC or DBEC transaction ID (for example, through the GENOPTS screen) to some other value then the value you specify in the EXEC statement must reflect this new value.

EXEC CICS START TRANSID('xxxx')

CONSOLE Command (MVSlogmodify)

Use this method to issue a DBOC URT or MUF action command or a DBEC URT or MUF PERFORM command to the console for the CICS region. With this method, CA Datacom® CICS Services provides no return code or response. When CA Datacom® CICS Services processes the command, it writes any response to the Message Log file (DBOCPRT). DBEC in remote. For DBEC, in remote mode, this response is written to the CICS specified in the SYSID limiter of the command.

When using a console command, provide a data area containing the command in the same format as you would type on a terminal. The exception to this is DBOC CONNECT, DISCONNECT, and IMMEDIATE which must be in the following format. For more information about using console commands, see your system administrator.

Console Command Examples

 ----+----1----+----2----+----3----+----4----+----5 . . . +----8


 /DBDCCICS,DBOC CONNECT=01

  or

 /DBDCCICS,DBEC_P,CONNECT,MUF(1)

Was this helpful?

Please log in to post comments.