Accessing the API environment

The REXX runtime interface does not require any translation of API commands. The commands are interpreted by a REXX function package that is supplied by CICSPlex® SM.

For instructions on installing the REXX function package, see Installing the REXX function package.

The first call to CICSPlex SM in your program must be an EYUINIT or EYUAPI function. EYUINIT is the primary means of initializing the API environment. However, if EYUINIT is not issued first, the EYUAPI function initializes the environment.

Note: Your program must be an EYUINIT or EYUAPI function. EYUINIT is the primary means of initializing the API environment. However, if EYUINIT is not issued first, the EYUAPI function initializes the environment.

For example, sample program EYU#API1, which is distributed in the CICSTS22.CPSM.SEYUSAMP library, begins like this:

  Say 'Initializing API...'
  XX = EYUINIT()
  If XX <> 0 Then Signal UNEXPECTED
  Say 'Establishing connection...'
  XX = EYUAPI('CONNECT' ,
              'CONTEXT('W_CONTEXT')' ,
              'SCOPE('W_SCOPE')' ,
              'VERSION(0310)' ,
              'THREAD(W_THREAD)' ,
              'RESPONSE(W_RESPONSE)' ,
              'REASON(W_REASON)')
  If XX <> 0 Then Signal UNEXPECTED

In this example, the EYUINIT function is issued first to initialize the API environment. Then an EYUAPI function is used to issue the API CONNECT command.

Once you have issued an EYUINIT or EYUAPI function, you can:

Issue any other CICSPlex SM function.
Access the host subcommand environment by issuing the REXX ADDRESS command.

Once the API environment is initialized, it exists until it is terminated, either by your program or by REXX. Therefore, the final call to CICSPlex SM in your program should always be an EYUTERM function. If you do not issue EYUTERM, some REXX resources, such as storage, may remain allocated and REXX becomes responsible for releasing them.

For example, sample program EYU#API1 ends like this:

  XX = EYUAPI('TERMINATE RESPONSE(W_RESPONSE) REASON(W_REASON)')
  XX = EYUTERM()

In this example, the EYUAPI function is used to issue an API TERMINATE command. Then EYUTERM is issued to terminate the API environment and release its allocated resources.

Using the EYUTERM function is always a good idea. However, if the CICSPlex SM host subcommand environment is installed at your enterprise (as opposed to being called from the function package), you may not need to use the EYUTERM function at the end of every program. Depending on the programming guidelines at your enterprise, the REXX resources that remain allocated can be reused by the next CICSPlex SM API program that accesses the host subcommand environment.