Update DNS API (QTOBUPDT)

  Required Parameter Group:

1 Update instructions Input Char(*)
2 Length of update instructions Input Binary(4)
3 Format name of update instructions Input Char(8)
4 Update key override Input Char(*)
5 Length of update key override Input Binary(4)
6 Format name of update key override Input Char(8)
7 Update key name Input Char(*)
8 Length of update key name Input Binary(4)
9 IP address of DNS server Input Char(*)
10 Miscellaneous attributes Input Char(*)
11 Length of miscellaneous attributes Input Binary(4)
12 Format name of miscellaneous attributes Input Char(8)
13 Result code Output Binary(4)
14 Error code I/O Char(*)

  Optional Parameter Group:

15 DNS server IP address type Input Char(10)

  Program Name: QDNS/QTOBUPDT

  Default Public Authority: *USE

  Threadsafe: Yes

The Update DNS (QTOBUPDT) API allows the caller to send one or more update instructions to a dynamic Domain Name System (DNS) server. The instructions allow for adding or deleting DNS Resource Records (RRs). The instructions can optionally include any number of prerequisite conditions that must be true for the actual updates to take place. This API is based on the Berkeley Internet Name Domain (BIND) version 9.4.0 implementation of dynamic DNS updates. Therefore, it also can be used to send update requests to DNS servers running on other operating system platforms that conform to BIND Version 9 update protocols.

IBM® i option 31 (Domain Name System) must be installed to use this API.


Authorities and Locks

If an Integrated File System (IFS) stream file name is specified for any of the parameters that allow it, then the user will need *R authority to the stream file and *X authority to the directories in the path of the stream file.


Required Parameter Group

Update instructions
INPUT; CHAR(*)

One or more instructions that define which DNS resource records should be updated (added or deleted) for a specific DNS domain, as well as any prerequistes that must be true for those updates to take place. Depending on which format name for this parameter is chosen, this parameter will either contain the actual update instructions themselves or the name of an Integrated File System file that contains the update instructions.

The syntax for the update instructions themselves is the same as that defined by BIND 9.4.0 for dynamic DNS updates, which it uses as input to its nsupdate program. Please see Update Instructions Syntax for descriptions of the update instructions themselves.

Length of update instructions
INPUT; BINARY(4)

The length of the data passed in the Update instructions parameter. If the length is larger than the size of the Update instructions parameter, the results may not be predictable.

Format name of update instructions
INPUT; CHAR(8)

The format of the data being passed in the Update instructions parameter.

DNSU0100 Data passed represents the actual data the API should use.
DNSU0200 Data passed represents the path name of an Integrated File System file that contains the data the API should use.
DNSU0300 Data passed represents the name of a file that contains the data the API should use. The file name is in an IBM i API path name structure. For the format of this structure, see Path name format.

Update key override
INPUT; CHAR(*)

This API automatically searches the default DNS dynamic update directory /QIBM/UserData/OS400/DNS/_DYN for a dynamic update transaction signature (TSIG) key for the specific domain being updated. The caller can override the default logic and provide a transaction signature key directly to the API by using this Update key override parameter. Depending on which format name for this parameter is chosen, this parameter will either contain the actual key itself or the path name of an Integrated File System file that contains the key.

Length of update key override
INPUT; BINARY(4)

The length of the data passed in the Update key override parameter. If the length is larger than the size of the Update key override parameter, the results may not be predictable.

Format name of update key override
INPUT; CHAR(8)

The format of the data being passed in the Update key override parameter.

DNSU0100 Data passed represents the actual data the API should use.
DNSU0200 Data passed represents the path name of an Integrated File System (IFS) file that contains the data the API should use.
DNSU0300 Data passed represents the name of a file that contains the data the API should use. The file name is in an IBM i API path name structure. For the format of this structure, see Path name format.

Update key name
INPUT; CHAR(*)

If the caller is providing a transaction signature key in the update key override parameter, then the update key name parameter must contain the name of the update key.

Length of update key name
INPUT; BINARY(4)

The length of the data passed in the Update key name parameter. If the length is larger than the size of the Update key name parameter, the results may not be predictable.

IP address of DNS server
INPUT; CHAR(*)

The IP address in dotted decimal form (for IPv4) or colon delimited form (for IPv6), of the DNS server where the API should start searching for the primary master DNS server for the zone being updated.

If DNS server IP address type is *IPV4, then this is a Char(15) and is a left adjusted, right padded with blanks, dotted decimal form address. If DNS server IP address type is *IPV6, then this is a Char(46) and is a left adjusted, right padded with blanks, colon delimited form address.

If this parameter is all blanks on input, the API will automatically search the network to determine where the primary master DNS server is located for the zone that contains the domain being updated. The DNS server IP address type must also be blank (if passed).

Miscellaneous attributes
INPUT; CHAR(*)

Optional miscellaneous runtime attributes.

Length of miscellaneous attributes
INPUT; BINARY(4)

The length of the data passed in the Miscellaneous attributes parameter. If the length is larger than the size of the Miscellaneous attributes parameter, the results may not be predictable.

Format name of miscellaneous attributes
INPUT; CHAR(8)

The format of the data being passed in the Miscellaneous attributes parameter.

DNSA0100 Miscellaneous runtime attributes. Refer to DNSA0100 Format for details on the format.

Result code
OUTPUT; BINARY(4)

Whether the API processed successfully or not, and if not, what type of problem was encountered. Any code that is not 0 means that the updates were not completely successful.

0 Successful.
1 Send error. The authoritative name server could not be reached.
2 Failed update packet. The name server has rejected the update, either because it does not support dynamic update or due to an authentication failure.
3 Prerequisite failure. The update was successfully received and authenticated by the name server. The prerequisites, however, prevented the update from actually being performed.

