Passing Program Control

DC provides program management facilities that allow you to pass control either between programs in a single task thread or from task to task. Using these program management functions, you can:

idmscu19

DC provides program management facilities that allow you to pass control either between programs in a single task thread or from task to task. Using these program management functions, you can:

Return control to the next-higher level within a task, optionally specifying the next task to be invoked on the same terminal

Initiate execution of a program on the same level within a task; control cannot return to the calling program

Initiate execution of a subordinate-level program within the same task, with the expectation that control will return to the instruction immediately following the request

This article describes the following information:

Levels of Program Control

The figure below shows levels of programs in a task. TASKA invokes Program A, which calls Program B expecting return of control. Program B passes control laterally to Program C, which then returns control to Program A. When Program A is finished, it returns control to DC specifying that TASKX should be the next task invoked on that logical terminal.


                               Next task code 'TASKX'
                            ┌─ - - - - - - - - - - - - - - - - ─┐

                            │                                   │
           DC
───────────┬────────────────▲───────────────────────────────────┼──────────────
           │   TASKA        │                                   │   TASKX
           │                                                    │
           │                │                                   │
           │                                                    │
  ┌────────▼───────┐        │                           ┌───────▼───────┐
  │                │                                    │               │
  │   Program A    │        │                           │  Program D    │
  │   (level 1)    │                                    │               │
  │                ◄────────┼──────────┐                │               │
  │                │        │          │                │               │
  │                │                   │                │               │
  └────────┬────┬──┘        │          │                └───────────────┘
           │                           │
           │    │           │          │
           │                           │
           │    └─ - - - - ─┘          │
           │                           │
  ┌────────▼───────┐           ┌───────┴───────┐
  │                │           │               │
  │   Program B    │           │  Program C    │
  │   (level 2)    │           │  (level 2)    │
  │                ├───────────►               │
  │                │           │               │
  │                │           │               │
  └────────────────┘           └───────────────┘

Returning to a Higher-level Program

You can return control to a higher level within a task or to DC. If you return control to DC and specify the next task code to be invoked, the task ends and a pseudoconverse begins.

DC RETURN Statement

To return control to the next-higher level in a task, issue a DC RETURN statement, optionally specifying the next task code to be invoked on the terminal.

If the next-higher-level program specifies a next task code, it overrides any task code specified by the subordinate program. If the issuing program is the highest-level program, DC regains control.

You can bypass intervening link levels and return control to DC by issuing a DC RETURN IMMEDIATE statement.

When the Next Task is Invoked

DC invokes the next task differently depending on how it is defined to the DC system:

If the next task is defined with the INPUT
attribute, it is executed when the user next presses an AID key.

If the next task is defined with the NOINPUT
attribute, it is executed immediately.

Example of Return Specifying Next Task

The program excerpt below returns control to DC and specifies the next task code to be invoked on that terminal.

The first DC RETURN statement returns control to DC. The second DC RETURN statement also specifies that DEPTDISM is the next task invoked on that terminal.


 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  DEPTDISM                   PIC X(8)  VALUE 'DEPTDISM'.
 01  SOLICIT-REC.
     05  SOLICIT-DEPT-ID        PIC X(4).
 PROCEDURE DIVISION.
*** ESTABLISH ADDRESSABILITY TO THE MAP AND MAP RECORD ***
     BIND MAP SOLICIT.
     BIND MAP SOLICIT RECORD SOLICIT-REC.
*** CHECK THE AID BYTE ***
     INQUIRE MAP SOLICIT MOVE AID TO DC-AID-IND-V.
*** RETURN CONTROL TO CA IDMS/DC IF OPERATOR HAS PRESSED CLEAR ***
     IF CLEAR-HIT
     DC RETURN.
        MOVE ZERO TO SOLICIT-DEPT-ID.
*** TRANSMIT THE MAP TO THE TERMINAL SCREEN ***
     MAP OUT USING SOLICIT
        NEWPAGE
        MESSAGE IS INITIAL-MESSAGE LENGTH 80.
*** RETURN CONTROL TO CA IDMS/DC AND SPECIFY THE NEXT TASK ***
     DC RETURN
     NEXT TASK CODE DEPTDISM.

Passing Control Laterally

After DC gives control to the program specified by an initial task code, that program can transfer control to other DC programs on the same level. That is, the issuing program does not expect return of control.

Steps to Transfer Control

To transfer control laterally, perform the following steps:

Invoke the main program specified by the task code.

Perform processing, as required.

Acquire storage for any parameters to be passed.

Transfer control to the second program by issuing a TRANSFER CONTROL XCTL statement, optionally specifying a parameter list.

Because control is transferred, there is no need to perform the IDMS-STATUS routine.

'COBOL programmers'. If you specify a parameter list, the specified data items must be defined in the LINKAGE SECTION of both the calling and the receiving programs.

'PL/I programmers'. If you specify a parameter list, the specified data items must be defined as based storage in both the calling and the receiving programs.

Example of Transferring Control Laterally

