Accessing the API environment

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

Note:
For instructions on installing the REXX function package, see CICS® Transaction Server for z/OS® Installation Guide.

The REXX run-time interface consists of a single load module containing two entry points:

EYU9AR00
The function package
EYU9AR01
The host subcommand

The function package contains these functions:

EYUAPI()
Passes an API command to CICSPlex SM.
EYUINIT()
Initializes the CICSPlex SM API environment and allocates the necessary REXX resources.
EYUREAS()
Translates the value returned by the REASON option of an API command.
EYURESP()
Translates the value returned by the RESPONSE option of an API command.
EYUTERM()
Terminates the CICSPlex SM API environment and releases any allocated REXX resources.

For complete descriptions of these functions, see CICSPlex System Manager Application Programming Reference.

In general, you access the CICSPlex SM API environment through the supplied 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.

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:

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 actually 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.

[[ Contents Previous Page | Next Page Index ]]