Error code
I/O; CHAR(*)

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

DNS server IP address type
INPUT; CHAR(10)

This parameter takes two special values -- *IPV4 which means the IP address of DNS server is a Char(15) or *IPV6 which means the IP address of DNS server is a Char(46). The default if this parameter is not passed is *IPV4.

If this parameter is all blanks on input, the API will assume *IPV4 for the value.


Update Instructions Syntax

The syntax of the update instructions for the QTOBUPDT API is the same as the syntax of the update instructions that are input to the BIND (Berkeley Internet Name Domain) Version 9.4.0 program known as nsupdate. It is a stream file-based input format that requires carriage-return(<cr>) linefeed (<lf>) characters to define distinct "lines" of input.

In addition to accepting these instructions using stream files, like nsupdate, the QTOBUPDT API has added the ability (by specifying format DNSU0100) for an application program to build the lines of input in memory and pass them directly to the API without first having to write them to a file. It is important to note, however, that this method still requires that you build the input lines exactly as you would if you were going to write them to a stream file; that is, separated by the same <cr><lf> characters that are described below.

QTOBUPDT reads input records, one per line, each line contributing a resource record directive to a single update request. As described below, the directives can be either prerequisite checks or actual resource record (RR) data update directives. All domain names used in an update request must belong to the same DNS zone. A blank line causes the accumulated records to be formatted into a single update request and transmitted to the zone's authoritative name servers. Additional records may follow, which are formed into additional, completely independent, update requests for that domain. For any given call to the API, multiple update requests can be made, but each group of lines belonging to each single update request must be separated by a blank line. For the last request to be transmitted, you must remember to include a blank line as the last line of your input.

Records take one of two general forms. Prerequisite records specify conditions that must be satisfied before the request will be processed. Update records specify actual data changes to be made to the DNS database. An "update request" consists of zero or more prerequisites, and one or more updates. Each update request is processed atomically; that is, all prerequisites must be satisfied, then all updates are performed. If any of the prerequisites within the specific update request fail, the actual data update directives following them will not be attempted.

QTOBUPDT API understands the following input record formats:

prereq nxdomain domain-name <cr><lf> Requires that no RR of any type exists with name domain-name.
prereq yxdomain domain-name <cr><lf> Requires that at least one RR named domain-name must exist.
prereq nxrrset domain-name [class] type <cr><lf> Requires that no RR exists of the specified type and domain-name.
prereq yxrrset domain-name [class] type [data...] <cr><lf> Requires that a RR exists of the specified type and domain-name. If data is specified, it must match exactly.
update delete domain-name [class] [type [data...]] <cr><lf> Deletes RRs named domain-name. If type and/or data is specified, only completely matching records are deleted.
update add domain-name ttl [class] type data... <cr><lf> Adds a new RR with specified ttl, type, and data.

EXAMPLES

  1. The following example illustrates a set of update instructions that could be sent to the QTOBUPDT API to change an IP address by deleting any existing A records for a domain name, and then inserting a new A record. Since no prerequisites are specified, the new record will be added even if there were no existing records to delete. The trailing blank line is required to process the request.


  2. In this example, a CNAME alias is added to the database only if there are no existing A or CNAME records for the domain name.


  3. To accomplish both of the above independent update requests in a single call to the QTOBUPDT API, the update instructions submitted would be:


DNSA0100 Format

The following is the format used for passing miscellaneous runtime attributes to the dynamic DNS update API. For detailed descriptions of the fields in this table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 BINARY(4) Debug flag
4 4 BINARY(4) Virtual circuit flag
8 8 CHAR(1) Reserved for future use


Field Descriptions

Debug flag. If set on, tells the API to create a spooled print file (QPRINT) to the caller's userid.

0 Debug tracing is off (default).
1 Debug tracing is on.

Reserved for future use. A reserved field that must be set to hexadecimal zeros.

Virtual circuit flag. If set on, tells the API to use a TCP connection instead of the default UDP packets.

0 Use UDP packets to communicate with the DNS server (default).
1 Use TCP to communicate with the DNS server.


Error Messages

Message ID Error Message Text
DNS0300 E Incorrect number of parameters passed.
DNS0301 E The update instructions parameter was null.
DNS0302 E The length of the update instructions parameter is incorrect.
DNS0303 E The format name of the update instructions parameter is incorrect.
DNS0304 E The update key override parameter is null.
DNS0305 E The format name of the update key override parameter is incorrect.
DNS0306 E The IP address of the DNS server parameter is incorrect.
DNS0307 E The miscellaneous attributes parameter is null.
DNS0308 E The format name of the miscellaneous attributes parameter is incorrect.
DNS0309 E The transaction signature key file could not be opened.
DNS0310 E The length of miscellaneous attributes parameter is incorrect.
DNS0311 E The miscellaneous attributes debug flag is incorrect.
DNS0312 E The miscellaneous attributes virtual circuit flag is incorrect.
DNS0313 E The key name parameter is null.
DNS0314 E The length of the key name parameter is incorrect.
DNS0315 E The transaction signature key file could not be read.
DNS0316 E The update instructions file could not be read.
DNS0317 E The format name of the server address type is incorrect.
DNS030A E The update instructions parameter was incorrect.
DNS030B E The dynamic DNS update failed.
DNS030C E The dynamic DNS update partially failed.
DNS030D E The miscellaneous attributes reserved field was not zeros.
DNS030E E The length of the update key override parameter is incorrect.
DNS030F E The update instructions file could not be opened.

API introduced: V5R1

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