ILE C/C++ Programmer's Guide

Using the Transfer Control (TFRCTL) Command

You can run an application from within a CL program that transfers control to your program using the Transfer Control (TFRCTL) command. This command:

  1. Transfers control to the program specified on the command.
  2. Removes the transferring CL program from the call stack.

In the following example, the TFRCTL command in a CL program RUNCP calls a C++ program XRUN2, which is specified on the TFRCTL command. RUNCP transfers control to XRUN2. The transferring program RUNCP is removed from the call stack.

Figure 28 illustrates the call to the CL program RUNCP, and the transfer of control to the C++ program XRUN2.

Figure 28. Calling Program XRUN2 Using the TFRCTL Command



runcp1

Example: Creating and Running a Program that Uses the TFRCTL Command

To create and run programs RUNCP and XRUN2, follow the steps below:

  1. Create the source file QCLSRC and enter the source code shown in Figure 29.
  2. Create the CL program RUNCP. From the command line, enter:
    CRTCLPGM PGM(MYLIB/RUNCP) SRCFILE(MYLIB/QCLSRC)
    
  3. T create program XRUN2 in library MYLIB from source file xrun2.cpp (shown in Figure 30), enter:
    CRTBNDCPP PGM(MYLIB/XRUN2) SRCSTMF(xrun2.cpp)
    
  4. Run program RUNCP from a command line, passing it the string "nails", with the command:
    CALL PGM(MYLIB/RUNCP) PARM('nails')
    

    The output from program XRUN2 is:

    +--------------------------------------------------------------------------------+
    |      string = nails                                                            |
    |      Press ENTER to end terminal session.                                      |
    |                                                                                |
    +--------------------------------------------------------------------------------+

Code Samples

Figure 29. Example of Source Code that Transfers Control to Another Program



/* Source for CL Program RUNCP */
PGM PARM(&STRING)
DCL VAR(&STRING) TYPE(*CHAR) LEN(20)
DCL VAR(&NULL) TYPE(*CHAR) LEN(1) VALUE(X'00')

/* ADD NULL TERMINATOR FOR THE ILE C++ PROGRAM */
CHGVAR VAR(&STRING) VALUE(&STRING *TCAT &NULL)
TFRCTL PGM(MYLIB/XRUN2) PARM(&STRING)

/* THE DSPJOBLOG COMMAND IS NOT CARRIED OUT SINCE */
/* WHEN PROGRAM XRRUN2 RETURNS, IT DOES NOT RETURN TO THIS */
/* CL PROGRAM. */
DSPJOBLOG
ENDPGM
Note:
In the example Example: Creating and Running a Program that Uses the TFRCTL Command, program RUNCP uses the TFRCTL command to pass control to the ILE C++ program XRUN2, which does not return control to RUNCP.

Figure 30. Example of Source Code that Receives and Prints a Null-Terminated Character String


// xrun2.cpp
// Source for Program XRUN2
// Receives and prints a null-terminated character string
 
#include <iostream.h>
 
int main(int argc, char *argv[])
{
   int    i;
   char * string;
   string = argv[1];
   cout << "string = " <<  string << endl;
}
Note:
In the example Example: Creating and Running a Program that Uses the TFRCTL Command, program XRUN2 receives a null-terminated character string from the CL program and prints the string.


[ Top of Page | Previous Page | Next Page | Table of Contents ]