Understanding tokens

For example, when you use the IMFEXEC HMC CONNECT command to connect to a CPC, a token representing this CPC is the output. Then, using the CPC token, you can use IMFEXEC HMC CONNECT to obtain a new token for an object within the CPC such as LPAR1 or Load-Activation-Profile1, and so on. You can use IMFEXEC HMC CONNECT to connect to many objects within the CPC concurrently. See Examples-for-the-IMFEXEC-HMC-command for an example showing the usage of tokens when connecting to an Image (LPAR).

Some commands such as LIST CPCs, LIST LocalCPC, and LIST LocalImages do not require a connection token. Other commands require a specific type of object such as a CPC connection token or an Image connection token.  

The connection tokens are valid only within the same EXEC thread. Each EXEC thread needs to issue IMFEXEC HMC CONNECT to get its own token. Issue IMFEXEC HMC DISCONNECT to release a token when it is no longer needed. In addition, the EXEC should release all tokens before ending the EXEC thread.

The results of List and Query are returned as REXX stem variables where LINE.0 contained the number of result lines (LINE.nnn) that were returned. See the EXECs in the Examples-for-the-IMFEXEC-HMC-command to see how the LINE.nnn variables are used.

If an error occurs, the IMFEXEC HMC return code is in IMFCC. If there is an accompanying BCPii return code, this code is returned in IMFRC (in decimal format) and also shown in the EM1510I message. If there is text from BCPii describing the error, it is displayed in the accompanying message EM1500E; for example:

The EM1500E message is not displayed when BCPii does not provide any error text.

The BCPii return code aaaa is displayed in hexadecimal. The explanation for aaaa is located in the IBM documentation MVS Programming: Callable Services for High-Level Languages. For example, if IMFEXEC HMC CONNECT has return code aaaa = 00000F00, look up return code 00000F00 for the HWICONN macro in the IBM documentation. Cross reference for IMFEXEC HMC commands and BCPii macros shows which macros correspond with the IMFEXEC HMC commands.

The next five hexadecimal error codes (bbbb, cccc, dddd, eeee, ffff) are the 5 words from the BCPii diagnostic area.

The following example shows an error code F02 where the Support Element was incorrectly configured with Access Type=Read. (Tt should have been configured with both Read and Write.) BCPii provided the additional text 'COMMNAMEINV' to further describe the error code.