NETLIB_CLOSE closes a socket.

Format

NETLIB_CLOSE socket

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Socket to be closed.

---

DESCRIPTION

This routine deletes the specified socket, closing the associated network communications channel, if one is open. Once closed, the socket can no longer be used; you must open a new one with the NETLIB_SOCKET call.

---

NETLIB_CONNECT

NETLIB_CONNECT connects a socket to a remote address/port.

---

Format

NETLIB_CONNECT socket, socket-address, sockaddr-len [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Socket to be connected.

socket-address

VMS usage:	structure
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Socket_address structure describing the addreses and port to which the socket is to be connected.

sockaddr-len

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Size of the socket address structure.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine is used primarily with TCP-based programs to establish a connection to a remote system. When used with UDP, this routine fixes the address to which subsequent UDP datagrams will be sent.

---

NETLIB_CONNECT_BY_NAME

NETLIB_CONNECT_BY_NAME establishes a TCP connection to a host using the host's name, rather than its IP address.

---

Format

NETLIB_CONNECT_BY_NAME socket, hostname, port [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A STREAM-type socket allocated with NETLIB_SOCKET.

hostname

VMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

A character string containing either a host name or an IP address in dotted-decimal format.

port

VMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

The port number to connect to on the destination host. Unlike the SIN_W_PORT field of a SINDEF (socket address) structure, this number is specified in host order, not network order. NETLIB_CONNECT_BY_NAME will automatically convert the port number to network order for you.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine converts the specified name or dotted-decimal address to an IP address and uses NETLIB_CONNECT to connect to the specified host and port. If multiple addresses are returned by the host name lookup, each address will be tried until a connection is established or all addresses have been tried.

---

NETLIB_DNS_EXPANDNAME

NETLIB_DNS_EXPANDNAME is a utility routine used for extracting a domain name from a DNS response.

---

Format

NETLIB_DNS_EXPANDNAME bufstart, buflen, bufptr, name [,retlen] [,skipcount]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

bufstart

VMS usage:	pointer
type:	longword (unsigned)
access:	read only
mechanism:	by value

A pointer to the start of the DNS response buffer.

buflen

VMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

The size of the buffer, in bytes.

bufptr

VMS usage:	pointer
type:	longword (unsigned)
access:	read only
mechanism:	by value

A pointer to the area of the buffer containing the domain name to be expanded.

name

VMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

A descriptor for a character string buffer into which the expanded name will be written.

retlen

VMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

The returned length of the expanded name, in bytes.

skipcount

VMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

The number of bytes in the buffer that were used for the domain name.

---

DESCRIPTION

This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It expands a domain name stored in a DNS response out to the typical, human-readable, dotted-domain format.

This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses.

---

NETLIB_DNS_MX_LOOKUP

NETLIB_DNS_MX_LOOKUP looks up a host name, returning any MX records.

---

Format

NETLIB_DNS_MX_LOOKUP socket, hostname, mxrrlist, mxrrlist-size [,mxrrcount] [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usagbr> VMS usage: longword_unsigned «s ÐI0. access: read only mechanism: by reference Any socket allocated with NETLIB_SOCKET. hostname erence VMS usage: The actual number of MX records written to mxrrlist. iosb VMS usage: io_status_block type: longword (unsigned) access: write only mechanism: by reference I/O status block to receive the status for this call. astadr VMS usage: procedure type: longword (unsigned) access: call mechanism: by reference Address of an AST routine to be invoked on completion of this operation. astprm VMS usage: user_arg type: longword (unsigned) access: read only mechanism: by value Parameter to be passed to the AST routine. DESCRIPTION This routine performs a DNS lookup on the specified name, returning any Mail Exchanger (MX) records for that name. This routism:

by reference

The actual number of MX records written to mxrrlist.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine performs a DNS lookup on the specified name, returning any Mail Exchanger (MX) records for that name.

This routine is a front-end that uses NETLIB_DNS_QUERY to perform the DNS queries.

---

NETLIB_DNS_QUERY

NETLIB_DNS_QUERY formats a domain name service query and returns the response from a DNS server.

---

Format

NETLIB_DNS_QUERY socket, name, [class], type, buffer, bufsize [,flags] [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A socket allocated with NETLIB_SOCKET. Any socket can be used.

name

VMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

The domain name to be looked up.

class

_K_DNS_TYPE_SOA ݢ@

6	Start-of-Authority (SOA) records
mechanism:	by reference
mechanism:	by reference

The class of the query. For Internet domain names, this should be NETLIB_K_DNS_CLASS_IN, which is the default if this parameter is omitted.

type

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The type of query. Valid type codes are specified by Internet RFCs on the DNS, the codes provided by NETLIB are listed in Table RTN-1.

Table RTN-1 Domain Name Service query types

Symbolic name	Value	Description
NETLIB_K_DNS_TYPE_A	1	Address (A) records
NETLIB_K_DNS_TYPE_NS	2	Name Server (NS) records
NETLIB_K_DNS_TYPE_CNAME	5	Canonical Name (CNAME) records
NETLIB_K_DNS_TYPE_SOA	6	Start-of-Authority (SOA) records
NETLIB_K_DNS_TYPE_WKS	11	Well-known-server (WKS) records
NETLIB_K_DNS_TYPE_PTR	12	Pointer (PTR) records
NETLIB_K_DNS_TYPE_HINFO	13	Host information (HINFO) records
NETLIB_K_DNS_TYPE_MX	15	Mail Exchanger (MX) records
NETLIB_K_DNS_TYPE_TXT	16	Text (TXT) records
NETLIB_K_DNS_QTYPE_ALL	255	Any available information

buffer

VMS usage:	varying_arg
type:	longword (unsigned)
access:	write only
mechanism:	by reference

A buffer into which the DNS response will be copied.

bufsize

VMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

The size of buffer, in bytes.

flags

VMS usage:	longword_mask
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A bitmask of flags specifying options for this query. Valid flags are listed in Table RTN-2. If omitted, the default value for this parameter is 1.

Table RTN-2 Flag values for NETLIB_DNS_QUERY

Symbolic name	Value	Description
NETLIB_M_DOMAIN_SEARCH	1	Perform a domain search on the default domain.
NETLIB_M_NO_RECURSION	2	Specify a non-recursive query.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine formats a DNS query and returns the response from the first name server to provide an answer that indicates either that the query succeeded, or that the name does not exist in the DNS. If the query fails due to an I/O error, that error status is returned and/or stored in the IOSB status word.

Even when this routine returns a success status, the caller should verify that the return code in the header of the DNS reply is NETLIB_K_DNS_RC_SUCCESS, indicating a successful lookup, before attempting to parse the rest of the reply.

The TCPIP$BIND_xxx logical names are used to determine the name server(s) to use for lookups. If no name servers can be found, SS$_UNSUPPORTED is returned.

---

NETLIB_DNS_SKIPNAME

NETLIB_DNS_SKIPNAME is a utility routine used for parsing DNS responses which skips over a domain name.

---

Format

NETLIB_DNS_SKIPNAME bufptr, buflen

---

RETURNS

VMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by value

---

ARGUMENTS

bufptr

VMS usage:	pointer
type:	longword (unsigned)
access:	read only
mechanism:	by value

A pointer to the area of the DNS response buffer that begins the name to be skipped.

buflen

VMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

A count of the number of bytes in the buffer, starting from bufptr.

---

DESCRIPTION

This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It returns a count of the number of bytes to skip allocated to the domain name positioned in the buffer at location bufptr. If the operation fails, -1 is returned to indicate an error.

This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses.

---

NETLIB_GETPEERNAME

NETLIB_GETSOCKNAME returns the remote address and port information for a connected socket.

---

Format

NETLIB_GETPEERNAME socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket
Returned actual length of the socket address.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only	by reference

Size of the socket address structure.

sockaddr-retlen

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Returned actual length of the socket address.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine is used to return the remote address and port information for a socket that is connected to a remote system.

---

NETLIB_GETSOCKNAME

NETLIB_GETSOCKNAME returns the local address and port information for a socket.

---

Format

NETLIB_GETSOCKNAME socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Socket for which the information is to be returned.

socket-address

VMS usage:	structure
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Socket_address structure which will hold the returned address/port information.

sockaddr-size

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Size of the socket address structure.

sockaddr-retlen

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Returned actual length of the socket address.

iosb

VMS usage:	io_status_block
type:	longword (unsigned)
access:	write only
mechanism:	by reference

I/O status block to receive the status for this call.

astadr

VMS usage:	procedure
type:	longword (unsigned)
access:	call
mechanism:	by reference

Address of an AST routine to be invoked on completion of this operation.

astprm

VMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Parameter to be passed to the AST routine.

---

DESCRIPTION

This routine is used to return the local address and port information for a socket that has been bound or connected.

---

NETLIB_GETSOCKOPT

NETLIB_GETSOCKOPT gets the current state of a socket option.

---

Format

NETLIB_GETSOCKOPT socket, level, option, value, valsize [,vallen] [,iosb] [,astadr] [,astprm]

---

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

---

ARGUMENTS

socket

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The socket about which you wish to obtain the option information.

level

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

"Level" of the option being set. The only level globally supported is NETLIB_K_LEVEL_SOCKET (value X'FFFF'). Some packages also support protocol-level option settings.

option

VMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Longword representing the option being set. Not all packages support all options, but most support the ones listed in Table RTN-4.

---

Previous

Next

Contents

Index