Change IPv4 Interface (QTOCC4IF) API
Required Parameter Group:
| 1 | Interface information | Input | Char(*) |
| 2 | Format name | Input | Char(8) |
| 3 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Change IPv4 Interface (QTOCC4IF) API is used to change selected parameters for an IPv4 interface that is defined in the system's TCP/IP configuration.
Authorities and Locks
- Special Authority
- The caller of this API must be running under a user profile that has input/output system configuration (*IOSYSCFG) special authority.
Required Parameter Group
- Interface Information
- INPUT; CHAR(*)
Contains the characteristics of the IPv4 interface being changed.
- Format name
- INPUT; CHAR(8)
The format of the interface information parameter. The format name supported is:
- IFCH0100
- Format for adding or changing an IPv4 interface parameter. For the format of the structure, see IFCH0100 Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure refer to Error code parameter.
IFCH0100 Format
For detailed descriptions of the fields in this table, see Field Descriptions.| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of fixed interface information |
| 4 | 4 | CHAR(15) | Internet address |
| 19 | 13 | CHAR(1) | Reserved |
| 20 | 14 | BINARY(4) | Proxy ARP allowed |
| 24 | 18 | BINARY(4) | Offset to preferred interface list |
| 28 | 1C | BINARY(4) | Number of entries in preferred interface list |
| 32 | 20 | BINARY(4) | Length of one preferred interface list entry |
| 36 | 24 | CHAR(24) | Interface name |
| This field repeats for each preferred interface list entry | CHAR(*) | Preferred interface list entry (See Format of Preferred Interface List Entry for more information.) | |
Format of Preferred Interface List Entry
The preferred interface list entry describes the data specified for each entry in the preferred interface list of the IFCH0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(15) | Preferred interface internet address |
| 15 | 0F | CHAR(1) | Reserved |
Field Descriptions
Interface name. Specifies a textual description of this interface. Up to 24 characters, padded with blanks, may be specified. A value of *SAME means that the interface name does not change.
Internet address. The IPv4 internet address, in dotted decimal notation, of an interface.
Length of fixed interface information. This field contains the number of bytes specified in the fixed portion of the interface information structure. The minimum value for this field is 24.
Length of one preferred interface list entry. The length of a preferred interface list entry. A value of zero means that the list will be removed. A value greater than zero means that the list will be replaced. A value of -1 means that the list does not change.
Number of entries in preferred interface list The number of entries in the preferred interface list. A value of zero means that the list will be removed. A value greater than zero means that the list will be replaced. A value of -1 means that the list does not change. The maximum value for this field is 10.
Offset to preferred interface list The offset from the start of the fixed interface information to the beginning of the preferred interface list. A value of zero or greater means that the list will be replaced. A value of -1 means that the list does not change.
Preferred interface internet address The internet address, in dotted decimal notation, of an interface in the preferred interface list. A special value of *DFTROUTE can be used to indicate that interface selection is to be performed dynamically based on the binding interface of the best active default IPv4 route on the system. To use the special value it must be the only value in the preferred interface list.
Preferred interface list entry. Specifies information about an interface in the preferred interface list. The order in which the list entries are specified is also the order in which the system uses the interfaces as Proxy Agents.
Proxy ARP allowed. This field applies to Opticonnect (*OPC) and Virtual Ethernet interfaces only. For those types of interfaces, this field indicates whether Proxy (Address Resolution Protocol) ARP has been configured to be allowed or not allowed.
| 0 | NO - Proxy ARP not allowed. |
| 1 | YES - Proxy ARP allowed. |
| -1 | The value does not change. |
Reserved. A reserved field. This field must be set to zero.
Usage Notes
Typically, if an error is detected during the change operation, a diagnostic message will be sent to the job log. This diagnostic message will contain details about the error. The API will then either signal the error message TCP2658 or return TCP2658 in the error code structure.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| TCP2658 E | &2 &1 not changed. |
| TCP923C E | &1 special authority is required. |
| TCP923F E | Value for parameter &2 for API &1 not valid. |
API introduced: V5R4