API Help

Entity Identifiers

While all entities in Central Administration have names, internally they are identified uniquely by an ID. This ID is 16 bytes in length and is comprised of binary data that is not generally human-readable. The identifier of any given entity will never be the same as any other identifier of any other entity. Since entity names can be changed at any time (a Template can be “renamed”, for example), these names are not suitable for long-term use in external databases; for this reason, the internal identifier should be used to unambiguously identify a specific entity. You will see these identifiers used in several of the Central Administration APIs described in this guide.

UCS2 character encoding

Some of the textual data in Central Administration are encoded in CCSID 1200, commonly known as UTF-16 or UCS2. These data use exactly 2 bytes for each character and as such are twice as long as regular character data. To prevent data loss resulting from character translations in delivering data from the APIs, this UCS2 data will be delivered to your application where you can decide if the possibility of data loss is significant.

In the API data layouts below, the notation UCS2(nn) Is used to indicate a nn-character UCS2 variable, which occupies (nn * 2) bytes.

ILE RPG supports the usage of UCS2 data via data type “C” and conversion via the %ucs2() and %char() built-in functions. Other languages may be able to use the iconv() API to perform character translations.

Error Messages returned from these APIs

Some of the APIs herein employ IBM APIs to accomplish their task, for example, when using user spaces in the list APIs. Some of the messages returned to your program may be IBM messages from QCPFMSG, or other messages from the Central Administration message file, PPLMSGF. When the message ID returned begins with CPF or MCH, QCPFMSG should be used if you intend to resend the error message. Otherwise, PPLMSGF should be used.

Network Configuration APIs

The information about systems contains connection state information. To produce reliable connection state information, the Central Administration Communication Server must be started using the PPLSTRMON command prior to executing these APIs. The APIs will run without the Communication Server running, but the connection state information returned will always be 2 (the indeterminate state).