GTDOM% JSYS 765 Obtains information from the Domain Name System. RESTRICTIONS: Some functions require WHEEL or OPERATOR capability ACCEPTS IN AC1: flags ,, function code AC2: function-specific argument AC3: function-specific argument AC4: function-specific argument RETURNS +1: failure, error code in AC1 +2: success, function-specific data returned in AC's All functions take flags in LH(AC1); irrelevant flags are ignored. The somewhat scattered allocation of flags and function codes is to avoid conflicts with the GTHST% and ISI GTDOM% monitor calls. GTDOM% Flag Bits Bit Symbol Meaning 0 GD%LDO Local Data Only. Use of this flag prevents the resolver from generating any network traffic on behalf of this query. 1 GD%MBA Must Be Authoritative. Don't use local cache; if resolve is necessary, try real hard to get authoritative data. 6 GD%RBK Resolve in BacKground. Ask resolver to work on this query, but returns immediately with a a GTDX4 error. 12 GD%EMO Exact Match Only. Prevents the resolver from using the search path mechanism. The same effect can be achived by suffixing the query name with a dot. This flag is provided for applications that know they don't want to DWIM a particular name. 13 GD%RAI Raise letters in output names. Frill. 14 GD%QCL QCLASS specified. If this is off, the QCLASS is assumed to be Internet. Some functions (eg, .GTDRR) may require a QCLASS, in which case this bit is ignored. 16 GD%STA Return status code instead of error for certain kinds of errors. Some of the GTDOM% errors indicate that names are invalid or even that a question cannot be definitely answered at the present time. GD%STA causes these errors (as distinguished from errors indicating bad arguments to the GTDOM% call) should be signaled by a +2 return and a status code in AC1. At present, these status codes and their mapping from error codes are as follows: .GTDX0 Total success .GTDXN Data does not exist (GTDX2,GTDX3) .GTDXT Timeout while processing query (GTDX4) .GTDXF Domain namespace is corrupt (GTDX7,GTDX10) Several IPCF errors that indicate transitory conditions or simply the lack of a resolver process are also handled as .GTDXT status, primarily so that MMAILR and friends won't bounce mail due to a temporary glitch. GD%STA has no effect on processing of any other error that may occur during a GTDOM% call. The intent is to distinguish between caused by bad programming and errors caused by events beyond the programmer's control. The following GTDOM% functions are supported. Code Symbol Function 0 .GTHSZ Returns local host number and a couple of zeros to keep old programs (that are used to GTHST%) happy. User-supplied arguments: AC2: QCLASS, if GD%QCL is on in AC1 Returned data: AC2: 0 AC3: 0 AC4: local host number 2 .GTHNS Returns the primary name for the given IP host number. Lookup is done via the IN-ADDR.ARPA PTR tree for class IN, or the equivalent for other classes. Note that a host address of 0 or -1 means "local host", so the return value in AC3 isn't a no-op. (This was an undocumented feature of GTHST%.) User-supplied arguments: AC2: destination designator AC3: host number AC4: QCLASS, if GD%QCL is on in AC1 Returned data: AC2: updated destination designator AC3: host number AC4: host status (if available) 3 .GTHSN Translates the specified host name string to its host number. If the name specified is a nickname, HS%NCK will be on in the status word. User-supplied arguments: AC2: source designator AC3: QCLASS, if GD%QCL is on in AC1 Returned data: AC2: updated source designator AC3: host number AC4: host status (if available) 12 .GTDWT Resolver dismiss function. Not available to user programs. 14 .GTDPN Get primary name and IP address. Like .GTHSN except returns canonicalized hostname instead of host status bits. User-supplied arguments: AC2: source designator AC3: QCLASS, if GD%QCL is on in AC1 AC4: destination designator Returned data: AC2: updated source designator AC3: host number AC4: updated destination designator 15 .GTDMX Get MX (Mail Exchange) data. See argument block format description below. Query type is ignored (only MX makes sense here). Query class is assumed to be Internet unless GD%QCL is on in AC1. User-supplied arguments: AC2: source designator AC3: destination byte pointer AC4: pointer to argument block Returned data: AC2: updated source designator AC3: updated byte pointer argument block updated 16 .GTDAA Authenticate Address. Checks to see if an address is among those associated with the specified name. This is the right way to validate the hostname associated with an open network connection. The call will return +2 iff the address matches the hostname. To see if a particular name is a valid name for the local machine, use an "address" of -1 in AC3. User-supplied arguments: AC2: source designator AC3: (numeric) network address AC4: QCLASS, if GD%QCL is on in AC1 Returned data: AC2: updated source designator 17 .GTDRR Get an arbitrary Resource Record from the database, in a somewhat parsed format. See specification of argument block, below. GD%QCL is ignored for this function, QCLASS and QTYPE must be specified in the call. Quantities which fit cleanly into a 36 bit word (16 and 32 bit numeric quantities, mostly) will be returned as one word in the argument block, strings will be written into string space and a pointer to the string will be placed in the argument block. This corresponds to the internal format of the messages which pass between the monitor and the resolver. This function is not yet implemented. User-supplied arguments: AC2: source designator AC3: destination byte pointer AC4: pointer to argument block Returned data: AC2: updated source designator AC3: updated byte pointer argument block updated 20 .GTDVN Validate Name. Checks to see if a name has RRs matching either a particular QTYPE or a list of QTYPEs known to GTDOM% to represent a particular kind of object such as a host or a zone. The call will return +2 iff (one of) the QTYPE(s) is found for the given name. The canonical name is returned. This is the right way to determine whether a particular name denotes a host (eg, for mail purposes, since a host can be a legitimate maildrop known to the domain system without having an IP address). User-supplied arguments: AC2: source designator AC3: LH: QCLASS (if GD%QCL is on in AC1) RH: QTYPE or special token; special tokens currently implemnented: .GTDVH: A host (A,MX,HINFO) .GTDVZ: A zone (SOA,NS) AC4: destination designator for canonical name Returned data: AC2: updated source designator AC3: QCLASS,,QTYPE pair that matched AC4: updated destination designator 21 .GTDLA Local Address. Given a foreign IP address, returns the local machine's IP address most suitable for sending an IP datagram to the specified remote host. This is primarily of interest to programmers writing UDP code that must work on a multi-homed host (eg, the CHIVES resolver itself). This function does not require the resolver to be running, as it obtains all the information it needs from the monitor's IP routing tables. In theory this function is available for QCLASSes other than Internet, in practice the code to do this has not been written. User-supplied arguments: AC2: foreign host address AC3: QCLASS (if GD%QCL is on in AC1) Returned data: AC2: local host address 22 .GTDSA Sort Addresses. Sorts a list of network addresses in decending order by desirability (ie, the address corresponding to the "best" path will be first). Addresses that are known to the routing code to be completely inaccessable will be removed from the list. This function is primarily of interest to the resolver itself, which uses it to sort IP address of foreign name servers. This function does not require the resolver to be available. User-supplied arguments: AC2: 30-bit address of block of network addresses AC3: count of addresses in block AC4: QCLASS (if GD%QCL is on in AC1) Returned data: AC2: pointer to update block of addresses AC3: updated count 23 .GTDOS Get Operating System string. Looks for a HINFO RR (Host Information) and extracts the operating system name string. Does not attempt to translate the string into one of the old GTHST% operating system .HSxxx codes, the code assignments are somewhat dated and it's easy enough to do this translation with a TBLUK% table if desired. This function is provided primarily for use by the client FTP program, which wants to know what defaults to set for transfer mode and the like when talking to a particular foreign host. User-supplied arguments: AC2: source pointer to target host name AC3: destination pointer for opsys name AC4: QCLASS (if GD%QCL is on in AC1) Returned data: AC2: updated source pointer AC3: destination pointer The format of the argument block for .GTDMX and .GTDRR is as follows: Word Meaning 0 .GTDLN Length of argument block, in words (inclusive). The minimum length is .GTDML (currently 5). On return this word contains a count of the number of words of argument block actually used. 1 .GTDTC LH: Query type (ignored if not relevant) RH: Query class 2 .GTDBC Length of the output buffer pointed to by AC3. Updated on return, like SOUT%. 3 .GTDNM Pointer to canonicalized name (returned) 4+ .GTDRD Returned data (words and byte pointers) begins here. In the case of .GTDMX, all data items will be byte pointers into the output string buffer, with the "best" relay name first, the next best second, etctera. For .GTDRR the exact format has not yet been determined, but it will closely resemble the format used internally by the resolver, which in turn resembles the standard network packet layout minus the string compression and byte packing tweaks. GTDOM% ERROR MNEMONICS: GTDX1: Bad syntax in input domain name GTDX2: Referenced domain name does not exist GTDX3: Requested data not present at name GTDX4: Requested data not available GTDX5: Bad output specification GTDX6: Domain system internal error GTDX7: Received data is inconsistant GTDX8: Result string too long GTDX9: Source string too long GTDX10: Too many CNAMEs found while processing query GTDX11: Argument block changed while call in progress GTDX12: Bad QCLASS GTDX13: Bad host address GTDX14: Bad QTYPE ARGX02: Invalid function ARGX04: Argument block too small ARGX22: Invalid flags ARGX28: Not available on this system ILLX01: Illegal memory read ILLX02: Illegal memory write Any IPCF error may occur while contacting resolver Any BIN% (BOUT%) error may occur while reading (writing) argument (result) See description of the GD%STA flag, which can cause some errors to be translated to a non-error status code.