|
|
This appendix describes DNR (Domain Name Resolver) directory services and how the DNR can be used to augment the use of API macro instructions. It includes these sections:
The DNR is a separate application program and can be configured to run in its own address space or in the same address space as the API. The function of DNR is to provide directory services to other application programs. These application programs generally use DNR to acquire network transport services for communicating with remote programs in a distributed processing environment. In fact, DNR uses the API to provide the transport between components of a distributed database that comprises a global network directory.
The directory consists of locally configured information and global information by supporting the Domain Name System (DNS). The DNS defines a distributed database system and provides a more dynamic information retrieval system than a local database search. Information may be obtained from the DNR by invoking the DIRSRV macro instruction or the dirsrv() C function. The client provides the name of an object known to the DNR. The DNR searches the directory for the information associated with that name or attribute and returns the information to the client.
Directory services can be used to build transport protocol addresses by mapping host names and service names into network addresses and TCP or UDP port numbers.
Other directory services are available to support application programs that process and distribute electronic mail. These services are currently provided by DNR:
The DNR information base consists of locally configured information and global information. Corresponding to this data, some services involve accessing local configured information only. Others use local and global distributed database, satisfied by DNR's implementation of the Domain Name System (DNS).
The Domain Name System (DNS) consists of the domain name space, resource records that describe the name space, name servers, and resolvers. The domain name space is a tree structured name space intended to provide a mechanism for naming resources in such a way that the host, network, or protocol is transparent. Each node within the name space corresponds to a set of resources. These resources are identified in a defined data format and referred as Resource Records (RR). Name servers and resolvers are application programs that exchange the Resource Records describing the name space.
The hierarchical structure of the domain name space is reflected in the format of a domain name. Each DNS node is represented by a label that is the simple name of the node. A fully qualified domain name describes a path through the domain name space to a particular node, beginning with the top-level (root) node. The name is formed by concatenating the simple names (or labels) of each node in right-to-left sequence, separated by periods (.) and beginning with the top-level domain. Thus, a 4-level domain name appears in this format:
level-4.level-3.level-2.level-1
Information about the name space is divided into zones and held by the domain's name servers. A name server's function is to hold information about the domain name space and provide answers to resolver's requests. The resolver's function is to extract information from name servers in response to client requests. The DNR implements the resolver portion of the DNS and queries name servers for responses.
Local configuration data enable DNR to provide services not provided by the Domain Name System as well as to provide an alternative to network based directory.
Names provided to DNR by the application program must conform to certain syntactic rules. Also, any name returned to the application program by DNR conforms to the same rules. These rules are defined separately for locally-managed names and Internet domain names.
Locally-managed names consist of those names defined in locally-maintained configuration data sets, and may be any one of these types:
Such names are case-insensitive and consist of alphanumeric characters from the EBCDIC character set (a-z, A-Z, 0-9). The dash character (-) may also be used as long as it is embedded within the name (in other words, does not appear at the beginning or end of the name). Locally-managed names must be less than or equal to 40 characters in length.
Simple domain names (in other words, domain name labels) are case-insensitive and consist of alphanumeric characters from the EBCDIC character set (a-z, A-Z, 0-9). The dash character (-) may also be used as long as it is embedded within the name (in other words, does not appear at the beginning or end of the name). Simple domain names must be less than or equal to 63 characters in length, and fully-qualified domain names must be less than or equal to 255 characters in length, including the terminating period.
The period at the end of a domain name represents the root of the Domain Name System (DNS) and indicates that the name is fully-qualified. A domain name not terminated with a period is assumed to be partially-qualified. In the latter case, DNR constructs fully-qualified names by appending qualifiers from a search list in a predetermined order.
This section includes the calls used to access directory information services for the Domain Name Resolver (DNR). Each macro instruction description includes this information:
It is assumed that you are familiar with the API concepts and facilities presented in Cisco IOS for S/390 Assembler API Concepts.
The DIRSRV macro instruction is defined in terms of its general use in obtaining information from the directory. Specific instances of the macro instruction are defined which correspond to the specific directory services that were listed in Other Directory Services.
[symbol] DIRSRV function_code,| function_code | These values can be coded:
GET - Indicates that the requested information is to be retrieved from the directory and returned to the application program. PURGE - Indicates a previously issued asynchronous DIRSRV request is to be purged. |
| information_category | Specifies a category of information maintained by DNR. This operand in combination with the search argument determines the specific type of information requested by the application program. These values may be coded:
HOST - Indicates information regarding a specific host consisting of its official name, alias name, and network-layer addresses (in other words, Internet addresses). NETWORK - Indicates information regarding a specific network consisting of its official name and network number. SERVICE - Indicates information regarding a well-known service consisting of its official name and transport-layer address (in other words, TCP or UDP port number). PROTOCOL - Indicates information regarding a specific protocol consisting of its official name and protocol number. HOSTSERV - Indicates information regarding a specific host consisting of its network-layer addresses and associated well-known services available at those addresses. HOSTINFO - Indicates information regarding a specific host consisting of a standardized CPU and operating system name. ROUTE - Indicates information regarding electronic mail routes consisting of a list of host names willing to act as mail routers for a specific host. |
| search_argument | Determines how the directory database is searched by indicating the specific type of information provided by the application program and implying the type of information to be returned by DNR. These values may be coded for this operand:
BYNAME - Indicates that a name has been supplied by the application program in the storage area defined by the NABUF and NALEN operands, and that the value associated with the named object is to be returned in the storage area defined by the VABUF and VALEN operands. BYVALUE - Indicates that a value has been supplied by the application program in the storage area defined by the VABUF and VALEN operands, and that the name of the object with the specified value is to be returned in the storage area defined by the NABUF and NALEN operands. BYALIAS - Indicates that an alias name (or real name) has been supplied by the application program in the storage area defined by the NABUF and NALEN operands, and that the real name associated with the alias name is to be returned in the storage area defined by the VABUF and VALEN operands. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a host, network, service, or protocol, or in which DNR returns such a name. The type of name contained or returned in the storage area is determined by the values indicated for information category and search argument, and consists of a a case-insensitive string of EBCDIC characters. Other syntactic rules may apply depending on the type of name.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. If the storage area contains a name provided by the application program, NALEN is the actual length of the name. If the storage area is to receive a name returned by DNR, NALEN is the maximum length of the storage area. The length is updated when the request is completed to reflect the actual length of the name returned. If no information is returned, the request is completed abnormally and the length remains unchanged. A length of zero is invalid.
Default: 0 (no name provided or returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed an Internet address, network number, TCP or UDP port number, or transport protocol number, or in which DNR returns such a value. The type of value contained or returned in the storage area is determined by the values indicated for information category and search argument. The format of such values is type-dependent, and the length is indicated by the VALEN operand.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. If the storage area contains a value provided by the application program, VALEN is the actual length of the value. If the storage area is to receive a value returned by DNR, VALEN is the maximum length of the storage area. The length is updated when the request is completed to reflect the actual length of the value returned. If no information is returned, the request is completed abnormally and the length remains unchanged. A length of zero is invalid.
Default: 0 (no value provided or returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully-qualified name associated with a partial name provided by the application program. The partially-qualified name is contained in the storage area indicated by the NABUF and NALEN operands. Rules governing the formation of names and local configuration information maintained by DNR is used to construct fully-qualified names, which in turn are used to search the directory for the desired information.
The value returned depends on the type of search being performed. If the search argument is BYALIAS, the name returned is the locally-qualified alias that is used to search for the real name. Otherwise, the search argument must be BYNAME and the name returned is the locally-qualified name, or if an alias is encountered in the search, the last de-referenced alias name. Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully-qualified name returned. A length of zero indicates that no name is to be returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, an error code indicating such is returned to the application program.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| SIZE = size_limit | Indicates a limit on the amount of information returned. The ultimate limit is determined by the length of the storage area provided to receive the returned values. However, for those requests that may return lists or an array of values, this operand limits the number of elements returned. A value of zero indicates there is no limit (other than the size of the storage area provided).
Default: 0 (no size limit) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
Of the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). This option code affects disposition of a request after it has been accepted by DNR. If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). Default: BLOCK (suspend task indefinitely) |
| OPTCD=LOCAL | GLOBAL | Indicates the scope of the directory search.
If the option is OPTCD=LOCAL, only the locally-maintained database is searched. If the option is OPTCD=GLOBAL, the distributed database is searched, and queries for the requested information are sent to remote destinations as required. If this option is specified, and access to the network is disabled or inoperative, or no distributed nodes are configured, the request proceeds as if OPTCD=LOCAL were specified. Default: GLOBAL (global scope) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations.If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an Event Control Block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT=exit routine address below. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set. If the application program specified a SIZE limit less than the defined number of entries for the given host, or if the entire list of return information would not fit in the storage area provided, the DCMORE conditional completion code is returned.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Syntactic Rules for Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request, the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the DIRSRV macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY DCOVRFLO | DCMORE DCNAMEIA | DCALIAS DCLOCAL |
| DRFAILED | DAEXCPTN | DENONAME DETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAM DENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOST-BYNAME instance of the DIRSRV macro instruction is used to obtain a list of Internet addresses for a given host when its name is known. The name provided may be a local alias or a partial or fully qualified domain name, and the information returned may be obtained locally from the host-name configuration data set (DNRHSTxx) or globally from the Internet Domain Name System (DNS).
[symbol] DIRSRV GET,HOST,BYNAME,| GET,HOST,BYNAME | Indicates that the DNR is to search for and return a list of Internet addresses associated with the host name or alias provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a host. The name may be a local alias defined in the alias configuration member (DNRALCxx), a local host name defined in the host configuration member (DNRHSTxx), or an Internet domain name or alias name defined by the DNS. Names may be partially or fully qualified. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a fully qualified domain name is 255 bytes. The maximum length of a local alias name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a list of Internet addresses associated with the named host. Each Internet address is four bytes. The number of addresses returned is the smaller of the total number defined for the host, the length of the storage area divided by the length of an Internet address (4), or the number indicated by the SIZE operand.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged. The minimum length of the storage area is 4 bytes. It is not necessary that the storage area length be evenly divisible by the length of an Internet address.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully qualified name used to search for the requested information. The fully qualified name is either the result of a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned to the application program. TIME is only applicable if OPTCD=GLOBAL.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| SIZE = size_limit | Indicates a limit on the amount of information returned for requests that return lists or arrays of values. A value of zero indicates there is no limit and the DNR is to return all Internet addresses associated with the domain name. If the return information would not fit in its entirety in the storage area provided or if the application program specifies a limit less than the defined number of Internet addresses for the given host, the DCMORE conditional completion code is returned.
Default: 0 (no size limit) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). If the option is OPTCD=NOBLOCK. The request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). OPTCD=BLOCK|NOBLOCK is only applicable if OPTCD=GLOBAL. This option code affects disposition of a request after it has been accepted by the DNR. Default: BLOCK (suspend task indefinitely) |
| OPTCD = LOCAL | GLOBAL | Indicates the scope of the directory search.
If the option is OPTCD=LOCAL, only the locally-maintained database is searched. If the option is OPTCD=GLOBAL, the distributed database is searched, and queries for the requested information are sent to remote destinations as required. If this option is specified, and access to the network is disabled or inoperative, or no distributed nodes are configured, the request proceeds as if OPTCD=LOCAL were specified. Default: GLOBAL (global scope) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. OPTCD=COPY|ORIGINAL is only applicable if OPTCD=GLOBAL. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands are not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set. If the application program specified a SIZE limit less than the defined number of entries for the given host, or if the entire list of return information would not fit in the storage area provided, the DCMORE conditional completion code is returned.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Locally-Managed Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request, the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the GET-HOST-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY DCOVRFLO | DCMORE DCNAMEIA | DCALIAS DCLOCAL |
| DRFAILED | DAEXCPTN | DENONAME DETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAMDENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOST-BYNAME instance of the DIRSRV macro is used to get a list of internet addresses given an Internet domain name.
The list of returned Internet addresses is sorted according to the networks given in the network preference configuration member (DNRNPCxx).
This example demonstrates the use of GET-HOST-BYNAME. The request is to find the list of internet addresses for the host NS.NASA.GOV. The application supplies this DIRSRV information:
NABUF = (address of:)
N | S | . | N | A | S | A | . | G | O | V |
NALEN = 11 VABUF = (address of:)
|
VALEN = 100 QNBUF = (address of:)
|
QNLEN = 100
SIZE = 0
This information is returned:
NABUF = (address of:)
N | S | . | N | A | S | A | . | G | O | V |
NALEN = 11
VABUF = (address of:)
0x80 | 0x66 | 0x10 | 0x0a | 0xc0 | 0x34 | 0xc3 | 0x0a |
VALEN = 8
QNBUF = (address of:)
N | S | . | N | A | S | A | . | G | O | V | . |
QNLEN = 12
SIZE = 2
Because the search string, 'NS.NASA.GOV' is partially qualified, the search list strings were appended to 'NS.NASA.GOV'. The root (.) is always included in the search list, therefore, the directory was searched for 'NS.NASA.GOV.'. The DNR received a DNS response for 'NS.NASA.GOV.' and returned the information to the application program.
The GET-HOST-BYVALUE instance of the DIRSRV macro instruction is used to obtain a fully qualified host name for a host when its address is known. The address provided may be an address defined locally or globally known to the Internet Domain Name System (DNS) and the information returned may be obtained locally from the host name configuration member (DNRHSTxx) or globally.
[symbol] DIRSRV GET,HOST,BYVALUE,| GET,HOST,BYVALUE | Indicates that the DNR is to search for and return a fully qualified host name associated with the host Internet address provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the DNR returns a fully qualified host name associated with the given Internet address.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no name returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed a four-byte Internet address.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The value of the storage area must be 4 bytes.
Default: 0 (no value provided) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned the application program. TIME is only applicable if OPTCD=GLOBAL.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). OPTCD=BLOCK|NOBLOCK is only applicable if OPTCD=GLOBAL. This option code affects disposition of a request after it has been accepted by DNR. Default: BLOCK (suspend task indefinitely) |
| OPTCD = LOCAL | GLOBAL | Indicates the scope of the directory search.
If the option is OPTCD=LOCAL, only the locally-maintained database is searched. If the option is OPTCD=GLOBAL, the distributed database is searched, and queries for the requested information are sent to remote destinations as required. If this option is specified, and access to the network is disabled or inoperative, or no distributed nodes are configured, the request proceeds as if OPTCD=LOCAL were specified. OPTCD=COPY|ORIGINAL is only applicable if OPTCD=GLOBAL. Default: GLOBAL (global scope) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner. If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-HOST-BYVALUE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | DCLOCAL | |
| DRFAILED | DAEXCPTN | DENONAME DETIMOUT DENOCDS DENODATA DEQNMODE | DENOVALU DERFAIL DEOVRFLO DENAMODE | DENOQNAMDENOTFND DENOBLOK DEVAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOST-BYVALUE instance of the DIRSRV macro is used to obtain a fully qualified domain name given an Internet address.
This example demonstrates the use of GET-HOST-BYVALUE. The request is to find the host name for the internet address 192.52.195.10.
The application supplies this DIRSRV information:
NABUF = (address of:)
|
NALEN = 100
VABUF = (address of:)
0xc0 | 0x34 | 0xc3 | 0x0a |
VALEN = 4
This information is returned:
NABUF = (address of:)
N | S | . | N | A | S | A | . | G | O | V | . |
NALEN = 12
VABUF = (address of:)
0xc0 | 0x34 | 0xc3 | 0x0a |
VALEN = 4
The GET-HOST-BYALIAS instance of the DIRSRV macro instruction is used to obtain a fully qualified domain name for a host when its alias is known. The name provided may be a local alias or a partial or fully qualified domain name alias, and the information returned may be obtained locally from the alias configuration member (DNRALCxx) or globally from the Internet Domain Name System (DNS).
[symbol]DIRSRV GET,HOST,BYALIAS,| GET,HOST,BYALIAS | Indicates that the DNR is to search for and return the fully qualified name associated with the alias provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the alias name of a host. The name may be a local alias defined in the alias configuration member (DNRALCxx) or an Internet domain alias name defined by the DNS. Names may be partially or fully qualified. All names must conform to the syntactic rules described in Locally-Managed Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the alias located in the storage area identified by the NABUF operand. The maximum length of a fully qualified domain name is 255 bytes. The maximum length of a local alias name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which the DNR returns a fully qualified name associated with the given alias.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully qualified name used to search for the requested information. The fully qualified name is either the result of a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned the application program. TIME is only applicable if OPTCD=GLOBAL.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). OPTCD=BLOCK|NOBLOCK is only applicable if OPTCD=GLOBAL. This option code affects disposition of a request after it has been accepted by the DNR. Default: BLOCK (suspend task indefinitely) |
| OPTCD = LOCAL | GLOBAL | Indicates the scope of the directory search.
If the option is OPTCD=LOCAL, only the locally-maintained database is searched. If the option is OPTCD=GLOBAL, the distributed database is searched, and queries for the requested information are sent to remote destinations as required. If this option is specified, and access to the network is disabled or inoperative, or no distributed nodes are configured, the request proceeds as if OPTCD=LOCAL were specified. Default: GLOBAL (global scope) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. OPTCD=COPY|ORIGINAL is only applicable if OPTCD=GLOBAL. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Syntactic Rules for Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request (in other words, the search string is not an alias but an actual host name) the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the GET-HOST-BYALIAS macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY DCLOCAL | DCALIAS | DCOVRFLO |
| DRFAILED | DAEXCPTN | DENONAME DETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAMDENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOST-BYALIAS instance of the DIRSRV macro is used to obtain a fully qualified domain name given an alias.
If OPTCD=LOCAL, the DNR returns information received from the alias configuration member (DNRALCxx).
If OPTCD=GLOBAL, the DNR returns information received from Domain Name System Canonical (CNAME) records.
This example demonstrates the use of GET-HOST-BYALIAS, OPTCD=LOCAL. The request is to find a fully qualified domain name for the subsystem name ACSS.
The alias configuration member (DNRALCxx) contains:
ACSS ZEUS.ACC.COM.
The application supplies this DIRSRV information:
NABUF = (address of:)
A | C | S | S |
NALEN = 4
VABUF = (address of:)
|
VALEN = 100
This information is returned:
NABUF = (address of:)
A | C | S | S |
NALEN = 4
VABUF = (address of:)
Z | E | U | S | . | A | C | C | . | C | O | M | . |
VALEN = 13
The GET-NETWORK-BYNAME instance of the DIRSRV macro instruction is used to obtain a network number when its name is known. The information returned is obtained locally from the network configuration member (DNRNETxx).
[symbol] DIRSRV GET,NETWORK,BYVALUE,| GET,NETWORK,BYNAME | Indicates that DNR is to search for and return a network number associated with the network name provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a network. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a local network name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided or returned) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a network number associated with the named network.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned.
If the request completes normally, the length is updated to a value from one to three. If the request completes abnormally, no information is returned and the length remains unchanged. Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-NETWORK-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAMEDENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-NETWORK-BYNAME. The request is to find the network number for the name ARPANET.
The application supplies this DIRSRV information:
NABUF = (address of:)
A | R | P | A | N | E | T |
NALEN = 7
VABUF = (address of:)
|
VALEN = 100
This information is returned:
NABUF = (address of:)
A | R | P | A | N | E | T |
NALEN = 7
VABUF = (address of:)
10 |
VALEN = 1
The GET-NETWORK-BYVALUE instance of the DIRSRV macro instruction is used to obtain a network name when its value is know. The information returned is obtained locally from the network configuration member (DNRNETxx).
[symbol] DIRSRV GET,NETWORK,BYVALUE,| GET,NETWORK,BYVALUE | Indicates that DNR is to search for and return a network name associated with the network number provided by the application program.
NABUF = name_address Indicates the address of a storage area in which the DNR returns the name of a network. Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed a network number.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the network number located in the storage area identified by the VABUF operand. This number should be one to three (bytes). A length of zero is invalid.
Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-NETWORK-BYVALUE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAME DENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-NETWORK-BYVALUE. The request is to find the network name for 10.
The application supplies this DIRSRV information:
NABUF = (address of:)
|
NALEN = 100
VABUF = (address of:)
10 |
VALEN = 1
This information is returned:
NABUF = (address of:)
A | R | P | A | N | E | T |
NALEN = 7
VABUF = (address of:)
10 |
VALEN = 1
The GET-PROTOCOL-BYNAME instance of the DIRSRV macro instruction is used to obtain a protocol number when its name is known. The information returned is obtained locally from the protocol configuration member (DNRPRTxx).
[symbol] DIRSRV GET,PROTOCOL,BYNAME,| GET,PROTOCOL,BYNAME | Indicates that the DNR is to search for and return a protocol number associated with the protocol name provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed a protocol name. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a protocol name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a protocol number associated with the named protocol.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned.
If the request completes normally, the length is updated to a value from one to three. If the request complete abnormally, no information is returned and the length remains unchanged. Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT=exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-PROTOCOL-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAMEDENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-PROTOCOL-BYNAME. The request is to find the protocol number of TCP.
The application supplies this DIRSRV information:
NABUF = (address of:)
T | C | P |
NALEN = 3
VABUF = (address of:)
|
VALEN = 100
This information is returned:
NABUF = (address of:)
T | C | P |
NALEN = 3
VABUF = (address of:)
6 |
VALEN = 1
The GET-PROTOCOL-BYVALUE instance of the DIRSRV macro instruction is used to obtain a protocol name when its official protocol number is known. The information returned is obtained locally from the protocol configuration member (DNRPRTxx).
[symbol] DIRSRV GET,PROTOCOL,BYVALUE,| GET,PROTOCOL,BYVALUE | Indicates that DNR is to search for and return a protocol name associated with the protocol number provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the DNR returns a protocol name associated with the protocol number contained in the storage area indicated by the VABUF and VALEN operands.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged. A length of zero is invalid.
Default: 0 (no name provided or returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed a protocol number.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the protocol number located in the storage area identified by the VABUF operand. This number should be 1 (byte). A length of zero is invalid.
Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| SIZE = size_limit | Indicates a limit on the amount of information returned. The ultimate limit is determined by the length of the storage area provided to receive the returned values. However, for those requests that may return lists or an array of values, this operand limits the number of elements returned. A value of zero indicates there is no limit (other than the size of the storage area provided).
Default: 0 (no size limit) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT = exit_routine_address. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-PROTOCOL-BYVALUE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAME DENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-PROTOCOL-BYVALUE. The request is to find a protocol name for the protocol number 6. The application supplies this DIRSRV information:
NABUF = (address of:)
|
NALEN = 100
VABUF = (address of:)
6 |
VALEN = 1
This information is returned:
NABUF = (address of:)
T | C | P |
NALEN = 3
VABUF = (address of:)
6 |
VALEN = 1
The GET-SERVICE-BYNAME instance of the DIRSRV macro instruction is used to obtain a port number when its name is known. The information returned is obtained locally from the services configuration member (DNRSVCxx).
[symbol] DIRSRV GET,SERVICE,BYNAME,| GET,SERVICE,BYNAME | Indicates that DNR is to search for and return a service port number associated with the protocol/service pair provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the protocol/service name pairs. The protocol/service names should be separated by a slash (/). All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a local protocol or service name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided or returned) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a service number associated with the named protocol/service pair.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned.
If the request completes normally, the length is updated to a value from one to three. If the request completes abnormally, no information is returned and the length remains unchanged. Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT = exit_routine_address. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-SERVICE-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAME DENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-SERVICE-BYNAME. The request is to obtain a service number for the name TCP/DISCARD.
The application supplies this DIRSRV information:
NABUF = (address of:)
T | C | P | / | D | I | S | C | A | R | D |
NALEN = 11
VABUF = (address of:)
|
VALEN = 100
This information is returned:
NABUF = (address of:)
T | C | P | / | D | I | S | C | A | R | D |
NALEN = 11
VABUF = (address of:)
9 |
VALEN = 1
The GET-SERVICE-BYVALUE instance of the DIRSRV macro instruction is used to obtain a protocol and service name pair when a service number is known. The information returned is obtained locally from the service configuration member (DNRSRVxx).
[symbol] DIRSRV GET,SERVICE,BYVALUE,| GET,SERVICE,BYVALUE | Indicates that DNR is to search for and return a list of protocol and service name pairs associated with the service port number provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the DNR returns a list of protocol and service name pairs. The protocol and service name entries are separated by a slash (/). Each entry in the list is separated by a space character. The number of entries returned is returned in the SIZE operand.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed a service port number.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the port number located in the storage area identified by the VABUF operand. This number should be 2 (bytes). A length of zero is invalid.
Default: 0 (no value returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| SIZE = size_limit | Indicates a limit of the number of protocol and service name pairs returned. A value of 0 in the request, indicates there is no limit and the DNR is to return all name pairs associated with the port number. If the return information would not fit in the storage area provided or if the application program specifies a limit less than the defined number of protocol and service name pairs, the DCMORE conditional completion code is returned.
Default: 0 (no size limit) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. If the application program specified a SIZE limit less than the defined number of entries for the given host, or if the entire list of return information would not fit in the storage area provided, the DCMORE conditional completion code is returned.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-SERVICE-BYVALUE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAME DENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-SERVICE-BYVALUE. The request is to find the protocol and service name pair for the service port number 9.
The application supplies this DIRSRV information:
NABUF = (address of:)
|
NALEN = 100
VABUF = (address of:)
9 |
VALEN = 1
This information is returned:
NABUF = (address of:)
T | C | P | / | D | I | S | C | A | R | D | U | D | P | / | |
| D | I | S | C | A | R | D |
NALEN = 23
VABUF = (address of:)
9 |
VALEN = 1
The GET-HOSTINFO-BYNAME instance of the DIRSRV macro instruction is used to obtain CPU and operating system information for a given host when its name is known. The name provided may be a local alias or a partial or fully-qualified domain name. The information returned is obtained globally from the Internet Domain Name System (DNS).
[symbol] DIRSRV GET,HOSTINFO,BYNAME,| GET,HOSTINFO,BYNAME | Indicates that DNR is to search for and return CPU and operating system information associated with the host name or alias provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a host. The name may be a local alias defined in the alias configuration member (DNRALCxx) or an Internet domain name or alias name defined by the DNS. Internet domain names may be partially or fully qualified. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a fully-qualified domain name is 255 bytes. The maximum length of a local alias name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns the CPU and operating system information. The strings are EBCIDIC strings separated by a space character.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully qualified name used to search for the requested information. The fully qualified name is either the result of a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully-qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned the application program.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). This option affects disposition of a request after it has been accepted by the DNR. If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). Default: BLOCK (suspend task indefinitely) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT = exit_routine_address. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Syntactic Rules for Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request, the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the GET-HOSTINFO-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | DCALIAS | DCOVRFLO |
| DRFAILED | DAEXCPTN | DENONAMEDETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAMDENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOSTINFO-BYNAME instance of the DIRSRV macro is used by application programs to obtain CPU and operating system information. The DNR returns information received from DNS Host Information (HINFO) records. HINFO records specify the data returned by the DNR.
This example demonstrates the use of GET-HOSTINFO-BYNAME. The request is to obtain CPU and operating system information about UNIX.
The alias configuration member (DNRALCxx) contains:
ACSS ZEUS.ACC.COM.
UNIX SALT.
The application supplies this DIRSRV information:
NABUF = (address of:)
U | N | I | X |
NALEN = 4
VABUF = (address of:)
|
VALEN = 100
QNBUF = (address of:)
|
QNLEN = 100
This information is returned:
NABUF = (address of:)
U | N | I | X |
NALEN = 4
VABUF = (address of:)
V | A | X | - | 1 | 1 | / | 7 | 8 | 5 | U | N | I | X |
VALEN = 15
QNBUF = (address of
S | A | L | T | . | A | C | C | . | C | O | M | . |
QNLEN = 13
SALT.ACC.COM. was used to search the directory because UNIX was found as an alias in the alias configuration member. Because the replacement string, SALT, was partially qualified, the search list strings were appended to SALT.
ACC.COM. was included in the search list because the subsystem name ACSS is included in the alias configuration member. The DNR received a DNS response for SALT.ACC.COM. and returned the information to the application program.
The GET-HOSTSERV-BYNAME instance of the DIRSRV macro instruction is used to obtain a list of well-known service supported by a host. The name provided may be a local alias or a partial or fully-qualified domain name. The information returned is obtained globally from the Internet Domain Name System (DNS).
[symbol] DIRSRV GET,HOSTSERV,BYNAME,| GET,HOSTSERV,BYNAME | Indicates that DNR is to search for and return a list of well-known services supported by the host name or alias provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a host. The name may be a local alias defined in the alias configuration member (DNRALCxx) or an Internet domain name or alias name defined by the DNS. Internet domain names may be partially or fully qualified. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a fully-qualified domain name is 255 bytes. The maximum length of a local alias name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a list of well-known services supported by the host. The list contains a four-byte Internet address followed by a two-byte protocol number, a two-byte integer indicating the number of ports supported, followed by an array of two-byte ports. The array size is indicated by the two-byte number proceeding the array. Each entry describes the well-known services supported by a particular protocol on a particular internet address. The number of entries is the smaller of the total number defined for the host, the length of the storage area available, or the number indicated by the SIZE operand.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully qualified name used to search for the requested information. The fully qualified name is either the result of a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully-qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned the application program.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| SIZE = size_limit | Indicates a limit of the number of entries returned. A value of zero in the request, indicates there is no limit and the DNR is to return all entries associated with the domain name. If the return information would not fit in the storage area provided or if the application program specifies a limit less than the defined number of entries for the given host, the DCMORE conditional completion code is returned.
Default: 0 (no size limit) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) OPTCD = BLOCK | NOBLOCK Indicates the disposition of a request if the information is not immediately available. If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). This option code affects disposition of a request after it has been accepted by the DNR. If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). Default: BLOCK (suspend task indefinitely) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set. If the application program specified a SIZE limit less than the defined number of entries for the given host, or if the entire list of return information would not fit in the storage area provided, the DCMORE conditional completion code is returned.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Syntactic Rules for Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request, the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the GET-HOSTSERV-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY DCOVRFLO | DCMORE | DCALIAS |
| DRFAILED | DAEXCPTN | DENONAME DETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAM DENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-HOSTSERV-BYNAME instance of the DIRSRV macro is used by application programs to determine the services supported by a given Internet domain name. The DNR returns information received from DNS Well Known Services (WKS) records. WKS records specify the well-known services supported by a particular protocol on a particular internet address. The two-byte protocol number returned in an entry may be used as input in a DIRSRV GET-PROTOCOL-BYVALUE request to obtain the associated protocol name. Likewise, the two byte port numbers may be used as input in a DIRSRV GET-SERVICE-BYVALUE request to obtain the associated service names.
This example demonstrates the use of GET-HOSTSERV-BYNAME. The request is to find the list of well-known services supported by host TERP.UMD.EDU.
The application supplies this DIRSRV information:
NABUF = (address of:)
T | E | R | P | . | U | M | D | . | E | D | U |
NALEN = 12
VABUF = (address of:)
|
VALEN = 100
QNBUF = (address of:)
|
QNLEN = 100
SIZE = 100
This information is returned:
NABUF = (address of:)
T | E | R | P | . | U | M | D | . | E | D | U | . |
NALEN = 13
VABUF = (address of:)
0x80 | 0x08 | 0x0a | 0x5a | 17 | 2 | 53 | 123 | ||||
| 0x80 | 0x08 | 0x0a | 0x5a | 6 | 3 | 21 | 23 | ||||
| 25 |
VALEN = 26
QNBUF = (address of:)
|
QNLEN = 100
SIZE = 2
The response information indicates that the Internet address of 128.8.10.90 (0x80080a5a) supports 2 UDP (17) well-known services DOMAIN (53) and NTP (123) and 3 TCP (6) services FTP (21), TELNET (23), and SMTP (25).
The GET-ROUTE-BYNAME instance of the DIRSRV macro instruction is used to obtain a list of hosts willing to act as a mail exchange for a host. The name provided may be a local alias or a partial or fully qualified domain name. The information returned is obtained globally from the Internet Domain Name System (DNS).
[symbol] DIRSRV GET,ROUTE,BYNAME,| GET,ROUTE,BYNAME | Indicates that DNR is to search for and return a list of host names willing to act as mail exchanges for the host name or alias provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed the name of a host. The name may be a local alias defined in the alias configuration member (DNRALCxx) or an Internet domain name or alias name defined by the DNS. Internet domain names may be partially or fully qualified. All names must conform to the syntactic rules described in Syntactic Rules for Names.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of a fully-qualified domain name is 255 bytes. The maximum length of a local alias name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns a list of hosts willing to act as mail exchanges. The list contains EBCDIC character strings separated by a space character. The number of strings returned is specified in the SIZE operand. The list is sorted by preference giving the highest preferred host first. The number of entries is the smaller of the total number defined for the host, the length of the storage area available, or the number indicated by the SIZE operand.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the fully qualified name used to search for the requested information. The fully qualified name is either the result of a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully-qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| TIME = time_limit_ | Indicates the maximum amount of elapsed time (in seconds) to find the requested information. Since portions of the distributed database are maintained on other systems, queries must sometimes be transmitted to remote destinations. Also, the responses to such queries may contain referrals to other remote systems. Therefore, some types of directory requests may take an arbitrary amount of time to complete. This operand can be used to limit the amount of time spent searching for specific information. If the directory search is abandoned because the time limit has been exceeded, DETIMOUT error code is returned the application program.
Default: 0 (use MAXTIME limit in DNRCFG00) |
| SIZE = size_limit | Indicates a limit of the number of entries returned. A value of zero in the request, indicates there is no limit and the DNR is to return all entries associated with the domain name. If the return information would not fit in the storage area provided or if the application program specifies a limit less than the defined number of entries for the given host, the DCMORE conditional completion code is returned.
Default: 0 (no size limit) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| OPTCD = BLOCK | NOBLOCK | Indicates the disposition of a request if the information is not immediately available.
If the option is OPTCD=BLOCK, processing continues in accordance with the synchronization mode selected (OPTCD=SYNC | ASYNC). This option code affects disposition of a request after it has been accepted by the DNR. If the option is OPTCD=NOBLOCK, the request is completed abnormally and the specific error code is set to DENOBLOK indicating that the request could not be completed immediately. OPTCD=NOBLOCK is generally used in conjunction with OPTCD=SYNC to prevent suspension of the issuing task for an extended period of time. Note The issuing task may be momentarily suspended to let the DNR address space process the request. If the application program cannot afford to be suspended, even for a very small amount of time, then the request must be executed asynchronously (OPTCD=ASYNC). Default: BLOCK (suspend task indefinitely) |
| OPTCD = COPY | ORIGINAL | Indicates whether a copy of the information can be used to complete the request or whether original information must be returned.
If the option is OPTCD=COPY, a local copy of the requested information may be used to satisfy the request. Specifying OPTCD=COPY lets information obtained as the result of a previous request be reused and returned to the application program, thus avoiding time-consuming queries to remote destinations. If the option is OPTCD=ORIGINAL, the information must be obtained from its original, authoritative source. Specifying OPTCD=ORIGINAL assures that the most current information is returned. Default: COPY (use copy of original data) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT = exit_routine_address. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the fully qualified name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the fully qualified name in the QNBUF storage area. If the fully qualified name could not fit in the storage area, DCOVRFLO is set. If the application program specified a SIZE limit less than the defined number of entries for the given host, or if the entire list of return information would not fit in the storage area provided, the DCMORE conditional completion code is returned.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
If the fully qualified search string did not conform to the syntactic rules described in Syntactic Rules for Names, a DEBDNAME error code is returned. If the fully qualified search string is a valid host name but the host does not exist, the DNR returns an error code of DENAMERR. If the fully qualified search string is a valid and existing host but there is no specific data configured to satisfy the request, the DNR returns an error code of DENODATA. The fully qualified search string is the result of a fully qualified name given in the NABUF storage area, a local alias lookup, a name formed by appending the DNR search list strings to a partially qualified domain name, or a DNS alias referral.
This table lists the symbolic return codes for the GET-ROUTE-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY DCOVRFLO | DCMORE DCLOCAL | DCALIAS |
| DRFAILED | DAEXCPTN | DENONAMEDETIMOUT DENOCDS DENOBLOK DEVAMODE | DENOVALU DERFAIL DENAMERR DENODATA DEQNMODE | DENOQNAM DENOTFND DEOVRFLO DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
The GET-ROUTE-BYNAME instance of the DIRSRV macro is used by mailers to determine how to route a message given an Internet domain name. The DNR returns information received from DNS Mail Exchange (MX) records. MX records specify mail exchange hosts that know how to route mail to a host not directly connected to the Internet. MX records include a preference value that specifies the preference given to the host relative to other hosts. The DNR sorts MX records according to preference (lower values are preferred) and returns the host names in order. This order reflects the order the calling mailer programs should follow when delivering mail. To determine the internet address of the remote hosts, mailers should pass the hosts names returned in the GET-ROUTE-BYNAME request as search strings to a DIRSRV GET-HOST-BYNAME request.
This example demonstrates the use of GET-ROUTE-BYNAME. The request is to find the list of hosts willing to act as a mail exchange for the host UNIX. The alias configuration member (DNRALCxx) contains:
UNIX VAX.ACC.COM.
The application supplies this DIRSRV information:
NABUF = (address of:)
U | N | I | X |
NALEN = 4
VABUF = (address of:)
|
VALEN = 100
QNBUF = (address of:)
|
QNLEN = 100
SIZE = 100
This information is returned:
NABUF = (address of:)
U | N | I | X |
NALEN = 4
VABUF = (address of:)
S | A | T | U | R | N | . | A | C | C | . | C | O | M | . | |
| S | A | L | T | . | A | C | C | . | C | O | M | . |
VALEN = 29
QNBUF = (address of:)
S | A | T | U | R | N | . | A | C | C | . | C | O | M | . |
QNLEN = 15
SIZE = 2
SATURN.ACC.COM. is returned in the QNBUF because the search string UNIX was listed as an alias in the alias configuration member. The replacement string VAX.ACC.COM. was in turn known as an alias of SATURN.ACC.COM. in the domain name space. The DNR received a DNS response for SATURN.ACC.COM. and returned the information to the application program.
The GET-RPC-BYNAME instance of the DIRSRV macro instruction is used to obtain an RPC number when its RPC name is known. This information returned is obtained locally from the RPC configuration member (DNRRPCxx).
[symbol] DIRSRV GET,RPC,BYNAME,| GET,RPC,BYNAME | Indicates that the DNR is to search for and return an RPC value associated with the RPC name provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the application program has placed an RPC name. The name may be an RPC alias defined in the RPC configuration member (DNRRPCxx) or an official RPC name.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the name located in the storage area identified by the NABUF operand. The maximum length of an RPC name is 40 bytes. A length of zero is invalid.
Default: 0 (no name provided) |
| VABUF = value_address | Indicates the address of a storage area in which DNR returns an RPC value associated with the RPC name. Each returned RPC value is four bytes.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the storage area identified by the VABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged. The minimum length of the storage area is 4 bytes.
Default: 0 (no value returned) |
| QNBUF = qualified_name_address | Indicates the address of a storage area in which DNR returns the official RPC name used to search for the requested information. The DNR returns an RPC name in the QNBUF data area if the search string was an alias.
Default: 0 (no qualified name storage area) |
| QNLEN = qualified_name_length | Indicates the length (in bytes) of the storage area identified by the QNBUF operand. This length is the maximum length of the storage area and is updated when the request is completed to reflect the actual length of the fully qualified name returned. If QNLEN is non-zero, QNBUF must also be non-zero and point to the beginning of a valid storage area.
Default: 0 (no qualified name returned) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in EXIT = exit_routine_address. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly. DCALIAS is set if the name referenced in the NABUF and NALEN operands is not the official RPC name associated with the returned data. If DCALIAS is set and a storage area was supplied in the QNBUF and QNLEN operands, the DNR returns the official RPC name in the QNBUF storage area. If the official RPC name could not fit in the storage area, DCOVRFLO is set.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-RPC-BYNAME macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | DCALIS | DCOVRFLO |
| DRFAILED | DAEXCPTN | DENONAMEDENOTFND DENAMODE | DENOVALUD ENOCDS DEVAMODE | DENOQNAMDE OVRFLO DEQNMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-RPC-BYNAME. The request is to find the RPC number for the RPC name portmapper.
The application supplies this DIRSRV information:
NABUF = (address of:)
S | U | N | R | P | C |
NALEN = 6
VABUF = (address of:)
|
VALEN = 100
QNBUF = (address of:)
|
QNLEN = 100
SIZE = 0
This information is returned:
NABUF = (address of:)
S | U | N | R | P | C |
NALEN = 6
VABUF = (address of:)
0x00 | 0x01 | 0x86 | 0xa0 |
VALEN = 4
QNBUF = (address of:)
P | O | R | T | M | A | P | P | E | R |
QNLEN = 10
Because the search string, SUNRPC is given as an alias in the RPC configuration file, the official RPC name is returned in the qualified name buffer.
The GET-RPC-BYVALUE instance of the DIRSRV macro instruction is used to obtain an RPC name when its number is known. The information returned is obtained locally from the RPC configuration member (DNRRPCxx).
[symbol] DIRSRV GET,RPC,BYVALUE,| GET,RPC,BYVALUE | Indicates that the DNR is to search for and return an RPC name associated with the RPC number provided by the application program. |
| NABUF = name_address | Indicates the address of a storage area in which the DNR returns an RPC name.
Default: 0 (no name storage area) |
| NALEN = name_length | Indicates the length (in bytes) of the storage area identified by the NABUF operand. The length is updated when the request is completed to reflect the actual amount of information returned. If the request completes abnormally, no information is returned and the length remains unchanged.
Default: 0 (no name returned) |
| VABUF = value_address | Indicates the address of a storage area in which the application program has placed a four-byte RPC number.
Default: 0 (no value storage area) |
| VALEN = value_length | Indicates the length (in bytes) of the RPC number located in the storage area identified by the VABUF operand. The value of the storage area must be 4 (bytes).
Default: 0 (no value provided) |
| SYSID = MVS_subsystem_id | Indicates the ID of the MVS subsystem that is to process this request. Normally this operand is not required and an installation default is used. However, if more than one DNR subsystem is active on the local system, the particular subsystem that is to process this request must be indicated. The MVS subsystem ID is coded as an alphanumeric string up to four (4) characters in length.
Default: not indicated (use installation default) |
| OPTCD = SYNC | ASYNC | Indicates the synchronization mode to be used when executing this macro instruction.
If the option is OPTCD=SYNC, the request is executed in synchronous mode, and control is not returned to the application program until the requested macro instruction is complete. If the option is OPTCD=ASYNC, the request is executed in asynchronous mode, and control is returned to the application program immediately after it has been accepted by DNR. The application program is notified asynchronously when the request has been completed. The ECB and EXIT operands determine the form of asynchronous notification. Default: SYNC (synchronous mode) |
| ECB = INTERNAL | event_control_block_addr | Indicates the location of an event control block (ECB) to be posted by DNR when the directory request has been completed. The ECB can be any fullword of storage aligned on a fullword boundary.
The ECB and EXIT operands share the same storage location in the Directory Services Parameter List (DPL), and are therefore mutually exclusive operands. If asynchronous mode has been specified (OPTCD=ASYNC), the ECB-EXIT field of the DPL (DPLECBXR) is used in this manner: If the option is ECB=address, DNR uses the field as the address of an external ECB. The application program is responsible for issuing a WAIT macro instruction and clearing the ECB when posted. If EXIT=address is specified, DNR uses the field as the address of an exit routine, and schedules the routine as indicated in the following EXIT operand text. If the option is ECB=INTERNAL, DNR uses the field as an internal ECB. The application program is responsible for issuing a WAIT macro instruction specifying the internal ECB, but need not clear it when posted. If synchronous mode has been specified (OPTCD=SYNC), the parameter list is flagged to be processed as if ECB=INTERNAL had been specified, and the ECB-EXIT field is used as an internal ECB that is waited on and cleared automatically before control is returned to the application program. Default: INTERNAL (internal ECB) |
| EXIT = exit_routine_address | Indicates the address of a routine to be scheduled when the request is completed. The EXIT and ECB operands share the same storage location in the parameter list and are therefore mutually exclusive. The completion exit is scheduled only if asynchronous mode has been indicated by OPTCD=ASYNC. If synchronous mode has been indicated, the exit routine is not used. If one is specified with this operand, the address is overwritten with an internal ECB before the request completes.
Default: not indicated (no exit routine) |
| MF = (I | L | G | M | E, [dpl_address]) | Indicates the standard (inline), list, generate, modify, or execute form of the DIRSRV macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to be used for this request. If no MF operand is specified, the standard form is used.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=I (inline, nonreentrant) |
The DIRSRV macro instruction completes normally (or conditionally) when the requested information has been returned in the storage area provided by the application program. The length of the storage area is updated to reflect the actual amount of information returned.
On normal return to the application program, the general return code in register 15 is set to 0 (DROKAY), and the conditional completion code is returned in register 0. The DPL return code field is set accordingly.
If the DIRSRV macro instruction completes abnormally, no information is returned in the storage area and the storage area length is unmodified. The general return code in register 15 and the recovery action code indicate the nature of the failure.
This table lists the symbolic return codes for the GET-RPC-BYVALUE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAEXCPTN | DENONAMEDENOCDS DEVAMODE | DENOVALU DEOVRFLO | DENOTFND DENAMODE |
| DAENVIRO | DESYSERR DENOTACT DEUNAVBL DETERM | DESUBSYS DENOTRDY DERSOURC | DENOTCNF DESTOP DENOTPRB | |
| DAFORMAT | DEBDOPCD DEBDEXIT | DEBDFNCD DEBDNAME | DEBDXECB DEBDVALU | |
| DRFATLPTL | DAPROCED | DEACTIVE | ||
| DADPLERR | DEBDTYPE | DEPROTCT | DEPLMODE | |
This example demonstrates the use of GET-RPC-BYVALUE. The request is to find the RPC name for the RPC value 100000.
The application supplies this DIRSRV information:
NABUF = (address of:)
|
NALEN = 100
VABUF = (address of:)
0x00 | 0x01 | 0x86 | 0xa0 |
VALEN = 4
This information is returned:
NABUF = (address of:)
P | O | R | T | M | A | P | P | E | R |
NALEN = 10
VABUF = (address of:)
0x00 | 0x01 | 0x86 | 0xa0 |
VALEN = 4
The PURGE instance of the DIRSRV macro instruction is used to purge a previously issued asynchronous DIRSRV request. The DNR searches for the DPL and completes the request.
[symbol] DIRSRV PURGE,| PURGE | Indicates that the DNR is to purge a previously issued DIRSRV request. |
| MF = (E, [dpl_address]) | Indicates the execute form of the PURGE macro instruction. The second sublist operand, dpl address, specifies the address of the parameter list to purge.
Note: It is recommended to use the list form of the macro to ensure DPL alignment on a full word boundary. If you do not use the list form, make sure you align the storage area used for the remote parameter list on a fullword boundary. This will ensure that the internal ECB is aligned on a fullword boundary. Default: MF=E |
This table lists the symbolic return codes for the PURGE macro. The values associated with the symbolic names can be found in the DPL macro expansion.
| General Return Code | Recovery Action Code | Conditional Or Specific Error Code | ||
|---|---|---|---|---|
| DROKAY | DAOKAY | DCOKAY | ||
| DRFAILED | DAENVIRO | DESYSERR | ||
|
|