VAX/VMS ACNET Network Services Software Documentation Memo # 64.2 ACNET Network Services VAX/VMS User's Manual Version 5.4A (UTI) Frank J. Nagy (original) Glenn C. Johnson (revision) March 16, 1994 In collaboration with Charlie I. Briegel Copyright (c) 1992 Universities Research Association, Inc. All Rights Reserved Network Services User's Manual Page ii This manual describes the calling sequences of the VAX/VMS ACNET network services. The reader is assumed to be familiar with the ACNET Network Services FORTRAN User's Manual for the ACNET calling sequences for FORTRAN users along with an introduction to the ACNET network. The descriptions in this manual are meant primarily for the MACRO user. However, like the VMS system services, the VAX/VMS ACNET routines can be called from any High- Level Language (such as FORTRAN or C) that provides the capability to pass arguments to procedures by immediate value in addition to by address (also known as "by reference"). The reader should also be familiar with the Introduction to VMS System Services. In particular, the reader should read Chapters 1 and 2 which describe the conventions for calling VMS system services as similar conventions are followed for the ACNET network services. Additional information can be found in Introduction to the VMS Run-Time Library as to procedure calling conventions. The reader should also examine Chapters 4 and 5 of Introduction to VMS System Services to be familiar with event flags and AST's (Asynchronous System Traps) as these items are used by the network services in interacting with user programs. "Would you tell me, please, which way I ought to go from here?" "That depends a good deal on where you want to get to," said the Cat. Alice's Adventures in Wonderland Lewis Carroll Change History: 29.1 23-May-82 Corrected Table D.1, added Chapter 5. 29.1A 25-May-82 Change JRADIX50 to $JRADIX50 29.2 27-May-82 Correct text in Chapter 5, add $.RAD50S macro, add NET_TRN_NODENAME, NET_TRN_NODE, and RAD50_TO_ASCII routines. 29.3 25-Jun-82 Cleanup and expand some descriptions. Removed AST restrictions. 40.0 26-Jan-83 Change from ACNET Design Note to Software Documentation Memo. Cleanup and several additions and changes of a minor nature. 64.1 30-Jul-91 Reflect changes made for ACNET upgrade 64.2 20-Dec-93 Multiple RUM connect and other changes Network Services User's Manual Page iii Table of Contents CONTENTS CHAPTER 1 INTRODUCTION TO NETWORK SERVICES 1.1 Overview of VAX/VMS ACNET . . . . . . . . . . . . 1-1 1.2 Summary of VAX/VMS ACNET Network Services . . . . 1-2 1.2.1 Global Network Services . . . . . . . . . . . . 1-2 1.2.2 Requestor Network Services . . . . . . . . . . . 1-2 1.2.3 Replier Network Services . . . . . . . . . . . . 1-3 1.2.4 Miscellaneous Network Services . . . . . . . . . 1-3 1.2.5 Multiple RUM-connections . . . . . . . . . . . . 1-4 1.3 Calling Network Services from VMS MACRO . . . . . 1-4 1.4 Calling Network Services from High-Level Languages 1-6 1.5 Linking With VAX/VMS ACNET Network Services . . . 1-7 1.5.1 Using the UTI Shareable Image . . . . . . . . . 1-7 CHAPTER 2 EVENT FLAGS AND AST'S 2.1 Event Flags and Network Services . . . . . . . . . 2-1 2.2 AST's and Network Services . . . . . . . . . . . . 2-1 2.2.1 User Reply AST Block . . . . . . . . . . . . . . 2-2 2.2.2 User Request AST Block . . . . . . . . . . . . . 2-3 2.2.3 UAB Flags Byte . . . . . . . . . . . . . . . . . 2-4 2.2.4 UAB Request Length . . . . . . . . . . . . . . . 2-6 2.3 AST Usage and Side Effects . . . . . . . . . . . . 2-6 2.4 Enabling and Disabling . . . . . . . . . . . . . . 2-7 CHAPTER 3 CONDITION CODES 3.1 Network Service Completion Codes . . . . . . . . . 3-1 3.2 Reply Status Codes and Condition Codes . . . . . . 3-1 3.3 Special Condition Code Meanings . . . . . . . . . 3-2 CHAPTER 4 NETWORK SERVICE DESCRIPTIONS 4.1 $NET_CAN - Cancel Request . . . . . . . . . . . . 4-4 4.2 $NET_CNCT - Connect to the network . . . . . . . . 4-6 4.3 $NET_CREQ - Check the status of a request . . . 4-10 4.4 $NET_CRPY - Check on the status of a reply . . . 4-13 4.5 $NET_DCNT_S - Disconnect from the network . . . 4-16 4.6 $NET_GTID - Get logical task id . . . . . . . . 4-18 4.7 $NET_GTNM - Get network task name . . . . . . . 4-21 4.8 $NET_HANDLE - Set the default handle . . . . . . 4-23 4.9 $NET_RREQ - Receive request change . . . . . . . 4-25 4.10 $NET_RRPY - Receive reply change . . . . . . . . 4-28 4.11 $NET_SEND - Send an unsolicited special message 4-31 4.12 $NET_SREQ - Send a request . . . . . . . . . . . 4-33 4.13 $NET_SRPY - Send a reply . . . . . . . . . . . . 4-37 Network Services User's Manual Page iv Table of Contents 4.14 $NET_STAT_S - Convert ACNET Global Status to 32-bit form . . . . . . . . . . . . . . . . . . 4-41 4.15 $NET_STS16_S - Convert 32-bit status to 16-bit form . . . . . . . . . . . . . . . . . . . . . . 4-44 4.16 $NET_WREQ - Wait for the receipt of a request . 4-46 4.17 $NET_WRPY - Wait on the reception of a reply . . 4-49 4.18 $JRADIX50 - Convert ASCII to Radix-50 representation . . . . . . . . . . . . . . . . . 4-51 CHAPTER 5 NETWORK LIBRARY ROUTINES 5.1 NET_RPYSTS_TEST - Check reply status for retry . . 5-2 5.2 NET_TRN_NODE - Translate logical node number into name . . . . . . . . . . . . . . . . . . . . . . . 5-3 5.3 NET_TRN_NODENAME - Translate name into logical node number . . . . . . . . . . . . . . . . . . . 5-4 5.4 NTV_LCL_RETRY - Check for local retryable condition . . . . . . . . . . . . . . . . . . . . 5-5 5.5 NTV_RMT_RETRY - Check for remote retryable condition . . . . . . . . . . . . . . . . . . . . 5-7 5.6 NTV_STS32 - Convert 16-bit status to 32-bit form . 5-9 5.7 RAD50_TO_ASCII - Convert from Radix-50 to ASCII 5-10 APPENDIX A Additional Macros A.1 $.RAD50L - Generate .LONG of Radix-50 text . . . . A-2 A.2 $.RAD50S - Generate symbol with Radix-50 value . . A-2 A.3 $.RAD50W - Generate .WORD of Radix-50 text . . . . A-2 A.4 CASE - Generate a CASEx instruction and dispatch list . . . . . . . . . . . . . . . . . . . . . . . A-3 A.5 POPREG - Pop a longword from stack into a register A-4 A.6 Definitions Macros . . . . . . . . . . . . . . . . A-5 A.6.1 $ARB_DEF . . . . . . . . . . . . . . . . . . . . A-5 A.6.2 $ART_DEF . . . . . . . . . . . . . . . . . . . . A-6 A.6.3 $LNN_DEF . . . . . . . . . . . . . . . . . . . . A-7 A.6.4 $MSGHDR_ALTDEF . . . . . . . . . . . . . . . . . A-8 A.6.5 $MSGHDR_DEF . . . . . . . . . . . . . . . . . . A-8 A.6.6 $NET_DEF . . . . . . . . . . . . . . . . . . . . A-8 A.6.7 $NETAGS_DEF . . . . . . . . . . . . . . . . . . A-8 A.6.8 $UAB_DEF . . . . . . . . . . . . . . . . . . . . A-9 APPENDIX B FORTRAN and C Considerations B.1 INCLUDE Files . . . . . . . . . . . . . . . . . . B-1 B.1.1 MSGTYPDEF . . . . . . . . . . . . . . . . . . . B-1 B.1.2 $NETAGS_DEF . . . . . . . . . . . . . . . . . . B-1 B.1.3 NODEDEFS . . . . . . . . . . . . . . . . . . . . B-2 B.1.4 REQRPYFLG . . . . . . . . . . . . . . . . . . . B-2 B.1.5 $SSDEF and $NET_DEF . . . . . . . . . . . . . . B-2 B.1.6 UABFLGDEF . . . . . . . . . . . . . . . . . . . B-2 B.2 EXTERNAL Symbols (FORTRAN) . . . . . . . . . . . . B-3 Network Services User's Manual Page v Table of Contents APPENDIX C Request and Reply Identification Codes APPENDIX D VMS Condition Codes and ACNET Global Status CHAPTER 1 INTRODUCTION TO NETWORK SERVICES 1.1 Overview of VAX/VMS ACNET The reader is assumed to be familiar with the FORTRAN User's Manual for ACNET network services. That document describes the FORTRAN by-reference entry points that return ACNET Global Status. Those entry points for the network services are (aside from the names) identical under both VAX/VMS and RSX-11M to provide for easy transport of code between the two systems. The FORTRAN User's Manual also provides an introduction to the philosophy used in the design of the ACNET network and discusses the concepts involved in using network services. A few very important points are repeated here for reference: 1. A user program must be "connected" to the network in order to use any network services. 2. A single user program may be either a requestor of information from other network users or a replier to such requests. A single user program may in fact perform both types of operations without having to perform an additional "network connect" operation. 3. ACNET uses three types of messages. Request messages are unsolicited messages which solicit information that is returned as reply messages. Unsolicited special messages (USM's) are used to convey control information for which a reply is not needed. 4. The ACNET network uses several different message packet sizes. The traditional "small" packet allows for 268 16-bit data words (supplied by the network user). A larger "ethernet" packet permits 739 16-bit data words (supplied by the network user). On token-ring machines (only), a "large" packet permits 1991 16-bit data words (supplied by the network user). These token-ring machines do not support the "ethernet" packet size. A single message, which is too large to fit in a single "ethernet" or "large" packet, may be broken into multiple packets. ACNET guarantees that messages containing up to 1991 16-bit data words (exclusive of header) can be properly transmitted over the network. INTRODUCTION TO NETWORK SERVICES Page 1-2 Overview of VAX/VMS ACNET 5. The packetting of long messages is invisible to users, but they should be aware of the packet size, as said messages take longer to be processed. 6. Network addresses consist of logical trunk and node numbers which determine which computer system is the destination, and a network task name (or logical task id) which determines which network user on that computer system is to receive the message. 7. Network node numbers in the range 240-255 (decimal) are reserved for multicast messages. For these pseudo-nodes, the trunk number is ignored. Only unsolicited special messages (USM's) which do not require any packetting may be sent to a multicast node. Certain nodes may not support multicast messages. Please consult with the network manager for a list of currently-supported multicast nodes. 1.2 Summary of VAX/VMS ACNET Network Services The ACNET network services constitute the User Task Interface (UTI) between a user task (or process) and the network. These services can be broken into four general categories based on their usage. They are categorized here in terms of which type of network users need to call the services. 1.2.1 Global Network Services These network services are called by all users of the network. The services that fall in this category include: o Connect to the network ($NET_CNCT) o Disconnect from the network ($NET_DCNT) 1.2.2 Requestor Network Services A requestor task makes use of these services to solicit information from other network users (the "repliers"). A user program connected to the network is automatically capable of being a requestor. A single request may have only a single reply or may invoke an indefinite stream of replies (a multiple-reply request). Those services concerned with the support of requestors are: INTRODUCTION TO NETWORK SERVICES Page 1-3 Summary of VAX/VMS ACNET Network Services o Send a request message ($NET_SREQ) o Check on a reply ($NET_CRPY) o Wait on receipt of a reply ($NET_WRPY) o Change reply buffer parameters ($NET_RRPY) o Cancel an outstanding request ($NET_CAN) 1.2.3 Replier Network Services A "replier" task services requests from other network user programs. Such a network user is said to be "connected to be able to receive unsolicited messages, or RUM-connected". This is to be contrasted with the act of sending a request (itself an unsolicited message) in that the reply to that request is solicited by the sending of the request. The network services used by repliers to receive and answer requests are: o Setup to receive requests or change receive buffer ($NET_RREQ) o Send a reply to a request ($NET_SRPY) o Check on receipt of a request or USM ($NET_CREQ) o Wait on receipt of a request or USM ($NET_WREQ) o Change the default network handle ($NET_HANDLE) Note that no special service is provided to perform the "RUM- connect" operation. A RUM-connect is performed implicitly by the very first use of the $NET_RREQ network service. A further feature to be noted is that repliers can receive either request messages or USM's. 1.2.4 Miscellaneous Network Services o Return logical task id ($NET_GTID) o Return network task name ($NET_GTNM) o Send a special unsolicited message ($NET_SEND) o Convert reply status to VMS completion code ($NET_STAT) INTRODUCTION TO NETWORK SERVICES Page 1-4 Summary of VAX/VMS ACNET Network Services o Convert VMS status to ACNET Global Status ($NET_STS16) 1.2.5 Multiple RUM-connections A single task can support multiple receive-unsolicted-message (RUM) channels, with each connection having its own unique task name, or "handle". The limit on the maximum number of RUM- connections is installation defined, and is currently set to ten. Each RUM-connection will have its own receive buffer, and may have its own AST routine and event flag as well. Replier tasks can take advantage of this feature to define separate receive buffers for each different type of request that it expects to field. Under this scheme, a single receive buffer being locked will have no effect on the other connections. A task defines additional handles by using the $NET_CNCT network service with a non-null task name (handle) for each connection. After the handle is defined by $NET_CNCT, the task must use the $NET_HANDLE network service to switch to the newly-defined handle, and then issue the $NET_RREQ network service to actually perform the RUM-connect on this handle. 1.3 Calling Network Services from VMS MACRO The use of the VAX/VMS ACNET network services from routines written in MACRO32 is patterned after the rules for using VMS system services from MACRO code. The reader should therefore be familiar with Chapter 2 of the Introduction to VMS System Services which describes, in general terms, the use of the macros which define the system service calls. The network service macros generate argument lists and CALL instructions to invoke network service routines. The macros are located in the macro library VAXNET.MLB stored in SYS$LIBRARY. This macro library must be explicitly invoked on the MACRO command line by: $ MACRO... ...,SYS$LIBRARY:VAXNET/LIBRARY,... or via an explicit reference in a source module using the .LIBRARY directive of MACRO32: .LIBRARY "SYS$LIBRARY:VAXNET.MLB" The description of each service indicates the positional dependencies and the keyword names for the arguments used by the macro for that service: INTRODUCTION TO NETWORK SERVICES Page 1-5 Calling Network Services from VMS MACRO $NET_name arga, [argb], [argc], argd where the square bracket notation is used to indicate optional arguments. If optional arguments are omitted, default values will be supplied or the argument list will be shortened if the optional arguments are omitted from the end of the list of arguments. The names shown with the macros are may be used as keywords in the macro call. There are two forms of the macros used to call the VAX/VMS ACNET network services: $NET_name_G $NET_name_S The "_G" form requires that an argument list be constructed elsewhere in the program, usually using the macro form: $NET_name With this form, the same argument list can be used for more than one invocation of the macro. Like the VMS system service macros, the "$NET_name" macro will generate an argument list using .LONG and .ADDRESS directives and so the macro argument values must be specified accordingly. The "_S" form requires that the arguments be supplied in the call of the macro. The macro generates the code necessary to construct the argument list on the call stack during the execution of the program. This form is useful when the arguments or pointer to the arguments are contained within the general registers. In particular the "_S" forms are useful in writing re-entrant routines. The argument values supplied to the "$NET_name_S" macros become operands to instructions to push values or addresses onto the stack. If an address is expected, then a PUSHAx instruction (x is one of B, L, Q, or W for byte, longword, quadword, or word data type) is used to place the address onto the stack. The macro argument value must be a valid operand for the PUSHAx instruction. If a value is expected, then a PUSHL instruction is used if the macro argument is one of: 1. a longword value, 2. a small constant ("#n") such that short literal addressing mode can be used, or 3. a general register (the value must have stored in the register with a MOVZxL instruction if the value is not a longword). Otherwise the instruction "MOVZxL src,-(SP)" is used to move the value (src) onto the stack (x is the data type of the value and is either B for byte values or W for word values). INTRODUCTION TO NETWORK SERVICES Page 1-6 Calling Network Services from VMS MACRO The macro "$NET_nameDEF" can be called to define symbols for the argument list offsets. These symbols have the names composed from the network service name and the argument keyword: NET_name$_keyword An additional symbol defines the maximum number of arguments expected by the network service: NET_name$_NARGS though many of the network services can take argument lists with fewer than the maximum number of arguments. The "$NET_nameDEF" macro is called as part of the expansion of the "$NET_name" macro to automatically define the argument list offsets. The network services return a completion status code in register R0 in the same manner as the VMS system services. Many of these status codes are system signal names ("SS$_ident") returned by VMS system services and either passed back to the caller or adopted for return by the network services (where the meaning is appropriate). In other cases, network specific signals have been created with names of the form: NET__ident See the chapter on "CONDITION CODES" later in this manual for more details. 1.4 Calling Network Services from High-Level Languages VAX/VMS ACNET provides two methods for High-Level Languages to use network services by providing two separate sets of entry points to the network service routines. One set has been described in the ACNET Network Services FORTRAN User's Manual. This set of entry points provides for passing all arguments in "by-reference" fashion (see below) and will not be discussed further here. The second set of entry points are the same as those used by the network service macros in the CALL instructions they generate. Using these entry points from a High-Level Language is very similar to using VMS system services from a High-Level Language. The reader should therefore be familiar with Section 2.8 of the Introduction to VMS System Services. The MACRO entry points to the VAX/VMS ACNET network services accept arguments in three forms: i. By immediate value. This form is generated in FORTRAN by use of the %VAL argument list function. The actual value of the argument is placed INTRODUCTION TO NETWORK SERVICES Page 1-7 Calling Network Services from High-Level Languages into the argument list. This form is only used for procedure input arguments. ii. By address (also known as "by reference"). This is the normal form for procedure arguments setup by FORTRAN. The address of the memory location(s) where the argument is stored is placed in the argument list. This form is used for procedure output arguments. iii. By address of a descriptor. This form is used for complicated arguments. The most common example of such is a string of ASCII text. FORTRAN passes CHARACTER strings with descriptors. The only network service that uses this argument form is $JRADIX50. The choice of form by which an argument is passed is made by the network service, not the caller. In the description of the network service arguments, an argument is passed by value unless the description explicitly describes the argument as "the address of ...". The MACRO entry points return a completion status code in register R0. In the High-Level Languages, if the network service is used as a function, then the function value is the completion status code. An important point to note is that the value returned by the functions is a longword integer (INTEGER*4 in FORTRAN). 1.5 Linking With VAX/VMS ACNET Network Services This section describes the methods by which the VAX/VMS ACNET network services are linked into a user's executeable image (program). These instructions are appropriate to both MACRO and High-Level Language programmers. 1.5.1 Using the UTI Shareable Image The normal method of linking to the VAX/VMS ACNET network services is to use the UTI Shareable Image. This method saves physical memory as only one copy of the code is shared among all the processes using the network services. In addition, changes to the UTI code may be installed without (usually) having to relink all the executeable images that call the network services. However, not all of the network services are linked into the UTI shareable image. In particular, the modules containing the FORTRAN entry points (all arguments are passed by reference) are not currently installed in the UTI. To use these services or entry points, the UTI object library in SYS$LIBRARY called VAXNETUTI.OLB must be searched by the linker. INTRODUCTION TO NETWORK SERVICES Page 1-8 Linking With VAX/VMS ACNET Network Services The simpliest method of linking to the network services is to use a LINK command of the following form which specifies that the LINK options are to be read from the file VAXNETUTI.OPT in SYS$LIBRARY. $ LINK file1,file2,...,SYS$LIBRARY:VAXNETUTI/OPTIONS The items file1, file2, etc. in the LINK command are file specifications for object module files and libraries containing other code for the executeable image. If other LINK options must be used, then the contents of the VAXNETUTI.OPT options file must be included in the user's LINK options. This options file contains the single line: SYS$SHARE:UTI/SHARE,SYS$LIBRARY:VAXNETUTI/LIBRARY which must be included in a program-specific options file input to the VMS linker. CHAPTER 2 EVENT FLAGS AND AST'S 2.1 Event Flags and Network Services Event flags and their use with VMS system services are described in Chapter 4 of the Introduction to VMS System Services. Event flags may also be used with VAX/VMS ACNET network services to indicate when an unsolicited message (request or USM) has been received in the receive buffer or a reply message has been placed in a reply buffer. Event flag zero (0) can not be used with the network services (specifying event flag 0 is treated as specifying no event flag). The event flag number is entered as an immediate value in the argument list of a network service. See the section on "Enabling and Disabling" for important information on retaining the current event flag number or setting it to zero to disable event flag usage. IMPORTANT NOTE! Local event flags 22 and 23 are used internally by the network services. 2.2 AST's and Network Services Asynchronous System Traps (AST's) and their use in VMS system services are described in Chapter 5 of the Introduction to VMS System Services. The network makes use internally of an executive-mode AST, called the network AST, to perform network operations in the context of a user process. In addition, user- mode AST's can be called by the VAX/VMS ACNET network as end- action routines called when an unsolicited message has been delivered to the receive buffer or a reply has been delivered to a reply buffer. The use of these user AST's is under control of the caller of the network services in that the address of the AST routine is provided by the caller in the network service argument list. If an address of zero (0) is given, then the particular user AST is disabled and will not be called by the network services. EVENT FLAGS AND AST'S Page 2-2 AST's and Network Services The internal network AST can not be disabled as it is a fundamental part of the VAX/VMS ACNET network. This AST is executed in EXECUTIVE mode (as opposed to USER mode normally used by a user process) for three reasons: 1. The network AST can not be disabled from a USER mode call to $SETAST. 2. The network AST can be executed even whilst in the middle of a USER mode AST routine since (in such a case) only USER mode AST's are queued for later delivery. 3. The network AST requires serial access to certain network data structures. The network User AST's are declared as normal USER mode AST's using the VMS $DCLAST system service. These AST's are queued for sequential delivery in the normal fashion for AST's. The AST parameter (see the Introduction to VMS System Services) for the network User AST's is the address of data structure called the User AST Block (UAB). This is a read-only data structure and must not be written into by the User AST routine. The format of the UAB for reply AST's and request AST's is described in the following sections. The symbolic names for the UAB offsets are defined by the $UAB_DEF macro in VAXNET.MLB. The notation used for symbol names of the UAB offsets follows a VMS standard in which a name consists of a structure identifier, data type identifier and data name or identifier. In the case of the UAB these have the format: "UAB_type_name". Offsets into the UAB use the data type (byte, word, longword, or quadword) as the type portion of the symbol name ("_B_", "_W_", "_L_", or "_Q_") so we have symbols like: UAB_W_RPYLEN, or UAB_L_RPYADR as shown below. Constants are defined by a data type of "_K_". In the case of the UAB, the symbol "UAB_L_LENGTH" gives the length of the UAB in bytes. 2.2.1 User Reply AST Block User AST's called as the result of the delivery of a reply are called with their AST parameter pointing to a UAB whose format is shown in Figure I. EVENT FLAGS AND AST'S Page 2-3 AST's and Network Services Note that the network provides a pointer to the reply buffer in the UAB. This can be used to write re-entrant routines by embedding the reply buffer in a larger data structure and then calculating the address of this "outer" data structure using the pointer from the UAB. This eliminates the need to save the address of the reply buffer in a "common" block for the reply AST thus allowing the same AST routine to potentially service several separate requests. Figure I Format of User AST Block for Replies 15 0 +---------------------------------+ | UAB_W_REQID | +---------------------------------+ | UAB_W_RPYLEN | +---------------------------------+ | UAB_L_RPYADR | + + | | +----------------+----------------+ | UAB_B_FLAGS | UAB_B_RPYSTS | +----------------+----------------+ | ACNET Global Status | +---------------------------------+ | | +---------------------------------+ | | +---------------------------------+ | | +---------------------------------+ | | +---------------------------------+ 2.2.2 User Request AST Block User AST's called as the result of the delivery of an unsolicited message (a request or a USM) into an active receive buffer. The AST parameter points to a UAB whose format is shown in Figure II. Note that the network provides a pointer to the receive buffer in the UAB. This can be used to write re-entrant routines by embedding the receive buffer in a larger data structure and then calculating the address of this "outer" data structure using the pointer from the UAB. EVENT FLAGS AND AST'S Page 2-4 AST's and Network Services Figure II Format of User AST Block for Requests and USM's 15 0 +---------------------------------+ | UAB_W_RPYID | +---------------------------------+ | UAB_W_REQLEN | +---------------------------------+ | UAB_L_REQADR | + + | | +----------------+----------------+ | UAB_B_FLAGS | UAB_B_REQSTS | +----------------+----------------+ | UAB_B_D.TSKID | UAB_B_D.NODE | +----------------+----------------+ | UAB_W_RRQID | +---------------------------------+ | UAB_B_S.TSKID | UAB_B_S.NODE | +----------------+----------------+ | unused | +---------------------------------+ | UAB_B_S.LAN | UAB_B_D.LAN | +---------------------------------+ | UAB_L_TASKNM | + + | | +---------------------------------+ 2.2.3 UAB Flags Byte Figures III and IV show the format of the UAB flags byte (UAB_B_FLAGS) returned in the UAB for both replies and unsolicited messages. The "UAB_V_name" symbols specify the bit offsets (bit number starting with 0) of the bit or field of the UAB flags byte. The "UAB_M_name" symbols then define masks for single bits or fields of bits (useful in bit-wise AND operations) of the UAB flags byte. The "UAB_S_MSGTYPE" symbol defines the size of the MSGTYPE field in bits. EVENT FLAGS AND AST'S Page 2-5 AST's and Network Services Figure III Format of UAB_B_FLAGS byte for Replies 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | 1 | T | | | | | | M | | S | O | | | | | | U | | T | O | | | | | | L | | P | L | | | | | | T | | K | O | | | | | | R | | T | N | | | | | | P | | | G | | | | | | Y | +---+---+---+---+---+---+---+---+ Figure IV Format of UAB_B_FLAGS byte for Requests and USM's 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | C | T | | | M | M | | A | O | | | S | U | | N | O | | | G | L | | C | L | | | T | T | | E | O | | | Y | R | | L | N | | | P | P | | | G | | | E | Y | +---+---+---+---+---+---+---+---+ The CANCEL bit and the MSGTYPE fields of the FLAGS byte are only used for Request AST's and may have undetermined values for Reply AST's. The 1STPKT bit is only used with Reply AST's. The 1STPKT bit is set when the first (in time) packet of the reply message has been stored in the reply buffer. The first packet reply AST is used to inform the user that the reply buffer is now corrupted. When the final packet of a long reply is stored into the reply buffer, then the normal reply AST will be delivered (the entire reply message has been received). The reply buffer contents are unuseable while the packets of the long reply message are being received and stored (between the declaring of the first packet AST and the final reply AST). For single packet replies, no first packet AST is declared as the entire reply message is stored in one operation. The generating of first packet reply AST's is enabled by the FCPAST request option (see below). The UAB flags byte is in the same format as the lower byte of the flags word returned via the optional flgadr arguments of the network services $NET_WREQ, $NET_CREQ, $NET_WRPY, and $NET_CRPY. For replies only the TOOLONG and MULTRPY flags have any meaning. EVENT FLAGS AND AST'S Page 2-6 AST's and Network Services 2.2.4 UAB Request Length The value in UAB_W_REQLEN contains the length of the request message (in words), and should be considered volitile. If a CANCEL is received for a request-type message while that message is being serviced by a user-mode AST, the request length in the UAB will be cleared to zero right in the middle of the AST routine. The AST programmer can eliminate any potential problems by making a local copy of the request length. Multiple references to UAB_W_REQLEN should be avoided. 2.3 AST Usage and Side Effects Since the UAB's provide pointers to the reply and receive buffers (see above), one can write fully re-entrant AST routines since the need to provide a dedicated "common" holding a pointer to the reply (or receive) buffer is eliminated. This is true even in FORTRAN where dealing with pointers is a bit of a bother (see the FERMILIB routines for providing indirect memory accessing via pointers stored in INTEGER*4 variables). As of the present time, experience has not turned up any problems with re-entrancy of the code-support FORTRAN runtime routines although no effort has been made to see if OPEN's can (for instance) be done at both AST and non-AST levels in the same program. When the internal network AST declares the User Reply AST, it does not directly call the user's routine but declares an additional internal (user-mode in this case) network AST routine which then CALL's the user's AST routine. This was done to handle the recovery of network resources by expended requests after the User Reply AST had completed. After returning from the user AST routine, if the request was a single-reply request or if a multiple-reply request received a reply with the MULTRPY cleared (a so-called ENDMULT reply), then the request is considered to be expended and is deleted. The network resources used by the request are recovered for later use. A network user task which receives requests and USM's provides one or more receive buffers. The mechanism of receive buffer locking is used by the network to insure that a new request (or USM) does not overwrite the current request being processed. However, it is the responsibility of the user to inform ACNET that the buffer is capable of receiving a new message by unlocking the receive buffer. This can be done in several ways in conjunction with the User Request AST: 1. By sending a reply to the request in the buffer. This implicitly unlocks the buffer and assumes that the user has (if necessary) saved the information from the request someplace else. EVENT FLAGS AND AST'S Page 2-7 AST Usage and Side Effects 2. By establishing a new receive buffer (this is the most often used method in User Request AST's) by invoking the $NET_RREQ service. 3. By expliciting unlocking the existing receive buffer (again by calling the $NET_RREQ service). This form is most commonly used when a CANCEL request message has been received. When a USM (or a request CANCEL) has been received, the receive buffer must be explicitly unlocked by a call to $NET_RREQ (to just unlock the buffer or to declare a new receive buffer). As in the case of the User Reply AST, the user-mode network AST which actually calls the user's AST routine provides for the recovery of expended network resources. In the case of the Request AST, this happens after delivering a USM or a request CANCEL. The elimination of expended requests (at the receiver end) is accomplished in the $NET_SRPY service, not at the user- mode network AST level. If a network user task has defined multiple RUM-connections, the network will perform an implicit $NET_HANDLE service upon entry to the User Request AST. The AST routine, therefore, can always assume that the correct handle context has been established. When the AST routine returns, the previous handle context is automatically restored. 2.4 Enabling and Disabling The arguments to network service routines that specify an event flag number and a User AST address always occur at the end of the argument list for a network service that accepts such arguments. A non-zero event flag number or User AST address enables the use of the event flag or the declaring of the User AST and replaces any previously set value for either parameter. If both arguments are not specified, then the argument list passed to the network service routine is shortened and the current event flag number and User AST address are retained with no change. This is referred to as "implicitly" defaulting the event flag number and User AST address arguments to leave the current values unchanged. In a macro call these arguments are "implicitly" defaulted by just leaving them off the list of arguments (positional or keyword) used in the particular macro call. For a High-Level Language they are also left off the list of arguments in the call without even specifying commas for them. Note that if an event flag number is specified, then the User AST address (always the last argument) may still be "implicitly" defaulted. EVENT FLAGS AND AST'S Page 2-8 Enabling and Disabling One of the other, or both, of the event flag number and AST address arguments may be "explicitly" defaulted. This is done by using "#0" for the event flag number and "0" for the User AST address in a macro call: $NET_RREQ ...,efn=#0,astadr=0 By "explicitly" defaulting these arguments, no event flag is used by the network service and no User AST routine is called. For some High-Level Languages (such as FORTRAN) these arguments are explicitly defaulted by providing commas for them in the argument list but no values: status = NET_RECEIVE_REQUEST(...,,) Note that if the User AST is to be disabled by either method shown above, then a non-zero value for the event flag number must be used to prevent the event flag from also being disabled. CHAPTER 3 CONDITION CODES 3.1 Network Service Completion Codes VMS system services and VAX/VMS ACNET network services return 32-bit longword completion status codes in register R0. These codes are also known as signal names and are part of the VAX-11 condition handling standard. More information on VAX-11 condition codes may be found in the VAX Architecture Handbook in Section C.4, and in the Introduction to VMS System Services in Section 2.6. Chapter 4 of the VMS RTL Library (LIB$) Manual also describes VAX-11 condition generation and condition handling in more detail. The VMS system service signal names (completion codes) are defined by the $SSDEF macro in the system macro library (STARLET.MLB). These names are of the form: SS$_ident and are also defined as global symbols in the system object module library (STARLET.OLB). The signal names defined by VAX/VMS ACNET network are defined in the $NET_DEF macro in VAXNET.MLB macro library and as global symbols in the VAXNETUTI.OLB object module library. The network signal names have the form: NET__ident The description of each network service lists the status codes it can return upon completion. 3.2 Reply Status Codes and Condition Codes Some ACNET status information is passed between remote nodes in the form of a 16-bit ACNET Global Status in the message header. The upper byte of the ACNET Global Status word is the error code (negative indicates an error, zero for complete success, and positive for conditional success). The lower byte of the ACNET Global Status contains the facility number. The entire word will contain a zero if there is complete success. These reply status CONDITION CODES Page 3-2 Reply Status Codes and Condition Codes codes are translated into VMS condition codes using the $NET_STAT network service which is automatically called by the $NET_Cxxx and $NET_Wxxx (xxx are REQ or RPY) network services. 3.3 Special Condition Code Meanings SS$_INTERLOCK is used (in different routines) to indicate that data structures are currently locked by the user for modification. This also can happen by mixing certain network service calls in non-AST and AST level code. The particular network services involved here are $NET_RREQ and $NET_RRPY. Each of these locks a particular data structure in order to insert new values into fields of the data structure. Thus the user can get SS$_INTERLOCK returned from either of these services by calling the services from an AST routine which just happens to execute while a non-AST level call to the same service was partially completed. This can not and will not be removed from VAX/VMS ACNET. User's of VAX/VMS ACNET network services must either avoid this problem (call the services from either only non-AST or AST level code, not both) or provide their own handling of possible SS$_INTERLOCK error returns. Associated with the modification interlock discussed in the previous paragraph, the $NET_RREQ and $NET_RRPY network services can return the SS$_EXQUOTA or SS$_INSFMEM condition codes due to attempts to declare a network AST when the modification interlock is cleared. The network AST is used to process message packet buffers that have been queued to the interlocked data structure by the network process (ACNET). Thus these condition codes are returned for precisely the same reason that the $DCLAST system service will return the same codes. The return of these condition codes is affected by the setting of Resource Wait mode. Normally, Resource Wait mode is enabled causing a process to go into a wait state until the particular resource (VMS dynamic memory or AST quota in this case) is available. Resource Wait mode can be enabled or disabled with the $SETRWM system service. CHAPTER 4 NETWORK SERVICE DESCRIPTIONS This part of the manual describes each of the VAX/VMS network services. The network services are presented in alphabetical order by their MACRO names. The reader is assumed to be familiar with the FORTRAN calls to the network services described in the ACNET Network Services FORTRAN User's Manual document and with the VAX/VMS system services described in the VAX/VMS System Services Reference Manual. Each network service description consists of the following categories, as applicable. Some services require detailed information beyond these categories. For these services, additional information appears after the "Notes" section. Macro Format Shows the macro name, with all keyword arguments listed in positional order. High-Level Language Format Shows the procedure name and a generalized format for calling the service from a high-level language, with all arguments listed in positional order. These forms of the network service calling sequences (unlike those described in the FORTRAN User's Manual) use mixed argument lists in which some of the arguments are passed by immediate value and others by address (by reference). Arguments Describes each of the arguments. Arguments passed by reference (address) are distinguished by those passed by immediate value by the key phase "address of" in the description of the argument. NETWORK SERVICE DESCRIPTIONS Page 4-2 Return Status Lists the possible completion status codes with an explanation of the returned condition. The successful returns are listed first (in alphabetical order) followed by the warning and severe error return status codes (also in alphabetical order). All status codes are severe errors, unless otherwise indicated. Several condition codes are common to almost all the routines (the exceptions are noted for individual routines). These condition codes are: NET__NOTCNCT Not connected to network. SS$_ACCVIO An address for the request (or reply) identification word was not specified (only for those services which have the request id or reply id as an argument). SS$_INSFARG One or more required arguments are missing. SS$_NONEXPR Warning, the network process (named NETPROCESS) does not exist. Note that the network process must be running for VAX/VMS ACNET to function. SS$_SSFAIL There is no XSC (eXtended System Common) block installed in VMS nonpaged dynamic memory. The XSC block must be installed for VAX/VMS ACNET to function (usually installed at system startup). In addition, several of the routines can return condition codes that are indicative of errors that are internal to VAX/VMS ACNET and should never happen (we hope). In particular, NET__BUGCHECK may be returned by several network services due to an internal programming error rather than a user-caused programming error. Similarly, SS$_VECINUSE may be returned by some network services. This is also internal network error caused by the buffer pointer's save vector already being in use. This should not happen unless AST's are being used in different processor modes (User, Supervisor, Executive, and Kernel) simultaneously. NETWORK SERVICE DESCRIPTIONS Page 4-3 Notes Contains the "fine print" of the service description, as well as references to related services or additional information. NETWORK SERVICE DESCRIPTIONS Page 4-4 $NET_CAN - Cancel Request 4.1 $NET_CAN - Cancel Request Cancels a specified outstanding request. Macro Format $NET_CAN reqidadr High-Level Language Format NTV_CANCEL_REQUEST(reqidadr) reqidadr address of a word which contains a valid request identification code of the outstanding request to be cancelled. Return Status SS$_WASCLR Success, the request was already marked for deletion. SS$_WASSET Success, the request has been deleted locally and the cancellation message sent to the remote destination. NET__BUGCHECK Internal network error. NET__NOBUFFER Warning, no free buffers available to construct the cancellation message. NET__NOSUCHREQ No such request, as given by the request id, found for this user process. NET__NOTREQID Not a request identification code. SS$_VECINUSE Internal network error caused by the buffer pointer's save NETWORK SERVICE DESCRIPTIONS Page 4-5 $NET_CAN - Cancel Request vector being in use. Notes A cancellation message (of type USM) is constructed and sent to the destination of the original request to stop the sending of any further replies. The request is then locally deleted. NETWORK SERVICE DESCRIPTIONS Page 4-6 $NET_CNCT - Connect to the network 4.2 $NET_CNCT - Connect to the network Connect a process to the network, specify a new network task name for an already connected process, or create a new network handle for the already connected process. Macro Format $NET_CNCT [tsknam] High-Level Language Format NTV_CONNECT([tsknam]) tsknam longword value specifying the network task name with which the user process is to be connected to the network. The network task name is given as 6 Radix-50 characters in the longword. If this argument is not given, the the first 6 characters of the VMS process name are converted to Radix-50 and used as the network task name. If the task is already connected, the task name argument will be used to define a new network "handle" for the task. Return Status SS$_NORMAL Service successfully completed NET__BUGCHECK Internal network error. NET__NOCTLBLK No free control blocks available (can occur only when renaming a RUM-connected process). NET__NOTALLMAP Not all of NETCOMMON was mapped successfully (can occur during UTI init). NET__RUMNAMEXI Another RUM-connected process with the same network task name already exists. NETWORK SERVICE DESCRIPTIONS Page 4-7 $NET_CNCT - Connect to the network NET__HANLSTFUL Connection failed because handle list full. NET__TSKLSTFUL Cannot connect to network as no logical task ids are available. SS$_EXQUOTA Paging file quota exceeded in mapping NETCOMMON (can occur during UTI init). SS$_INSFWSL Insufficient working set limit to allow expansion of P0 region to map NETCOMMON (can occur during UTI init). SS$_LCKPAGFUL System limit on number of locked pages reached (can occur during UTI init). SS$_NOPRIV Cannot allow access (or requested type of access) to the NETCOMMON global section (can occur during UTI init). SS$_NOSUCHSEC Warning, the NETCOMMON global section does not exist (can occur during UTI init). SS$_OPINCOMPL NETCOMMON not completely locked into memory (can occur during UTI init). SS$_VASFULL Virtual address space of the process is full, no room exists to map NETCOMMON (can occur during UTI init). Possible internal error returns: SS$_BADPARAM, SS$_INTERLOCK, SS$_INVLOGNAM, SS$_IVSECFLG, SS$_IVSECIDCTL, SS$_SHMNOTCNCT, SS$VECINUSE, or SS$_TOOMANYLNAM NOTE: NET__NOTCNCT cannot be returned by this service. NETWORK SERVICE DESCRIPTIONS Page 4-8 $NET_CNCT - Connect to the network Notes 1. The first call to this routine will invoke the network initialization for the user process (UTI init). This consists of mapping to the NETCOMMON global section and initializing some process-local information. The NETCOMMON global section contains the control blocks and buffers used by VAX/VMS ACNET and is the means by which information passes between a VMS user process and the network process (NETPROCESS). NETPROCESS is that portion of the VAX/VMS ACNET network which provides the interface to the remote systems and implements the message packet routing. 2. If a tsknam argument is not given (and no prior connection exists), then the first 6 characters of the VMS process name are converted to Radix-50. This is termed a "SOFT connection" because the user did not provide an explicit task name. If the first character of the VMS process name is an underscore ("_") as in "_JOB696", then the 6 characters starting with the second character (after the underscore) are converted to Radix-50. The conversion to Radix-50 is terminated prematurely (before 6 characters have been converted) by the end of the process name string or the occurrence of a non- Radix-50 character. 3. If $NET_CNCT is called with no arguments when the user process is already connected to the network, then the network service will just return success (without doing anything). This feature permits layered software to insure that a user process is connected to the network before using network services without disturbing any network connection established explicitly by the user process. 4. A "hard connection" to the network is created when the user supplies an explicit task name argument. A SOFT connection is promoted to a HARD connection by either of the following methods: o $NET_CNCT is called with a valid tsknam argument, which replaces the task name generated from the VMS process name. o $NET_RREQ is called, which creates a Receive Unsolicited Message (RUM) connection. 5. If a HARD network connection exists and $NET_CNCT is called with a valid tsknam argument, then the network service will create a new "handle" for the task using this argument. These handles are used to support multiple Receive Unsolicited Message (RUM) connections. Please note: the default handle is initially set to the first HARD task name, and will NOT be changed by any subsequent $NET_CNCT service call. The user must explicitly call the $NET_HANDLE network service in order NETWORK SERVICE DESCRIPTIONS Page 4-9 $NET_CNCT - Connect to the network to change the default handle. 6. While a network task may have multiple handles (each of which has the structure of a network task name), it has only a single "official" network task name. This official network task name is always identical to the first defined handle. 7. The $NET_CNCT network service must never be called from any AST routine IF it is being called with the purpose of creating a new handle. NETWORK SERVICE DESCRIPTIONS Page 4-10 $NET_CREQ - Check the status of a request 4.3 $NET_CREQ - Check the status of a request Check on the status of the receive buffer of a RUM-connected process. The receive buffer is either unlocked and waiting for a request or unsolicited special message (USM) or is locked by an unsolicited message or request that has been placed in it. Macro Format $NET_CREQ rpyidadr, [lenadr], [nodadr], [flgadr], [reqidadr], [srcadr] High-Level Language Format NTV_CHECK_REQUEST(rpyidadr, [lenadr], [nodadr], [flgadr], [reqidadr], [srcadr]) rpyidadr address of a word in which the reply identification code is returned. The reply identification is to be used when sending a reply to a request. This word is cleared for unsolicited special messages (USM's). lenadr address of a word in which the length of the request or unsolicited message is returned. The length is given in words. nodadr address of a word in which the destination logical node number of the request or unsolicited special message is returned. The upper byte of this word contains the LAN-ID (or Trunk), and the lower byte contains the actual logical node value. flgadr address of a word in which the message flags are returned in the low order byte. See the UAB flags byte for the format of these flags. reqidadr address of a word in which the request identification is returned. For unsolicited special messages the contents of the message identification field of the message header are returned (they have no special meaning for the ACNET network). NETWORK SERVICE DESCRIPTIONS Page 4-11 $NET_CREQ - Check the status of a request srcadr address of a word in which the message source address is returned. The source logical node number is returned in the low order byte and the source logical task id in the upper byte. The source LAN-ID (or trunk) is not returned. Return Status SS$_WASCLR Receive buffer is locked by an old USM, one that has been processed. SS$_WASSET Receive buffer is locked by a request or a new USM that has been completed (completely received) but not yet been processed. 0 (zero) Receive buffer is empty and unlocked. NET__BUGCHECK Internal network error. NET__NOSUCHREQ Receive buffer is locked, but not by any known request or USM. NET__NOTCNCT Not connected to the network. NET__NOTRUM Not connected to receive unsolicited messages (not setup as a RUM process). NET__REQTRUNC Warning, request message truncated to fit in receive buffer. SS$_ACCVIO Address of word for the reply identification not provided. NETWORK SERVICE DESCRIPTIONS Page 4-12 $NET_CREQ - Check the status of a request Notes 1. If the $NET_CREQ service returns the condition code zero (0) to indicate a pending state for the receive buffer, no values are returned in the arguments. 2. A RUM process uses one or more receive buffers to accept unsolicited messages (both requests and USM's). If more than one handle/receive-buffer has been defined for the network task, the user must select the appropriate handle (using $NET_HANDLE) prior to invoking the $NET_CREQ service. A receive buffer is considered to have two possible states: i. Unlocked and able to receive a new message, or ii. Locked and either actively receiving a new message or contains a completed message. The transition from unlocked to locked is made internally in the VAX/VMS UTI routines by the network AST. The transition back to the unlocked state is made at the explicit or implicit behest of the user. This can be done by explicitly calling the $NET_RREQ service to specify a new receive buffer (which by definition is initially unlocked) or to unlock the current buffer if no new buffer address is specified. The receive buffer may be implicitly unlocked by calling the $NET_SRPY service to send a reply to the request which is locking the receive buffer. If the receive buffer is locked by a USM, only the $NET_RREQ service can be used to unlock the buffer. 3. When a "new" unsolicited message is received by ACNET, a reply control block is allocated to contain control information about the request or USM. When the $NET_CREQ returns a non- pending status (either SS$_WASSET or NET__REQTRUNC) for a new USM, the reply control block is deleted but the receive buffer remains locked. A second call to $NET_CREQ will then return SS$_WASCLR since the USM is now considered to "have been processed". The reply block for a request will not be deleted until the request is cancelled or the final (or only) reply to the request is sent. NETWORK SERVICE DESCRIPTIONS Page 4-13 $NET_CRPY - Check on the status of a reply 4.4 $NET_CRPY - Check on the status of a reply Check on the status (pending or received) of a reply to a specified outstanding request. Macro Format $NET_CRPY reqidadr, [lenadr], [flgadr], [stsadr] High-Level Language Format NTV_CHECK_REPLY(reqidadr, [lenadr], [flgadr], [stsadr]) reqidadr address of a word which contains the request identification code of the request for which the reply status is to be checked. lenadr address of a word in which the length of the reply is returned. The length is given in words. flgadr address of a word in which the message flags are returned in the low order byte. See the UAB flags bytes for the format of these flags. stsadr address of a word in which the ACNET Global Status (reply status) from the message header is returned. Return Status SS$_NORMAL Success, reply has been received. 0 (zero) Reply not yet received. NET__BUGCHECK Internal network error. NET__NOSUCHREQ NETWORK SERVICE DESCRIPTIONS Page 4-14 $NET_CRPY - Check on the status of a reply No such request exists as given by the request identification. NET__NOTCNCT Not connected to the network. NET__NOTREQID Not a request identification code. SS$_ACCVIO Address of a word for the request identification not specified. SS$_ILLEFC Illegal event flag number. SS$_UNASEFC Process not connected to the event flag cluster with the specified event flag number. See $NET_STAT_S for a list of the condition codes returned due to the reply status returned in the reply message header. Notes 1. If the $NET_CRPY service returns the condition code zero (0) to indicate a pending state for the receive buffer, no values are returned in the arguments. 2. If a reply has been received, then the $NET_CRPY service will clear the DONE bit for the reply and clear the event flag (if any) specified for the reply with the $NET_SREQ service. These actions are taken to insure that the next call to $NET_CRPY will return a "pending" status until a new reply message is received. 3. The request is deleted after a call to $NET_CRPY if a a reply has been received and: i. the request has only a single reply, or ii. the reply is the final reply for a multiple-reply request. Basically, the request is deleted if the reply message has the MULTRPY bit cleared in the message header of the reply. This can be forced by using the ENDMULT reply option of the $NET_SRPY service. NETWORK SERVICE DESCRIPTIONS Page 4-15 $NET_CRPY - Check on the status of a reply 4. The stsadr argument is used to allow the raw value of the ACNET Global Status (reply status) to be accessed. This is important if the replier, to whom the request was made, can return status information in the reply status word. In such a case, one of the NET__USRINFO or NET__SUPSINFO condition codes is used as the completion status code of the $NET_CRPY service and the user must look at the ACNET Global Status for further information. NETWORK SERVICE DESCRIPTIONS Page 4-16 $NET_DCNT_S - Disconnect from the network 4.5 $NET_DCNT_S - Disconnect from the network Disconnects the network task from the network. Only the "_S" form of the macro is defined. Macro Format $NET_DCNT_S High-Level Language Format NTV_DISCONNECT() Return Status SS$_WASCLR Success, disconnected from network. SS$_WASSET Success, already disconnected. NET__BUGCHECK Internal network error. NET__NOBUFFER No free buffers available for use in sending request cancellation messages to other nodes. SS$_INTERLOCK Process is already waiting for a transmission to complete. This can occur if the service is called from an AST routine while a transmission is in progress from a non-AST routine. SS$_VECINUSE Internal network error caused by the buffer pointer's save vector being in use. Notes Before the user process is disconnected from the network, all outstanding requests are terminated. Requests made from this user process to other network tasks are cancelled in the same fashion as the $NET_CAN network service. Requests made to this process are terminated by a status-only reply with a NETWORK SERVICE DESCRIPTIONS Page 4-17 $NET_DCNT_S - Disconnect from the network reply status of DISCON. NETWORK SERVICE DESCRIPTIONS Page 4-18 $NET_GTID - Get logical task id 4.6 $NET_GTID - Get logical task id Return the logical task id for a particular network task on this or some other system (using a logical node number). Macro Format $NET_GTID [lognode], [tsknam], tskid High-Level Language Format NTV_GET_TASKID([lognode], [tsknam], tskid) lognode word value giving the logical node and LAN-ID from which the logical task id is to be returned. The upper byte of this word must contain the LAN-ID (trunk), and the lower byte must contain the logical node. The default is to use the current local node. tsknam longword value with the Radix-50 representation of the network task name whose logical task id is to be returned. If this is defaulted, the network task name of the user process itself (must be connected to the network) will be used. tskid address of a byte in which the logical task id is returned. Return Status SS$_NORMAL Service successfully completed, logical task id returned. NET__BUGCHECK Internal network error. NET__IOERROR Error, retryable I/O error. NET__NOBUFFER NETWORK SERVICE DESCRIPTIONS Page 4-19 $NET_GTID - Get logical task id No free buffers available to construct ACNET request message. NET__NOCTLBLK No free control blocks available to setup ACNET request. NET__NODEDOWN Error, destination logical node down. NET__NOMEMRMT Error, no memory available at remote node. NET__REQTBLFUL No table space available to setup ACNET request. NET__SYSERR Error, system service or directive error (probably at remote system). SS$_COMMHARD Hard communications I/O error. SS$_INTERLOCK Already awaiting the completion of a transmission. SS$_NOSUCHNODE No such logical node known. SS$_NOSUCHOBJ No such network task known. Possible internal error returns: SS$_BADPARAM, SS$_MSGNOTFND, SS$_VECINUSE, NET_BUGCHECK, NET_ILLACNCOD, NET_NOMSG, NET_NORPYBUF, NET_NOTREQID, NET_RPYTRUNC, or NET_TOOLONG. Notes 1. If the logical node specified is on a remote system, normal network services are used to send an ACNET Request Block to the ACNET task on the remote system to response with a reply giving the logical task id. NETWORK SERVICE DESCRIPTIONS Page 4-20 $NET_GTID - Get logical task id 2. The logical task id is used internally by the network to identify connected user processes (tasks). The external address of a user process (task) is given by its network task name which is assigned by the user at the time the process is connected to the network. At this time, the network then assigns a logical task id as the internal address of the user process. Thus on a single system there is a one-to-one mapping between logical task ids and network task names. NETWORK SERVICE DESCRIPTIONS Page 4-21 $NET_GTNM - Get network task name 4.7 $NET_GTNM - Get network task name Return the network task name for a task connected on a specified logical node and having a specified logical task id. Macro Format $NET_GTNM [lognode], [tskid], tsknam High-Level Language Format NTV_GET_TASKNAME([lognode], [tskid], tsknam) lognode word value giving the logical node and LAN-ID from which the network task name is to be returned. The upper byte of this word must contain the LAN-ID (trunk), and the lower byte must contain the logical node. The default is to use the current local node. tskid byte value giving the logical task id for which the task name is to be returned. If defaulted, then a logical task id of zero is used and the network task name of ACNET (in Radix-50) is returned. tsknam Address of a longword in which the network task name associated with the logical task id is returned (as 6 Radix-50 characters). Return Status SS$_NORMAL Service successfully completed, network task name returned. NET__BUGCHECK Internal network error. NET__IOERROR Error, retryable I/O error. NET__NOBUFFER NETWORK SERVICE DESCRIPTIONS Page 4-22 $NET_GTNM - Get network task name No free buffers available to construct ACNET request message. NET__NOCTLBLK No free control blocks available to setup ACNET request. NET__NODEDOWN Error, destination logical node down. NET__NOMEMRMT Error, no memory available at remote node. NET__REQTBLFUL No table space available to setup ACNET request. NET__SYSERR Error, system service or directive error (probably at remote system). SS$_COMMHARD Hard communications I/O error. SS$_INTERLOCK Already awaiting the completion of a transmission. SS$_NOSUCHNODE No such logical node known. SS$_NOSUCHOBJ Logical task id not in use. Possible internal error returns: SS$_BADPARAM, SS$_MSGNOTFND, SS$_VECINUSE, NET_BUGCHECK, NET_ILLACNCOD, NET_NOMSG, NET_NORPYBUF, NET_NOTREQID, NET_RPYTRUNC, or NET_TOOLONG. Notes If the logical node specified is on a remote system, normal network services are used to send an ACNET Request Block to the ACNET task on the remote system to response with a reply giving the network task name. NETWORK SERVICE DESCRIPTIONS Page 4-23 $NET_HANDLE - Set the default handle 4.8 $NET_HANDLE - Set the default handle Change the current default network handle for subsequent service calls involving a receive request buffer. Multiple handles are created by calls to $NET_CNCT with non-null task names. These task names become the handles which are used to create multiple receive unsolicited message (RUM) connections. Macro Format *NOT AVAILABLE* High-Level Language Format NTV_HANDLE(handle, [ohanadr]) handle longword value specifying the network handle (normally in Radix-50 characters) which is to become the default for future network calls. This handle must have been previously defined by $NET_CNCT (NTV_CONNECT). ohanadr address of a longword in which the old default handle is to be returned. Return Status SS$_NORMAL Service successfully completed SS$_INSFARG Insufficient arguments: must supply the handle argument NET__ASTACTIVE Cannot perform function at AST level NET__NOSUCHHAN No such handle exists in table SS$_BADPARAM Bad $GETJPI parameter (internal network bug) NETWORK SERVICE DESCRIPTIONS Page 4-24 $NET_HANDLE - Set the default handle Notes When a USM or request type message is received and a network AST routine is called, the handle is temporarily changed to that of the incoming message for the duration of the AST routine. NTV_HANDLE must never be called from any AST routine. NETWORK SERVICE DESCRIPTIONS Page 4-25 $NET_RREQ - Receive request change 4.9 $NET_RREQ - Receive request change Change the receive parameters for requests and unsolicited messages. The first time this is used after a network connect ($NET_CNCT), the process is connected as a RUM-style network task. This allows the process to Receive Unsolicited Messages (RUM). If a network task has defined multiple handles, this service must be called for EACH handle in order to define multiple receive buffers. Macro Format $NET_RREQ [reqadr], [maxlen], [efn], [astadr] High-Level Language Format NTV_RECEIVE_REQUEST([reqadr], [maxlen], [efn], [astadr]) reqadr address of the buffer in which the request (or unsolicited special messages) message contents are returned. This becomes the address of the current receive buffer of the RUM- task. If defaulted, then the previously specified address is used for the receive buffer (may not be defaulted on the first call). maxlen value specifying the length of the receive buffer and the maximum acceptable length of a request (or unsolicited special) message contents. The length is specified in words. If defaulted, then the previously specified length is used for the receive buffer (may not be defaulted on the first call). efn event flag number to be set when a request or unsolicited special message has been received. If set to zero (or explicitly defaulted), then no event flag is set when the receive buffer is full. astadr address of the user request AST which is called when a request or unsolicited special message is received. The AST parameter for the user request AST is the address of the request form of the UAB. NETWORK SERVICE DESCRIPTIONS Page 4-26 $NET_RREQ - Receive request change Return Status SS$_NORMAL Service successfully completed NET__BUGCHECK Internal network error. NET__NOBUFR A receive buffer of non-zero length must be specified on the first call to this service (when RUM-connecting). NET__NOCTLBLK No free control blocks available to establish the RUM- connect. NET__RUMLSTFUL Cannot RUM-connect as RUM task list full. NET__RUMNAMEXI Cannot RUM-connect as network task name already in use by another RUM task. SS$_EXQUOTA AST quota exceeded while attempting to declare network AST. SS$_ILLEFC Illegal event flag number. SS$_INSFARG Insufficient number of arguments (can only occur on initial call to the service). SS$_INSFMEM Insufficient VMS dynamic memory to declare network AST. SS$_INTERLOCK The RUM Connect Block is locked for modification by a partially completed call to $NET_RREQ. SS$_UNASEFC Process not associated with event flag cluster containing the NETWORK SERVICE DESCRIPTIONS Page 4-27 $NET_RREQ - Receive request change specified event flag number. SS$_VECINUSE Internal network error caused by the control block pointer's save vector being in use (can only occur when doing the initial RUM-connect). Notes 1. The first call to the $NET_RREQ network service implicitly performs the RUM connection operation (establishes to the network that this process can Receive Unsolicited Messages). At this time the a receive buffer must be specified. A network control block is allocated and becomes the RUM Connect Block for this RUM task. 2. If more than one handle has been defined for the network task, the user must select the appropriate handle (using $NET_HANDLE) prior to invoking the $NET_RREQ service. Each handle may have its own unique receive buffer, event flag, and AST address (but they could be shared). 3. The event flag number and User Request AST address may be explicitly defaulted (or set to zero) to disable either one. Implicit defaulting, by leaving the argument(s) off the call, results in preserving the current values in the RUM Connect Block. 4. A call to $NET_RREQ with all arguments defaulted will simply unlock the receive buffer (for the current default handle). 5. If a buffer address but no length is specified (on any except the initial call), then the previous buffer length is used. Thus a multi-buffering scheme for the receive buffer can be implemented using $NET_RREQ to specify a new buffer address (but same buffer length) when a message is received. 6. Any call to the service will unlock the receive buffer (a newly specified receive buffer is initially unlocked). If an event flag is specified for the receive buffer (or was specified in some earlier call and not cleared), then that event flag is cleared. 7. If message packet buffers are queued to the RUM Connect Block when the modification lock is removed by this service, then the process's network AST will be invoked to deliver the unsolicited message represented by those message packets. The completion status' SS$_EXQUOTA and SS$_INSFMEM will be returned only if Resouce Wait mode is disabled. The normal case is for the process to be placed in a resouce wait state by VMS until the particular resource (AST quota or VMS dynamic memory) becomes available. NETWORK SERVICE DESCRIPTIONS Page 4-28 $NET_RRPY - Receive reply change 4.10 $NET_RRPY - Receive reply change Change the parameters concerned with receiving the reply (or replies) for a specified outstanding request. Macro Format $NET_RRPY reqidadr, [rpyadr], [maxlen], [efn], [astadr] High-Level Language Format NTV_RECEIVE_REPLY(reqidadr, [rpyadr], [maxlen], [efn], [astadr]) reqidadr address of a word containing the request identification code for which the reply receive buffer or other parameters are modified. rpyadr address of the new reply buffer. If defaulted, then the address of the reply buffer is unchanged. maxlen size of the new reply buffer in words. If defaulted, then the size of the reply buffer is left unchanged. efn number of an event flag to be sent when a reply is received. If the event flag is set to 0, then no event flag will be set when a reply is received. astadr address of the User Reply AST routine which is called when a reply is received. Return Status SS$_NORMAL Service successfully completed NET__NOSUCHREQ No such request exists as given by the request identification NETWORK SERVICE DESCRIPTIONS Page 4-29 $NET_RRPY - Receive reply change code. NET__NOTREQID Not a request identification code. SS$_CANCEL Warning, request has been cancelled or ended and is being deleted. SS$_EXQUOTA Insufficient AST quota to declare network AST to deliver reply. SS$_ILLEFC Illegal event flag number. SS$_INSFARG Not enough arguments were supplied to the service. SS$_INSFMEM Insufficient VMS dynamic memory to declare network AST to deliver reply. SS$_INTERLOCK Request Block is already locked for modification by a partially completed call to $NET_RRPY. SS$_UNASEFC Process not associated with event flag cluster with the specified event flag number. Notes 1. Calling this routine will clear the done bit for the reply and (if any) the event flag associated with the reply buffer. 2. The event flag number and User Request AST address may be explicitly defaulted (or set to zero) to disable either one. Implicit defaulting, by leaving the argument(s) off the call, results in preserving the current values in the Request Block. 3. If a buffer address but no length is specified (on any except the initial call), then the previous buffer length is used. Thus a multi-buffering scheme for the reply buffer can be implemented using $NET_RRPY to specify a new buffer address NETWORK SERVICE DESCRIPTIONS Page 4-30 $NET_RRPY - Receive reply change (but same buffer length) when a message is received. 4. If message packet buffers are queued to the Request Block when the modification lock is removed by this service, then the process's network AST will be invoked to deliver the unsolicited message represented by those message packets. The completion status' SS$_EXQUOTA and SS$_INSFMEM will be returned only if Resouce Wait mode is disabled. The normal case is for the process to be placed in a resouce wait state by VMS until the particular resource (AST quota or VMS dynamic memory) becomes available. 5. If the reply AST is disabled, then the FCPAST option will be cancelled for the request. NETWORK SERVICE DESCRIPTIONS Page 4-31 $NET_SEND - Send an unsolicited special message 4.11 $NET_SEND - Send an unsolicited special message Send an unsolicited special message (USM). Macro Format $NET_SEND [lognode], [tsknam], msgadr, msglen High-Level Language Format NTV_SEND([lognode], [tsknam], msgadr, msglen) lognode byte value giving the destination logical node number and LAN-ID (trunk). The upper byte of this word must contain the LAN-ID (trunk), and the lower byte must contain the logical node. The default value is the default logical node of the local system. tsknam longword value giving the network task name in Radix-50 representation of the destination task (or process). The default value is the network task name of the process from which this service is called. msgadr address of the buffer containing the message contents to be sent as an unsolicited special message. msglen word value giving the length of the message contents in words. Return Status SS$_NORMAL Service successfully completed NET__BUGCHECK Internal network error. NET__NOBUFFER No free buffers available to construct the message. NETWORK SERVICE DESCRIPTIONS Page 4-32 $NET_SEND - Send an unsolicited special message NET__NOMSG No user message buffer or message of length zero specified. NET__TOOLONG Message is too long for network. SS$_INSFARG Not enough arguments were supplied to the service. SS$_INTERLOCK Already waiting for a transmission to complete. SS$_NOSUCHNODE No such destination logical node known. SS$_VECINUSE Internal network error caused by the buffer pointer's save vector being in use. Notes This service should be used with great care as USM's are thrown away by the network with no notification if they cannot be delivered. NETWORK SERVICE DESCRIPTIONS Page 4-33 $NET_SREQ - Send a request 4.12 $NET_SREQ - Send a request Send a request message and setup the buffer and the parameters used in receiving the reply (or replies) to the request. Macro Format $NET_SREQ [lognode], [tsknam], [reqflg], reqadr, reqlen, reqidadr, rpyadr, maxlen, [efn], [astadr] High-Level Language Format NTV_SEND_REQUEST([lognode], [tsknam], [reqflg], reqadr, reqlen, reqidadr, rpyadr, maxlen, [efn], [astadr]) lognode word value giving the destination logical node number and LAN-ID (trunk). The upper byte of this word must contain the LAN-ID (trunk), and the lower byte must contain the logical node. The default value is the default logical node of the local system. tsknam longword value giving the network task name in Radix-50 representation of the destination task (or process). The default value is the network task name of the process from which this service is called. reqflg word value of bit flags used to select options for the request. reqadr address of the buffer containing the message to be sent as a request. reqlen word value giving the length of the request message in words. The length of the request message can not be zero. reqidadr address of a word in which the request identification code is returned. rpyadr NETWORK SERVICE DESCRIPTIONS Page 4-34 $NET_SREQ - Send a request address of a user buffer in which the reply message is to be received. A reply buffer must be specified when sending a request. maxlen word value giving the size of the reply buffer in words. This can not be zero. efn number (if non-zero) of an event flag to be set when a reply is received. astadr address of the User Reply AST routine to be called when a reply is received. Return Status SS$_NORMAL Service successfully completed NET__BUGCHECK Internal network error. NET__NOBUFFER No free buffers available to construct the message. NET__NOCTLBLK No free control blocks available to construct Request Block. NET__NOMSG No user message buffer or message of length zero specified. NET__NORPYBUF No reply buffer address specified, or reply buffer of length zero specified. NET__REQTBLFUL No table space available to define a new request. NET__TOOLONG Message is too long for network. NETWORK SERVICE DESCRIPTIONS Page 4-35 $NET_SREQ - Send a request SS$_ACCVIO Address of a word for the request identification not specified. SS$_ILLEFC Illegal event flag number. SS$_INTERLOCK Already awaiting the completion of a transmission. SS$_NOSUCHNODE No such destination logical node known. SS$_VECINUSE Internal network error caused by the buffer or control block pointers' save vector being in use. SS$_UNASEFC Process is not associated with the event flag cluster containing the specified event flag number. Notes 1. A control block is allocated to be the Request Block in which the reply buffer parameters are placed. These parameters are used to return the reply message in the reply buffer specified in the $NET_SREQ service call. 2. The request option flags defined are: REQ_V_MULTRPY - multiple-reply request. REQ_V_NOBSYWT - do not queue request to busy task. REQ_V_FCPAST - enable first packet reply ASTS. The symbols REQ_V_MLT and REQ_V_NBW are alternate names for those listed above. The "_V_" symbols define the option bits as bit offsets while the "_M_" symbols define the option bits as masks. If MULTRPY is not set, then the request is ended (and deleted) when the single reply is received. If MULTRPY is set, then the request is not ended until it is either explicitly cancelled or and reply is sent with the ENDMULT reply option (see $NET_SRPY). If NOBSYWT is set, then the request will not be queued to the destination task if its receive buffer is locked. Instead, NETWORK SERVICE DESCRIPTIONS Page 4-36 $NET_SREQ - Send a request NOBSYWT causes a status-only reply with the reply status TASKBUSY to be returned as the reply. If FCPAST is set, then first packet AST's will be declared for long reply messages. Figure V Request Options Bits 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | | | | | | F | N | M | | | | | | | C | O | U | | | | | | | P | B | L | | | | | | | A | S | T | | | | | | | S | Y | R | | | | | | | T | W | P | | | | | | | | T | Y | +---+---+---+---+---+---+---+---+ NETWORK SERVICE DESCRIPTIONS Page 4-37 $NET_SRPY - Send a reply 4.13 $NET_SRPY - Send a reply Send a reply to a request. Macro Format $NET_SRPY rpyidadr, [rpyflg], [rpyadr], [rpylen], [rpysts] High-Level Language Format NTV_SEND_REPLY(rpyidadr, [rpyflg], [rpyadr], [rpylen], [rpysts]) rpyidadr address of a word containing the reply identification code. rpyflg word value containing reply option bits. rpyadr address of the buffer containing the message to be returned as the reply. If not specified, a status-only reply is returned. rpylen word value giving the length of the reply message in words. If defaulted or zero is specified, a status-only reply is returned. rpysts word value giving the ACNET Global Status (reply status) value. If defaulted, the reply status is NETAGS_K_SUC or NETAGS_K_END (see Notes). Return Status SS$_NORMAL Service successfully completed. NET__BUGCHECK Internal network error. NET__NOBUFFER NETWORK SERVICE DESCRIPTIONS Page 4-38 $NET_SRPY - Send a reply No free buffers available to construct message. NET__NOMSG No reply message address, but a non-zero length was specified. NET__NOSUCHREQ No such request for reply. NET__NOTRPYID Not a reply identification code. NET__NOTRUM Not connected to receive unsolicited messages (not RUM- connected). NET__TOOLONG Message too long for network. SS$_ACCVIO Address of a reply identification word not specified. SS$_CANCEL Warning, request already cancelled. SS$_ILLEFC Illegal event flag number. SS$_INTERLOCK Already waiting for a transmission to complete. SS$_NOSUCHNODE No such logical destination node. SS$_VECINUSE Internal network error caused by the buffer pointer's save vector being in use. SS$_UNASEFC Process is not associated with the event flag cluster containing the specified event flag number. NETWORK SERVICE DESCRIPTIONS Page 4-39 $NET_SRPY - Send a reply Notes 1. The reply option flags defined are: RPY_V_ENDMULT - terminate multiple-reply request. RPY_V_LOCKED - do not unlock receive buffer. The symbols RPY_V_EMR and RPY_V_BRL are alternate names for those listed above. The "_V_" symbols define the option bits as bit offsets while the "_M_" symbols define the option bits as masks. If ENDMULT is set, then the request is ended by clearing the MULTRPY flag bit in the message header and setting the reply status to NETAGS_K_END (only if it would otherwise have the value NETAGS_K_SUC). If LOCKED is set, then the receive buffer is not unlocked by the sending of the reply. Figure VI Reply Options Bits 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | | | | | | | L | E | | | | | | | | O | N | | | | | | | | C | D | | | | | | | | K | M | | | | | | | | E | U | | | | | | | | D | L | | | | | | | | | T | +---+---+---+---+---+---+---+---+ 2. The receive buffer of the RUM process may be implicitly unlocked by calling the $NET_SRPY service to send a reply to the request which is locking the receive buffer. The conditions required for the $NET_SRPY service to unlock the receive buffer are: a. the receive buffer must be locked, b. the reply option flag LOCKED must not be selected (clear), and c. the request identification for which the reply is being sent must match that of the request locking the buffer (also the source node and logical task ids must match). 3. If the receive buffer is unlocked, any event flag to be set when an unsolicited message is received is cleared. 4. The condition code SS$_CANCEL can be returned if the USM cancelling the request was received but has not yet been processed by the user program. In this case, the "request" NETWORK SERVICE DESCRIPTIONS Page 4-40 $NET_SRPY - Send a reply may be queued to a locked receive buffer. Or the "request" may be in the receive buffer (locking it) awaiting processing by a (queued) user AST or by a call to $NET_CREQ or $NET_WREQ. This "request" will have the CANCEL bit set in the flags byte which is to be used to inform the user program to delete its own references to this request. When the user AST has completed (or $NET_CREQ or $NET_WREQ return), then the network will delete the request itself. NETWORK SERVICE DESCRIPTIONS Page 4-41 $NET_STAT_S - Convert ACNET Global Status to 32-bit form 4.14 $NET_STAT_S - Convert ACNET Global Status to 32-bit form Converts the 16-bit ACNET Global Status (reply status) to a 32-bit return status. This routine is called by the $NET_CRPY and $NET_WRPY routines. Only the "_S" form of this macro is defined. Macro Format $NET_STAT_S rpysts High-Level Language Format NTV_STATUS(rpysts) rpysts word value of the ACNET Global Status (reply status) from the reply message header. Return Status NET__ENDMLTRPY Informational, this was the final reply in a set of multiple replies. NET__SUPSINFO Informational, a reply status code specific to support software was returned. NET__USRINFO Informational, a reply status code specific to user software was returned. SS$_MSGNOTFND Success, unknown reply status code returned. SS$_NORMAL Success, reply status of OK returned. NET__DISCONING Warning, replier task being disconnected. NET__ILLACNCOD NETWORK SERVICE DESCRIPTIONS Page 4-42 $NET_STAT_S - Convert ACNET Global Status to 32-bit form Illegal or unknown ACNET request typecode or sub-function value. NET__INCWRTPWD Incorrect ACNET WRITE function password. NET__IOERROR Error, retryable I/O error. NET__NODEDOWN Error, destination logical node down. NET__NOMEMRMT Error, no memory available at remote node. NET__NOSUCHREQ No such request known. NET__REQPKTERR Warning, request message packet assembly error. NET__REQTRUNC Warning, request message truncated. NET__RPYPKTERR Warning, reply message packet assembly error. NET__RPYTBLFUL Warning, request failed due to no room in reply tables at the remote node for the reply. NET__RPYTRUNC Warning, reply message truncated. NET__SYSERR Error, system service or directive error (probably at remote system). NET__TASKBUSY Warning, request failed because the destination task was busy (only returned if the request option NOBSYWT was selected). NETWORK SERVICE DESCRIPTIONS Page 4-43 $NET_STAT_S - Convert ACNET Global Status to 32-bit form NET__TSKQFUL Warning, request failed because the destination task's receive buffer queue was full. SS$_BADPARAM Bad value or address in an ACNET request block. SS$_COMMHARD Hard communications I/O error. SS$_NOSUCHNODE No such logical node. SS$_NOSUCHOBJ No such task at destination node. SS$_TIMEOUT Request timed-out while queued for receive buffer. NETWORK SERVICE DESCRIPTIONS Page 4-44 $NET_STS16_S - Convert 32-bit status to 16-bit form 4.15 $NET_STS16_S - Convert 32-bit status to 16-bit form Converts a 32-bit VMS condition code to a 16-bit ACNET Global Status. Only the "_S" form of this macro is defined. Macro Format $NET_STS16_S sts32 or MOVL #sts32,R0 ;Input is in register R0 JSB G^NTV_STS16_R1 High-Level Language Format NTV_STS16(sts32) NET_STS16(stsadr) sts32 longword value of the 32-bit VMS condition code (or status) to be converted to 16-bit ACNET Global Status. stsadr Address of a longword containing the VMS condition code. Return Status No status is returned, instead register R0 contains the ACNET Global Status as a 32-bit longword (sign-extended from 16- bits). The upper byte of the ACNET Global Status word is the error code (negative indicates an error, zero for complete success, and positive for conditional success). The lower byte of the ACNET Global Status contains the network's facility number (1). Notes 1. The mapping from VMS condition codes to ACNET Global Status is not a one-to-one mapping. Some of the VMS condition codes returned by the NTV network services are not converted to the same Global Status words by this service as compared to the Global Status values returned by the NET network services (see the FORTRAN User's Manual). NETWORK SERVICE DESCRIPTIONS Page 4-45 $NET_STS16_S - Convert 32-bit status to 16-bit form 2. The NTV_STS16_R1 routine is called by a JSB instruction (or one of the BSBx instructions) and provides MACRO programmers which a more efficient calling sequence. The routine's single input parameter, the 32-bit VMS condition code, is passed in register R0. The routine also uses register R1 (the routine name thus follows the convention for JSB entry points described in the VAX-11 Run-Time Library Reference Manual). NETWORK SERVICE DESCRIPTIONS Page 4-46 $NET_WREQ - Wait for the receipt of a request 4.16 $NET_WREQ - Wait for the receipt of a request Wait until a request or an unsolicited special message has been received and the receive buffer is locked. Macro Format $NET_WREQ rpyidadr, [lenadr], [nodadr], [flgadr], [reqidadr], [srcadr] High-Level Language Format NTV_WAIT_REQUEST(rpyidadr, [lenadr], [nodadr], [flgadr], [reqidadr], [srcadr]) rpyidadr address of a word in which the reply identification code is returned. The reply identification is to be used when sending a reply to a request. This word is cleared for unsolicited special messages (USM's). lenadr address of a word in which the length of the request or unsolicited message is returned. The length is given in words. nodadr address of a word in which the destination logical node number of the request or unsolicited special message is returned. The upper byte of this word contains the LAN-ID (or Trunk), and the lower byte contains the actual logical node value. flgadr address of a word in which the message flags are returned in the low order byte. See the UAB flags byte for the format of these flags. reqidadr address of a word in which the request identification is returned. For unsolicited special messages the contents of the message identification field of the message header are returned (they have no special meaning for the ACNET network). srcadr NETWORK SERVICE DESCRIPTIONS Page 4-47 $NET_WREQ - Wait for the receipt of a request address of a word in which the message source address is returned. The source logical node number is returned in the low order byte and the source logical task id in the upper byte. The source LAN-ID (or trunk) is not returned. Return Status SS$_WASCLR Receive buffer is locked by an old USM, one that has been processed. SS$_WASSET Receive buffer is locked by a request or a new USM that has not yet been processed. NET__BUGCHECK Internal network error. NET__NOSUCHREQ Receive buffer is locked, but not by any known request or USM. NET__NOTCNCT Not connected to the network. NET__NOTRUM Not connected to receive unsolicited messages (not setup as a RUM process). NET__REQTRUNC Warning, request message truncated to fit in receive buffer. SS$_ACCVIO Address of word for the reply identification not provided. Notes 1. A RUM process uses one or more receive buffers to accept unsolicited messages (both requests and USM's). If more than one handle/receive-buffer has been defined for the network task, the user must select the appropriate handle (using $NET_HANDLE) prior to invoking the $NET_WREQ service. A receive buffer is considered to have two possible states: NETWORK SERVICE DESCRIPTIONS Page 4-48 $NET_WREQ - Wait for the receipt of a request i. Unlocked and able to receive a new message, or ii. Locked and either active receiving a new message or filled with a completed message. The transition from unlocked to locked is made internally in the VAX/VMS UTI routines by the network AST. The transition back to the unlocked state is made at the explicit or implicit behest of the user. This can be done by explicitly calling the $NET_RREQ service to specify a new receive buffer (which by definition is initially unlocked) or to unlock the current buffer if no new buffer address is specified. The receive buffer may be implicitly unlocked by calling the $NET_SRPY service to send a reply to the request which is locking the receive buffer. If the receive buffer is locked by a USM, only the $NET_RREQ service can be used to unlock the buffer. 2. When a "new" unsolicited message is received by ACNET, a reply control block is allocated to contain control information about the request or USM. When the $NET_WREQ returns a non- pending status (either SS$_WASSET or NET__REQTRUNC) for a new USM, the reply control block is deleted but the receive buffer remains locked. A second call to $NET_WREQ will then return SS$_WASCLR since the USM is now considered to "have been processed". The reply block for a request will not be deleted until the request is cancelled or the final (or only) reply to the request is sent. NETWORK SERVICE DESCRIPTIONS Page 4-49 $NET_WRPY - Wait on the reception of a reply 4.17 $NET_WRPY - Wait on the reception of a reply Wait for the reception of a reply to a specified outstanding request. Macro Format $NET_WRPY reqidadr, [lenadr], [flgadr], [stsadr] High-Level Language Format NTV_WAIT_REPLY(reqidadr, [lenadr], [flgadr], [stsadr] reqidadr address of a word which contains the request identification code of the request for which the reply status is to be checked. lenadr address of a word in which the length of the reply is returned. The length is given in words. flgadr address of a word in which the message flags are returned in the low order byte. See the UAB flags bytes for the format of these flags. stsadr address of a word in which the ACNET Global Status (reply status) from the message header is returned. Return Status SS$_NORMAL Success, reply has been received. NET__BUGCHECK Internal network error. NET__NOSUCHREQ No such request exists as given by the request identification. NETWORK SERVICE DESCRIPTIONS Page 4-50 $NET_WRPY - Wait on the reception of a reply NET__NOTCNCT Not connected to the network. NET__NOTREQID Not a request identification code. SS$_ACCVIO Address of a word for the request identification not specified. SS$_ILLEFC Illegal event flag number. SS$_UNASEFC Process not connected to the event flag cluster with the specified event flag number. See $NET_STAT_S for a list of the condition codes returned due to the reply status returned in the reply message header. Notes 1. If a reply has been received, then the $NET_WRPY service will clear the DONE bit for the reply and clear the event flag (if any) specified for the reply with the $NET_SREQ service. 2. The request is deleted when a reply is received and $NET_WRPY is called if: i. the request has only a single reply, or ii. the reply is the final reply for a multiple-reply request. Basically, the request is deleted if the reply message has the MULTRPY bit cleared in the message header of the reply. This can be forced by using the ENDMULT reply option of the $NET_SRPY service. 3. The stsadr argument is used to allow the raw value of the ACNET Global Status (reply status) to be accessed. This is important if the replier, to whom the request was made, can return status information in the reply status word. In such a case, one of the NET__USRINFO or NET__SUPSINFO condition codes is used as the completion status code of the $NET_WRPY service and the user must look at the ACNET Global Status for further information. NETWORK SERVICE DESCRIPTIONS Page 4-51 $JRADIX50 - Convert ASCII to Radix-50 representation 4.18 $JRADIX50 - Convert ASCII to Radix-50 representation Convert up to 6 characters of an ASCII string to a Radix-50 longword value. If the ASCII string is shorter than 6 characters, it is treated as if it were padded on the right with blanks until a full 6 characters is reached. Macro Format $JRADIX50 tskstr High-Level Language Format JRADIX50(tskstr) tskstr address of a character string descriptor for the input text string. Return Status The longword with the Radix-50 representation is returned in place of a return status. This value is returned in register R0 or as the function value for the High-Level Language Call. Notes 1. Only the first 6 characters of an ASCII string longer than 6 characters are converted to Radix-50. If the string is shorter than 6 characters, then the string is considered to be padded with blanks (spaces) on the right to form a 6 character string. 2. The conversion from ASCII to Radix-50 will be stopped prematurely by the occurrence of a non-Radix-50 character. The Radix-50 character set includes the space, letters (lower case letters are converted as if they were upper case), digits, dollar sign ("$") and period ("."). CHAPTER 5 NETWORK LIBRARY ROUTINES In addition to the network service routines, several additional routines are included in the network library. These routines may be called to perform special functions related to the network services at the request of user programs. In particular several routines allow the status returns of the network services to be checked for condition codes which indicate that the failed operation may be retried. These additional network library routines do not have macros defined to call them. Instead the macro code illustrates a possible method of calling one of these routines using the CALLS instruction. Where appropriate, the function result in register R0 is described as an output from the routine rather than a status return. NETWORK LIBRARY ROUTINES Page 5-2 NET_RPYSTS_TEST - Check reply status for retry 5.1 NET_RPYSTS_TEST - Check reply status for retry This library routine will check the ACNET Global Status (reply status) code passed as an input argument against a bit vector of codes which indicate that the original $NET_SREQ may be retried. Thus NET_RPYSTS_TEST returns TRUE for reply status codes that indicate a failure due to a (possibly) transient condition in the remote system. Macro Format PUSHAB rpystsadr CALLS #1,G^NET_RPYSTS_TEST High-Level Language Format result = NET_RPYSTS_TEST(rpystsadr) rpystsadr address of the word containing the ACNET Global Status (reply status) code to be checked for a retryable failure. Function Result result (register R0) a value of -1 (logical TRUE for FORTRAN) is returned if the reply status code indicates a retryable failure condition. A value of 0 (logical FALSE) is returned if the reply status code indicates success or a fatal (non-retryable) failure. Notes The following reply status codes are considered to indicate retryable failures: NETAGS_K_RIO retryable I/O error NETAGS_K_NRM no memory available on remote system NETAGS_K_QPE request message packet assembly error NETAGS_K_RPE reply message packet assembly error NETAGS_K_TMO request timeout while queue to destination task NETAGS_K_FUL request failed, destination task queue full NETWORK LIBRARY ROUTINES Page 5-3 NET_TRN_NODE - Translate logical node number into name 5.2 NET_TRN_NODE - Translate logical node number into name This routine translates a logical node number (including LAN-ID) into the Radix-50 text of the logical node name. Macro Format MOVZBL #node,-(SP) PUSHAL namadr CALLS #2,G^NET_TRN_NODE High-Level Language Format NET_TRN_NODE(node, namadr) node word value giving the logical node and LAN-ID. The upper byte of this word must contain the LAN-ID (trunk), and the lower byte must contain the logical node. namadr address of a longword in which the Radix-50 text value of the logical node name is returned. Return Status SS$_NORMAL Service successfully completed, logical node name returned. SS$_NOSUCHNODE Error, no such logical node number defined. Logical node name cleared to 0. NETWORK LIBRARY ROUTINES Page 5-4 NET_TRN_NODENAME - Translate name into logical node number 5.3 NET_TRN_NODENAME - Translate name into logical node number This routine translates an ACNET logical node name into its logical node number and LAN-ID. Macro Format PUSHAB lnnadr PUSHAQ namtxt CALLS #2,G^NET_TRN_NODENAME High-Level Language Format NET_TRN_NODENAME(namtxt, lnnadr) namtxt address of a quadword string descriptor for the ASCII text of the logical node name. lnnadr address of a word in which the logical node and LAN-ID is returned. The upper byte of this word will contain the LAN-ID (trunk), and the lower byte will contain the logical node. Return Status SS$_NORMAL Service successfully completed, logical node name returned. SS$_NOSUCHNODE Error, no such logical node number defined. NETWORK LIBRARY ROUTINES Page 5-5 NTV_LCL_RETRY - Check for local retryable condition 5.4 NTV_LCL_RETRY - Check for local retryable condition This routine tests the 32-bit VMS condition code returned by a network service for values which indicate the service request failed due to a transient local condition and that the network service may be retried. Macro Format PUSHL R0 CALLS #1,G^NTV_LCL_RETRY High-Level Language Format NTV_LCL_RETRY(stsin) stsin longword value of the VMS condition code (returned status from a network service) to be tested for a retryable condition. Return Status SS$_NORMAL Success, input condition code indicates that the network service request may be retried. Any other condition code Original input condition code is returned if the condition is not recognized as retryable. Notes 1. The NTV_LCL_RETRY routine recognizes the following condition codes returned by network services as indicating a transient condition for which the network service may be retried: NET__NOBUFFER no buffers available NET__NOCTLBLK no control blocks available NET__REQTBLFUL no request table slots available 2. If a condition code value of SS$_NORMAL is used as input to this routine, then the same value will be returned as the result status since this condition code is considered to not be retryable. However, this return is then indistinguishable NETWORK LIBRARY ROUTINES Page 5-6 NTV_LCL_RETRY - Check for local retryable condition from the TRUE result returned for retryable condition codes. Therefore, only failure condition codes (severity levels of warning, error, and severe error) should be used as input to this routine. 3. Typically this routine is used to test the status returned by the $NET_SREQ, $NET_SRPY, $NET_SEND, and $NET_CAN network services. 4. When used from MACRO, the original condition code (passed as input to this routine) is returned in register R1. NETWORK LIBRARY ROUTINES Page 5-7 NTV_RMT_RETRY - Check for remote retryable condition 5.5 NTV_RMT_RETRY - Check for remote retryable condition This routine tests the 32-bit VMS condition code returned by a network service for values which indicate the service request failed due to a transient condition in the remote (destination) system and that the network service may be retried. Macro Format PUSHL R0 CALLS #1,G^NTV_RMT_RETRY High-Level Language Format NTV_RMT_RETRY(stsin) stsin longword value of the VMS condition code (returned status from a network service) to be tested for a retryable condition. Return Status SS$_NORMAL Success, input condition code indicates that the network service request may be retried. Any other condition code Original input condition code is returned if the condition is not recognized as retryable. Notes 1. The NTV_RMT_RETRY routine recognizes the following condition codes returned by network services as indicating a transient condition for which the network service may be retried: NET__IOERROR retryable I/O error NET__NOMEMRMT no memory available on remote system NET__REQPKTERR request message packet assembly error NET__RPYPKTERR reply message packet assembly error NET__RPYTBLFUL request failed, no table room for reply NET__TKSQFUL request failed, destination task queue full SS$_TIMEOUT request timeout while queued at NETWORK LIBRARY ROUTINES Page 5-8 NTV_RMT_RETRY - Check for remote retryable condition destination 2. If a condition code value of SS$_NORMAL is used as input to this routine, then the same value will be returned as the result status since this condition code is considered to not be retryable. However, this return is then indistinguishable from the TRUE result returned for retryable condition codes. Therefore, only failure condition codes (severity levels of warning, error, and severe error) should be used as input to this routine. 3. Typically this routine is used to test the status returned by the $NET_CRPY, $NET_WRPY, and $NET_STAT_S network services. 4. When used from MACRO, the original condition code (passed as input to this routine) is returned in register R1. NETWORK LIBRARY ROUTINES Page 5-9 NTV_STS32 - Convert 16-bit status to 32-bit form 5.6 NTV_STS32 - Convert 16-bit status to 32-bit form This routine converts a 16-bit ACNET Global Status to a 32-bit VMS condition code. Macro Format PUSHL #sts16 CALLS #1,G^NTV_STS32 or MOVL #sts16,R0 JSB G^NTV_STS32_R1 High-Level Language Format NTV_STS32(sts16) sts16 value of the 16-bit ACNET Global Status (or status) to be converted to 32-bit VMS condition code. Return Status Register R0 contains the VMS condition code corresponding the the 16-bit ACNET Global Status input. If the facility code of the ACNET Global Status is not that of the network (which has the value 1) or if the error code of the Global Status is unknown, then the VMS condition code SS$_MSGNOTFND will be returned. Notes 1. The mapping from ACNET Global Status to VMS condition codes is a one-to-one mapping. 2. The NTV_STS32_R1 routine is called by a JSB instruction (or one of the BSBx instructions) and provides MACRO programmers with a more efficient calling sequence. The routine's single input parameter, the 16-bit ACNET Global Status code, is passed in register R0. The routine also uses register R1 (the routine name thus follows the convention for JSB entry points described in the VAX-11 Run-Time Library Reference Manual). NETWORK LIBRARY ROUTINES Page 5-10 RAD50_TO_ASCII - Convert from Radix-50 to ASCII 5.7 RAD50_TO_ASCII - Convert from Radix-50 to ASCII This routine converts a Radix-50 value in a longword (6 Radix-50 characters) into ASCII text and returns the result in a character string pointed to by a string descriptor. Macro Format PUSHAQ txtadr PUSHAL r50adr CALLS #2,G^RAD50_TO_ASCII High-Level Language Format RAD50_TO_ASCII(r50adr, txtadr) r50adr address of a longword which contains the Radix-50 text value to be converted to ASCII. txtadr address of the quadword string descriptor of the character string in which the ASCII text is to be returned. Return Status SS$_NORMAL Service successfully completed LIB$_STRTRU Success, except that the output string is shorter than 6 characters and the converted text may have been truncated (non-blank characters lost) to fit. Notes 1. This routine is designed to work with VAX-11 FORTRAN in that the ASCII text may be returned in a CHARACTER data type. 2. This routine treats the output string as a fixed-length string by ignoring the type and class fields of the string descriptor. Thus it is possible to return the condition code LIB$_STRTRU even with dynamic strings. If the output string is longer than 6 characters, the string is padded on the right NETWORK LIBRARY ROUTINES Page 5-11 RAD50_TO_ASCII - Convert from Radix-50 to ASCII with blanks to the length of the string (even for dynamic strings). 3. If the Radix-50 value in a word of the longword is greater than 174777 octal, then three ASCII question marks ("???") are returned in the positions of the characters represented by that word. If the undefined Radix-50 character value is found (35 octal), then an ASCII question mark ("?") is returned for that character. APPENDIX A Additional Macros This appendix describes several additional macros that are included in the VAXNET.MLB macro library. These macros are used to generate particular data or instruction sequences or to define constants or data structure offsets associated with the ACNET network. Additional Macros Page A-2 $.RAD50L - Generate .LONG of Radix-50 text A.1 $.RAD50L - Generate .LONG of Radix-50 text This macro provides the equivalent of a .ASCII assembler directive. The macro is used as shown: $.RAD50L text where the text is converted to Radix-50 and stored as a longword (via a .LONG directive). Only the first 6 characters of the text will be converted to Radix-50. If the text string is shorter than 6 characters, then it will be considered to be padded on the right with spaces (to 6 characters) in being converted to Radix-50. The occurrence of a non-Radix-50 character will terminate the conversion before 6 characters have been converted. A.2 $.RAD50S - Generate symbol with Radix-50 value This macro is similar to the $.RAD50L macro except that instead of storing the Radix-50 text with a .LONG directive, the value of a specified symbol is equated to the Radix-50 text value. The format of the macro call is: $.RAD50S symbol,text where the text is converted to Radix-50 in the same manner as for $.RAD50L. The specified symbol is then equated to this Radix-50 value. A.3 $.RAD50W - Generate .WORD of Radix-50 text The $.RAD50W macro is similar to the $.RAD50L macro except that only up to 3 characters are converted to Radix-50 and the Radix-50 value is stored with a .WORD directive. Additional Macros Page A-3 CASE - Generate a CASEx instruction and dispatch list A.4 CASE - Generate a CASEx instruction and dispatch list The CASE macro provides a convenient method for generating a CASEx instruction and its dispatch list. CASE src, , [type], [limit], [nmode] src this argument specifies the source of the data value on which the CASE test and branch is to be performed. This is the selector operand of the CASEx instruction. The data type of src is a byte, longword, or word according to the type of the CASEx instruction (see below). the dispatch list is a list of labels enclosed in angle brackets ("<" and ">") and separated by commas. These are the labels to which the CASE instruction will branch as determined by the value of the src argument. type this argument determines the data type of the CASEx instruction. The default is "W" for word data type. Other choices are "B" for bytes and "L" for longwords. limit this argument specifies the lower limit for the CASE selector (the base operand of the CASE instruction with same data type as the src argument). The default value is "#0" for the base. nmode this argument specifies the addressing mode for the CASE instruction limit operand. The default specifies short literal addressing ("S^#") which is usually adequate. The other choice is immediate mode addressing ("#"). Additional Macros Page A-4 POPREG - Pop a longword from stack into a register A.5 POPREG - Pop a longword from stack into a register The POPREG macro is a special form of the POPL macro (provided by the MACRO32 assembler) which pops a longword off the top of the stack. POPREG will use the shortest instruction sequence to pop a longword off the top of the stack and into a general register. The macro is called by: POPREG Rn where an error will result if Rn is not a general register. If a POPREG is done into one of the registers R0 through R5, then a POPR instruction is used as it a shorter instruction sequence. For other registers the equivalent of a POPL pseudo- instruction is done ("MOVL (SP)+,Rn"). Additional Macros Page A-5 Definitions Macros A.6 Definitions Macros These macros are used to define symbolic names for ACNET network constants and offsets into some network data structures. As standard for VAX/VMS definition macros, the first macro argument can be the literal "GLOBAL" to define the symbol as global symbols. If the argument is left off (defaulted) or "LOCAL" is used to define the symbols local to the module being assembled. The notation used for symbol names follows a VMS standard in which a name consists of a structure identifier, data type identifier and data name or identifier: "struct_type_name". The "_V_" symbols specify the bit offsets (bit number starting with 0) of the bit or field of the flags byte. The "_M_" symbols define the masks for single bits of fields of bits (useful in bit-wise AND operations). The "_S_" symbols specify the size in bits of multi-bit fields (note that such symbols are not defined for single bits). The "_K_" symbols define constants. Offsets into data structures use the data type (byte, word, longword, or quadword) as the type portion of the symbol name: "_B_", "_W_", "_L_", or "_Q_". A.6.1 $ARB_DEF This macro defines the symbol names of the offsets into the ACNET Request Block used to make requests to the ACNET network task. These requests contain a typecode (ARB_B_TYPCOD) and sub- function code or value (ARB_B_SUBFCN). The Request Block may also include additional data or addressing information as the particular typecode requires. Figure A.1 Format of ACNET Request Block 15 8 7 0 +----------------+----------------+ | ARB_B_SUBFCN | ARB_B_TYPCOD | +----------------+----------------+ | | | additional data (if any) ... | | | +---------------------------------+ Additional Macros Page A-6 Definitions Macros Figure A.2 Format of ACNET Request Typecode Byte 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | . | | | | | S | | | S | signed code | | F | | | | | | . | +---+---+---+---+---+---+---+---+ Figure A.2 shows the ACNET typecode byte in more detail. The actual typecode is specified by the entire byte as a signed value. The sign bit (ART_V_SSF) is set for ACNET typecodes that are specific to a particular system and not globally supported by all ACNET network tasks. A.6.2 $ART_DEF This macro defines the values of the ACNET Request Typecodes. These are listed in Table A.1 below. In addition, this macro defines the offsets into the ACNET Request Typecode byte just as they are defined by the $ARB_DEF macro. Additional Macros Page A-7 Definitions Macros Table A.1 ACNET Request Typecodes ART_K_ASSIGN 10 Reassign logical nodes ART_K_GTASKS 4 Get list of connected tasks ART_K_GTCNTS 5 Get resource/usage counts ART_K_GTPKTS 9 Get total packet count and uptime ART_K_GTSKID 1 Get logical task id ART_K_GTSKNM 2 Get network task name ART_K_GTSTAT 6 Get general statistics ART_K_GTTKST 7 Get Per-task statistics ART_K_GTVERS 3 Get version numbers ART_K_KILLER 11 Kill network operations ART_K_NOOP 0 No operation ART_K_SHUTUP 12 Shutdown local network ART_K_DACTAB 13 Read/write DACNET table ART_K_ETHTAB 14 Read/write Ethernet table ART_K_CASTAB 15 Read/write Multicast table ART_K_SETMGF 16 Set Multicast-Group-Functional address ART_K_IPATAB 17 Read/write IP (A) address table ART_K_VAX_CTLPRC -22 Perform process control function ART_K_VAX_GTCCRL -4 Get configuration report list ART_K_VAX_GTIMDT -1 Get time and date ART_K_VAX_GTJPI0 -11 Get job/process information ART_K_VAX_GTJPI1 -12 Get job/process information ART_K_VAX_GTMOAG -9 Get timeout age limits ART_K_VAX_GTPKTS -2 Get total packet count ART_K_VAX_GTPNAS -6 Get configuration table ART_K_VAX_GTSMSG -3 Get system message text ART_K_VAX_GTSUBN -5 Get PCL subnet number ART_K_VAX_MEMDMP -8 Dump network common memory block ART_K_VAX_SPAWNS -21 Spawn detached process ART_K_VAX_STMOAG -20 Set timeout age limit ART_K_VAX_TMRCTL -13 Enable/disable timer ART_K_VAX_ALTLST -14 Get alternate trunk/node info A.6.3 $LNN_DEF This macro defines the symbolic names for the ACNET logical nodes in the form "LNN_K_name", where "name" is the name of a logical node. The notation "LNN" is taken to mean "Logical Node Number". The name of the logical node is the same as the FORTRAN symbol defined by the PARAMETER statements in the NODEDEFS INCLUDE module. Additional Macros Page A-8 Definitions Macros A.6.4 $MSGHDR_ALTDEF This macro provides alternate symbol names for some of the offsets and constants defined in the $MSGHDR_DEF macro. HDR_V_CAN bit offset of CANCEL bit in message header extended flags byte (also called HDR_V_CANCEL). HDR_V_MLT bit offset of MULTRPY bit in message header flags byte (also called HDR_V_MULTRPY). HDR_V_NBW bit offset of NOBSYWT bit in message header extended flags byte (also called HDR_V_NOBSYWT). MSG_K_REQ message type code for request. MSG_K_RPY message type code for reply. MSG_K_USM message type code for unsolicited special request (USM). A.6.5 $MSGHDR_DEF This macro defines symbolic names for the offsets in the message header and for the message type codes. A.6.6 $NET_DEF This macro defines the symbols giving the values of the VAX/VMS ACNET network completion codes (signal names) in the form "NET__ident". These symbols are also defined as global symbols in the VAXNETUTI.OLB library and as UNIVERSAL symbols in the UTI.EXE shareable image. A.6.7 $NETAGS_DEF This macro defines the NETAGS_K_cod symbols giving the values of the ACNET Global Status returned by the various network routines. The ACNET Global Status is also returned by the FORTRAN entry points to the network services that are described in the FORTRAN User's Manual. See Appendix D for further information. The $NETAGS_DEF macro can define the NETAGS_K_cod symbols to be just the status code (upper byte) portion of the ACNET Global Status or the value of the entire 16-bit ACNET Global Status word. By default, the word values are generated. To generate the byte values, the macro keyword argument "type" should be given the value "BYTE" as shown: $NETAGS_DEF type=BYTE Additional Macros Page A-9 Definitions Macros A.6.8 $UAB_DEF This macro defines the offsets into the User AST Block and the flags byte as described in Chapter 2 of this document. APPENDIX B FORTRAN and C Considerations B.1 INCLUDE Files For High-Level Language users, there are several modules available to be INCLUDE'd into a program to define network constants and bit masks. All the modules can be found as separate files in the directory ACNET$INCLUDE:. The file types (".FOR" or ".H") determine for which VAX-11 language (FORTRAN or VAX-11 C) the files are applicable to. The FORTRAN modules consist of a series of PARAMETER statements and may be added to a FORTRAN routine with a "INCLUDE" statement. B.1.1 MSGTYPDEF The MSGTYPDEF module defines the message type code symbols. HDR_K_LENGTH gives the length of the message header in bytes. MSG_K_REPLY gives the message type code of replies (also defined as MSG_K_RPY). MSG_K_REQUEST gives the message type code of requests (also defined as MSG_K_REQ). MSG_K_UNSOLIC gives the type code of USM's, unsolicited special messages (also defined as MSG_K_USM). B.1.2 $NETAGS_DEF The $NETAGS_DEF module (NETAGSDEF.xxx file) defines the ACNET Global Status code symbols NETAGS_K_cod (cod is the 3 letter identifier of the error or success code). The values of these symbols are for the 16-bit word including the network facility code. More information on the ACNET Global Status values can be found in Appendix D. FORTRAN and C Considerations Page B-2 INCLUDE Files B.1.3 NODEDEFS This module defines symbolic names for the ACNET logical nodes. B.1.4 REQRPYFLG This module defines symbols to be the masks for request and reply option bits used in the $NET_SREQ and $NET_SRPY network service calls. REQ_M_MULTRPY mask for the multiple-reply bit in the request option flags (also defined as REQ_M_MLT). Used to indicate a request to which more than one reply message is returned. REQ_M_NOBSYWT mask for the no-busy-wait bit in the request option flags (also defined as REQ_M_NBW). Used to fail a request (return status-only reply) if the destination task is busy with another message. RPY_M_LOCKED mask for the buffer-remains-locked bit in the reply option flags (also defined as RPY_M_BRL). Used to override the receive buffer unlock done in the $NET_SRPY network service routine. RPY_M_ENDMULT mask for the end-multiple-reply bit in the reply option flags (also defined as RPY_M_EMR). B.1.5 $SSDEF and $NET_DEF The $SSDEF module defines the VMS system service completion codes (signal names) as "SS$_name". The $NET_DEF module defines the VAX/VMS ACNET network completion codes as "NET__name". B.1.6 UABFLGDEF The UABFLGDEF module defines symbolic names for the masks, bit offsets and sizes of the UAB_B_FLAGS byte and the request or reply flags arguments of the $NET_Cxxx (check) and $NET_Wxxx (wait) network service routines. UAB_K_LENGTH is the length of a UAB in bytes. UAB_V_CANCEL bit indicates that the outstanding request has been cancelled and no more replies should be generated. UAB_V_MSGTYPE is the message type code field. FORTRAN and C Considerations Page B-3 INCLUDE Files UAB_V_MULTRPY is the multiple reply bit. UAB_V_TOOLONG bit indicates that the message was truncated to fit in the specified buffer. The UAB_V_CANCEL bit and the UAB_V_MSGTYPE field are only used with requests and USM's. These fields are set to zero for replies. B.2 EXTERNAL Symbols (FORTRAN) FORTRAN programs may refer to the VMS completion codes (signal names) returned by VMS system services and VAX/VMS ACNET network services by declaring any such symbols needed as "EXTERNAL". The values may then be accessed by using the %LOC function to return the "address" of the symbol as in: value = %LOC(SS$_ABORT) Similarly if an explicit signal is to be generated, then the signal name may be used as is in the call to LIB$SIGNAL or LIB$STOP without the %VAL: CALL LIB$STOP(NET__NOTCNCT) APPENDIX C Request and Reply Identification Codes The request identification word used by VAX/VMS ACNET does not contain the address of a data structure. Instead, the request and reply identification word is divided into two fields. The first field of 10 bits (bits 0 through 9) is an index into the request/reply table. This field provides for a maximum of 1023 requests and replies to be active simultaneously at a single VAX/VMS node. The actual table size allocated will be somewhat smaller than this limiting value. The upper field of the word (bits 10 through 15) provides a 6 bit sequence count used to identify that a request index has been reused for a new request. A reply identification code has the sequence count field set to 0. APPENDIX D VMS Condition Codes and ACNET Global Status The ACNET Global Status code format is defined in Status and Error Conventions (ACNET Design Note 28). This is a 16-bit word whose upper byte is an error code and whose lower byte contains a facility number. The facility number for the ACNET network system is one (1). The VAX/VMS ACNET network service routines described in the FORTRAN User's Manual return ACNET Global Status codes (actually sign-extended to a full 32-bits in register R0). For the most part, the conversion from the 32-bit VMS condition code returned by the network service entry points described above to the 16-bit ACNET Global Status is performed by the NTV_STS16_R1 routine (see the $NET_STS16_S network service description). Table D.1 shows the mapping between the error code values and the VMS condition codes. Note that this does not exactly match the values returned from some of the NET entry points and their corresponding NTV entry points. This is because several of the NET entry points map some of the condition codes returned by particular NTV entry points to ACNET Global Status codes without invoking NTV_STS16_R1. The NTV_STS32 routine converts from an ACNET Global Status code back to a VMS condition code. This is a one-to-one mapping. The VMS condition code returned for each ACNET Global Status is the first (of any multiple entires) entry listed in Table D.1 for each Global Status value. VMS Condition Codes and ACNET Global Status Page D-2 Table D.1 VMS Condition Codes and ACNET Global Status Codes Error Global Code_ Status Name VMS_Condition_Code(s) +00 0 SUC SS$_NORMAL SS$_WASCLR SS$_WASSET +01 +257 PND 0 +02 +513 END NET__ENDMLTRPY +03 +769 SSR NET__SUPSINFO +04 +1025 USR NET__USRINFO -01 -255 RIO NET__IOERROR -02 -511 NLM NET__NOBUFFER NET__NOCTLBLK NET__REQTBLFUL NET__RUMLSTFUL NET__TSKLSTFUL SS$_INSFMEM -03 -767 MRM NET__NOMEMRMT NET__RPYTBLFUL -04 -1023 RPE NET__RPYPKTERR -05 -1279 QPE NET__REQPKTERR -06 -1535 TMO SS$_TIMEOUT -07 -1791 FUL NET__TSKQFUL -08 -2047 BSY NET__TASKBUSY -21 -5375 NCN NET__NOTCNCT -22 -5631 ARG SS$_INSFARG -23 -5887 IVM NET__NOBUFR NET__NOMSG NET__NORPYBUF NET__TOOLONG -24 -6143 NSR NET__NOSUCHREQ -25 -6399 IEF SS$_ILLEFC SS$_UNASEFC -26 -6655 CAN SS$_CANCEL -27 -6911 RUM NET__RUMNAMEXI -28 -7167 NCR NET__NOTRUM -30 -7679 NOD SS$_NOSUCHNODE NET__NOTRPYID NET__NOTREQID -31 -7935 TRQ NET__REQTRUNC -32 -8191 TRP NET__RPYTRUNC -33 -8447 TSK SS$_NOSUCHOBJ -34 -8703 DCN NET__DISCONING -35 -8959 L2E SS$_BADPARAM NET__ILLACNCOD NET__INCWRTPWD -41 -10495 HIO SS$_COMMHARD -42 -10751 DWN NET__NODEDOWN -43 -11007 SYS NET__SYSERR SS$_NONEXPR SS$_NOPRIV SS$_NOSUCHSEC SS$_OPINCOMPL -44 -11263 NXE SS$_SSFAIL NET__NOTALLLCK NET__NOTALLMAP -45 -11519 BUG NET__BUGCHECK SS$_ENDOFFILE SS$_IVLOGNAM SS$_IVSECIDCTL SS$_IVSECFLG SS$_PAGOWNVIO SS$_SHMNOTCNCT SS$_TOOMANYLNAM -46 -11775 NE1 SS$_EXQUOTA SS$_VASFULL SS$_INSFWSL SS$_LCKPAGFUL -47 -12031 NE2 SS$_ACCVIO -48 -12287 NE3 SS$_INTERLOCK SS$_VECINUSE INDEX ACNET Global Status, 1-1, 1-4, $NET_CREQ, 1-3, 2-5, 3-2, 4-10, 4-44, 5-9, A-8, B-1, D-1 4-40, B-2 VMS Condition Codes and ACNET Global Status Page Index-1 Index ACNET Request Block, 4-19, 4-22, $NET_CRPY, 1-3, 2-5, 3-2, 4-13, A-5 4-41, 5-8, B-2 ACNET$INCLUDE, B-1 $NET_DCNT, 1-2, 4-16 $ARB_DEF, A-5 to A-6 $NET_DCNT_S $ART_DEF, A-6 $NET_DEF, 3-1, A-8 $NET_GTID, 1-3, 4-18 Buffer locking, 2-6, 4-12, 4-27, $NET_GTNM, 1-3, 4-21 4-39, 4-48, B-2 $NET_HANDLE, 1-3 to 1-4, 2-7, 4-8, By-descriptor, 1-7 4-23 By-immediate-value, 1-6 NET_RPYSTS_TEST, 5-2 By-reference, 1-6 to 1-7 $NET_RREQ, 1-3, 2-7, 3-2, 4-12, by-address 4-25 to 4-26, 4-48 $NET_RREQ., 2-7 CASE, A-3 $NET_RRPY, 1-3, 3-2, 4-28 to 4-29 $NET_SEND, 1-3, 4-31, 5-6 ENDMULT, 4-14, 4-35, 4-39, 4-50, $NET_SREQ, 1-3, 4-14, 4-33, 4-35, B-2 4-50, 5-2, 5-6, B-2 Event flag 0, 2-1 $NET_SRPY, 1-3, 2-7, 4-12, 4-14, 4-35, 4-37, 4-48, 4-50, 5-6, FCPAST, 2-5, 4-30, 4-35 to 4-36 B-2 First Packet AST's, 2-5, 4-35 to $NET_STAT, 1-3, 3-2, 4-14, 4-41, 4-36 4-50, 5-8 $NET_STAT_S $JRADIX50, 4-51 $NET_STS16, 1-4, 4-44, D-1 JRADIX50, 4-51 $NET_STS16_S, 4-44 NET_STS16, 4-44 $LNN_DEF, A-7 NET_TRN_NODE, 5-3 Locking, 2-6, 4-12, 4-27, 4-39, NET_TRN_NODENAME, 5-4 4-48, B-2 $NET_WREQ, 1-3, 2-5, 3-2, 4-40, Logical node, 1-2, 4-10 to 4-11, 4-46, B-2 4-18 to 4-19, 4-21 to 4-22, $NET_WRPY, 1-3, 2-5, 3-2, 4-41, 4-31, 4-33, 4-46 to 4-47, 5-3 4-49, 5-8, B-2 to 5-4, A-7, B-2 $NETAGS_DEF, A-8 Logical task id, 1-2, 4-11, 4-18, NETCOMMON, 4-8 4-20 to 4-21, 4-47 NETPROCESS, 4-8 Network AST, 2-1 to 2-2, 3-2, Message packet size, 1-1 4-27, 4-30, 4-48 Message size, 1-1 Network task name, 4-6, 4-8 to Message types, 1-1, A-8, B-1 4-9, 4-18, 4-20 to 4-21, 4-31, $MSGHDR_ALTDEF, A-8 4-33 $MSGHDR_DEF, A-8 No Busy Wait, 4-35 Multicast nodes, 1-2 NOBSYWT, 4-35, A-8, B-2 Multiple replies, 1-2, 4-14, 4-35, NTV_CANCEL_REQUEST, 4-4 4-39, 4-50 NTV_CHECK_REPLY, 4-13 MULTRPY, 2-5 to 2-6, 4-14, 4-35, NTV_CHECK_REQUEST, 4-10 4-50, A-8, B-2 to B-3 NTV_CONNECT, 4-6 NTV_DISCONNECT, 4-16 $NET_CAN, 1-3, 4-4, 4-16, 5-6 NTV_GET_TASKID, 4-18 $NET_CNCT, 1-2, 4-6, 4-25 NTV_GET_TASKNAME, 4-21 VMS Condition Codes and ACNET Global Status Page Index-2 Index NTV_HANDLE, 4-23 Request Options Bits, 4-36 NTV_LCL_RETRY, 5-5 Requestor, 1-1 to 1-2 NTV_RECEIVE_REPLY, 4-28 Resource Wait mode, 3-2, 4-27, NTV_RECEIVE_REQUEST, 4-25 4-30 NTV_RMT_RETRY, 5-7 RUM-connect, 1-3 to 1-4, 4-25, NTV_SEND, 4-31 4-27 NTV_SEND_REPLY, 4-37 NTV_SEND_REQUEST, 4-33 $SSDEF, 3-1 NTV_STATUS, 4-41 SUPSINFO, 4-15, 4-41, 4-50 NTV_STS16, 4-44 SYS$LIBRARY:, 1-4, 1-7 to 1-8 NTV_STS16_R1, 4-44 to 4-45 NTV_STS32, 5-9, D-1 Trunk, 1-2 NTV_STS32_R1, 5-9 NTV_WAIT_REPLY, 4-49 UAB Flags Byte, 2-3 to 2-5, 4-10, NTV_WAIT_REQUEST, 4-46 4-13, 4-46, 4-49, B-2 UAB_B_FLAGS Packetting, 1-1 to 1-2 $UAB_DEF, 2-2, A-9 POPREG, A-4 Unlocking a buffer, 2-6, 4-12, 4-27, 4-39, 4-48, B-2 RAD50_TO_ASCII, 5-10 User AST Block, 2-2 to 2-3, A-9 $.RAD50L, A-2 USRINFO, 4-15, 4-41, 4-50 $.RAD50S, A-2 UTI, 1-2, 1-7, 4-8 $.RAD50W, A-2 User Task Interface Receive buffer, 4-12, 4-25, 4-27, UTI Shareable Image, 1-7, A-8 4-47 Receive buffer lock, 2-6, 4-12, VAXNET.MLB, 1-4, 2-2, 3-1, A-1 4-27, 4-39, 4-48, B-2 Macro Library Replier, 1-1, 1-3 VAXNETUTI.OLB, 1-7, 3-1, A-8 Reply Id, 4-2, 4-10, 4-46, C-1 UTI Object Library Reply Options Bits, 4-39 VAXNETUTI.OPT, 1-8 Reply Status, 3-1 UTI Linker Options File Reply status, 2-3, 4-13 to 4-15, VMS Condition Code, 1-3, 1-6, 3-1, 4-37, 4-39, 4-49 to 4-50, 5-2 4-2, 4-44 to 4-45, 5-5, 5-7, Request Id, 4-2, 4-4, 4-10, 4-13, 5-9, A-8, B-2, D-1 4-28, 4-33, 4-37, 4-46, 4-49, VMS Completion Code C-1 VMS Completion Status VMS Condition Codes and ACNET Global Status Page Index-3 Distribution Normal file gcj: USR$DISK1:[VAXACNET.DOC]VAXNETUSR.RNO ÿ