The program excerpt below shows a TRANSFER CONTROL request that includes a parameter list containing database retrieval information.

The ERRCHEK program performs error checking and passes control to the GETPROG program, which performs the database access.


 PROGRAM-ID.                     ERRCHEK.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  GETPROG                    PIC X(8) VALUE 'GETPROG'.
 LINKAGE SECTION.
 01  PASS-DEPT-INFO.
     05 PASS-DEPT-ID            PIC 9(4).
     05 PASS-DEPT-INFO-END      PIC X.
 PROCEDURE DIVISION.
     BIND MAP SOLICIT.
     BIND MAP SOLICIT RECORD SOLICIT-REC.
     MAP IN USING SOLICIT.
*** PERFORM ERROR CHECKING ***
     IF SOLICIT-DEPT-ID NOT NUMERIC
        THEN GO TO SOLICIT-ERROR.
*** ACQUIRE STORAGE FOR DEPT-ID TO BE PASSED ***
     GET STORAGE FOR PASS-DEPT-INFO TO PASS-DEPT-INFO-END
        WAIT LONG USER KEEP STGID 'PDIN'
        ON DC-NEW-STORAGE NEXT SENTENCE.
     MOVE SOLICIT-DEPT-ID TO PASS-DEPT-ID.
*** TRANSFER CONTROL TO DATABASE ACCESS PROGRAM ***
     TRANSFER CONTROL TO GETPROG XCTL
     USING PASS-DEPT-INFO.
______________________________________________________________________________
 
 PROGRAM-ID.                     GETPROG.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  GETPROG                    PIC X(8) VALUE 'GETPROG'.
 LINKAGE SECTION.
 01  P-DEPT-INFO.
     05 P-DEPT-ID               PIC 9(4).
     05 P-DEPT-INFO-END         PIC X.
PROCEDURE DIVISION USING P-DEPT-INFO.
 COPY IDMS SUBSCHEMA-BINDS.
     READY.
     MOVE P-DEPT-ID TO DEPT-ID-0410.
*** OBTAIN DEPARTMENT USING PASSED DEPT-ID ***
     OBTAIN DEPARTMENT CALC
        ON DB-REC-NOT-FOUND
        PERFORM ERR-NO-DEPT.
          .
*** FURTHER DATABASE PROCESSING ***

Passing Control, Expecting to Return

To transfer program control to a subordinate level, expecting return of control to the instruction immediately following the request, perform the following steps:

Invoke the main program specified by the task code.

Perform processing, as required.

Transfer control to the second program by issuing a TRANSFER CONTROL LINK statement, optionally specifying a parameter list.

Perform processing in the subordinate-level program, as required. DC returns control to the next-higher-level program when the subordinate program issues a DC RETURN statement.

Example of Passing Control to a Lower Level

The program excerpt below transfers control to DEPTCHEK, a subroutine that performs error-checking.

The GETPROG program performs processing based on the status returned by the DEPTCHEK program.


 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01  DEPTCHEK                   PIC X(8) VALUE 'DEPTCHEK'.
 01  ERRCHEK-INFO.
     05 CHEK-DEPT-ID            PIC 9(4).
     05 CHEK-ERRSTAT            PIC X(4).
 PROCEDURE DIVISION.
     BIND MAP SOLICIT.
     BIND MAP SOLICIT RECORD SOLICIT-REC.
     MAP IN USING SOLICIT.
     MOVE SOLICIT-DEPT-ID TO CHEK-DEPT-ID.
     MOVE 'OK' TO CHEK-ERRSTAT.
*** TRANSFER CONTROL TO ERROR CHECKING PROGRAM ***
     TRANSFER CONTROL TO DEPTCHEK LINK USING
     CHEK-DEPT-ID
     CHEK-ERRSTAT.
     IF CHEK-ERRSTAT NOT = 'OK'
        GO TO ERR-DEPT-ID.
     COPY IDMS SUBSCHEMA-BINDS.
     READY.
     MOVE SOLICIT-DEPT-ID TO DEPT-ID-0410.
     OBTAIN DEPARTMENT CALC
        ON DB-REC-NOT-FOUND
        PERFORM ERR-NO-DEPT.
*** FURTHER DATABASE PROCESSING ***
______________________________________________________________________________
 
 PROGRAM-ID.                     DEPTCHEK.
 DATA DIVISION.
 LINKAGE SECTION.
 01  CH-DEPT-INFO.
     05 CH-ID                   PIC 9(4).
     05 CH-ERRSTAT              PIC X(4).
PROCEDURE DIVISION USING CH-DEPT-INFO.
*** PERFORM ERROR AND RANGE CHECKING ***
     IF CH-ID NOT NUMERIC
        THEN MOVE 'NNUM' TO CH-ERRSTAT
     ELSE
       IF CH-ID > 8000 OR < 1000
          MOVE 'RANG' TO CH-ERRSTAT.
*** RETURN CONTROL TO CALLING PROGRAM ***
     DC RETURN.

DC Programming Techniques

CA IDMS Reference 19.0

Passing Program Control