Convert Interface ID (QtocCvtIfcID) API


  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8)
4 Interface request Input Char(*)
5 Interface request CCSID Input Binary(4)
6 Error Code I/O Char(*)

  Service Program Name: QTOCNETSTS

  Default Public Authority: *USE

  Threadsafe: Yes

The Convert Interface ID (QtocCvtIfcID) API retrieves the IP address of an interface when given the name or the name of an interface when given the IP address.


Authorities and Locks

None.


Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold.

Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the result may not be predictable. The minimum length is 8 bytes.

Format name
INPUT; CHAR(8)

The format of the information to be returned. The format names supported are:

NCII0100
Return the IP address associated with the name specified. Refer to NCII0100 Format for details on the format.
NCII0200
Return the name associated with the IPv4 address specified. Refer to NCII0200 Format for details on the format.
NCII0300
Return the name associated with the IPv6 address specified. Refer to NCII0300 Format for details on the format.
Interface request
Input; CHAR(*)

The alias name or interface IP address for the interface to retrieve the mapping for. When format NCII0100 is used, the Interface request parameter must be 50 characters long and the alias name must be passed in with this parameter. When format NCII0200 is used, the Interface request parameter must be 15 characters long. When format NCII0300 is used, the data must be specified:

Offset Type Field
Dec Hex
0 0 Char(45) Interface address
45 2D Char(3) Reserved
48 30 Char(10) Line description
58 3A Char(6) Reserved

Field Descriptions

Interface address.
The IP address of the interface that is associated with the specified name.
Line description.
The physical line the interface is associated with. This field must be set to all blanks when the interface is not a multi-cast interface.
Reserved.
A reserved field. It must be x'00'.
Interface request CCSID
Input; Binary(4)

The coded character set ID for the Interface request. To specify the job CCSID, this field should be set to 0. When using format NCII0200 or NCII0300, the CCSID is not applicable and must be set to 0.

Note: In V5R4, only the job CCSID is supported so this field must always be set to 0.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Format of Returned Interface Data


NCII0100 Format

Format NCII0100 returns the IP address of the named interface. For detailed descriptions of the fields in the table, see Field Descriptions

.
Offset Type Field
Dec Hex
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Char(45) Interface address
53 35 Char(3) Reserved
56 38 Char(10) Line Description
66 42 Char(6) Reserved


Field Descriptions

Bytes available.
The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned.
The number of bytes of data returned.
Interface address.
The IP address of the interface that is associated with the specified name.
Line description.
The physical line the interface is associated with. This field is set to all blanks when the interface is not a multi-cast interface.
Reserved.
An ignored field.

NCII0200 Format

Format NCII0200 returns the name for the interface specified by the IP address. For detailed descriptions of the fields in the table, see Field Descriptions

.
Offset Type Field
Dec Hex
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Char(50) Alias name
58 3A Char(6) Reserved
64 40 Binary(4) Alias name CCSID


Field Descriptions

Alias name.
The name that is defined for the interface.
Alias name CCSID.
The coded character set ID of the alias name.
Bytes available.
The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned.
The number of bytes of data returned.
Reserved.
An ignored field.

NCII0300 Format

Format NCII0300 returns returns the name for the interface specified by the IP address. For detailed descriptions of the fields in the table, see Field Descriptions

.
Offset Type Field
Dec Hex
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Char(50) Alias name
58 3A Char(6) Reserved
64 40 Binary(4) Alias name CCSID


Field Descriptions

Alias name.
The name that is defined for the interface.
Alias name CCSID.
The coded character set ID of the alias name.
Bytes available.
The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned.
The number of bytes of data returned.
Reserved.
An ignored field.

Error Messages

The following messages may be sent from this function:

Message ID Error Message Text
TCP266B TCP/IP interface not found.
TCP1901 Internet address &1 not valid.
TCP1902 Internet address &1 not valid.
TCP1908 Internet address &1 not valid.
TCP84C6 Internal operations error - RESULT &1 CC &2 RC &3 ERRNO &4.
CPF24B4 Severe error while addressing parameter list.
CPF3C19 Error occurred with receiver variable specified.
CPF3C1E Required parameter &1 omitted.
CPF3C21 Format name &1 is not valid.
CPF3C24 Length of the receiver variable is not valid.
CPF3C90 Literal value cannot be changed.
CPF3CF1 Error code parameter not valid.
CPF3CF2 Error(s) occurred during running of &1 API.
CPF8100 All CPF81xx messages could be returned. xx is from 01 to FF.
CPF9872 Program or service program &1 in library &2 ended. Reason code &3.


API introduced: V5R4

[ Back to top | Communications APIs | APIs by category ]