In X.25 communications, the NW device (or X.25 network device, or NWA0:) processes control data and user data which passes between the X.25 program and X.25 for OpenVMS.

In X.29 communications, the NW device processes system services relating to network control, which are issued by the X.29 program, and passes them to the NV device.

The NV device is used in X.29 communications to handle data transfer across an X.25 network. The NV device uses the X.29 protocol which connects the user’s X.29 program to the PAD.

The TT device processes system services relating to user data, which are issued by the X.29 program, and passes them to the NV device. The OpenVMS terminal driver controls the TT device.

For descriptions of the other components in the X.25 and X.29 communications links, refer to the VSI DECnet-Plus for OpenVMS Introduction and User’s Guide.

The differences between X.25 communications and X.29 communications are described in Table 1.1, “Facilities Offered by X.25 and X.29 Programming”

Section 1.3, “Interaction of the NV Device, the PAD, and the X.29 Terminal” provides some details of how the X.29 communications link works.

The PAD transfers data from the X.29 terminal to the TT device as follows:

The TT device transfers data to the PAD as follows:

The Network Connect Block (NCB) is a user-generated data structure composed of a number of variable-length items. Each item consists of a Length field, a Type Code field, and a variable-length Data field. The Type Code field identifies the item. For details of the NCB structure and item types, and a summary of the mandatory and optional fields in the NCB, refer to the VSI X.25 for OpenVMS Programming Reference manual; that manual also contains an example of an NCB.

The Network Connect Block is used by:

The NCB is used to set up, accept, redirect, reject, and clear virtual circuits.

X.25 for OpenVMS uses a mailbox to pass NCB information to a program. The NCB:

It is advisable to associate a mailbox with each NW or NV device you use to accept or make a call. If you do not, you will receive only indirect notification of network events.

Use the $CREMBX system service to create a mailbox before you assign a channel to your network device with the $ASSIGN system service.

Section 3.1.1, “Creating a Mailbox” describes how to create a mailbox.

For detailed information about the mailbox, refer to the VSI X.25 for OpenVMS Programming Reference manual, where the mailbox structure and mailbox message types are described.

The arguments required by a system service are shown in the system service descriptions in the VSI X.25 for OpenVMS Programming Reference manual. The Macro Format for each system service shows the positional dependencies and keyword names of each argument.

All arguments are longwords. The first longword in the list must contain, in its low-order byte, the number of arguments in the remainder of the list. The remaining three bytes must be zeros.

If you omit an optional argument in a system service macro instruction, the macro supplies a default value for the argument.

For details of the generic macro forms used for coding calls to system services, refer to the MACRO documentation.

If your program is to handle incoming calls, you must use a mailbox to receive notification of their arrival. You can then use the specified mailbox to receive messages of network events and interrupts.

If your program makes outgoing calls only, and you do not want direct notification of network events, you need not create a mailbox. Note, however, that without a mailbox you cannot receive interrupts.

There are two ways to create a mailbox:

For a description of the mailbox structure and message types, refer to the VSI X.25 for OpenVMS Programming Reference manual.

There are two ways to assign a channel to a device and associate a mailbox with it:

To find the unit number, uu, of the NW device, issue $GETDVI on the same channel.

If the NV device is connected to the OpenVMS terminal driver as a VT (virtual terminal) device, your program must use a special procedure to calculate the unit number of the NV device.

If there is a VT device associated with the NV terminal, the $GETDVI system service call returns information about the VT device. In particular, DVI$_UNIT returns the unit number of the VT device, not the unit number of the NV device.

To obtain the unit number of the NV device:

For an example of how to parse a device name string to extract the device unit number, refer to Appendix A, Example of Parsing the Device Name String.

Use $QIO(IO$_ACCESS) to set up a virtual circuit to a remote DTE, and optionally request network facilities. If you subscribe to the fast select facility, you can use this call to send 128 instead of 16 bytes of user data.

Also use this call before transmitting or receiving data on a Permanent Virtual Circuit (PVC). For a PVC, specify the name of the PVC in the NCB.

You must supply an NCB to inform X.25 for OpenVMS how you want the virtual circuit to be set up. For details of how to set up an NCB, refer to Section 2.4.1.1, “How to Set Up a Network Connect Block”.

Note that you must always specify the length of the NCB in the descriptor.

Certain system resources are used to set up a virtual circuit. For details of the system resources you require to set up virtual circuits, refer to Section 2.7, “System Resources Required for a Virtual Circuit”.

Figure 3.1, “Set Up a Virtual Circuit-Call Accepted”, Figure 3.2, “Set Up a Virtual Circuit - Call Rejected by Remote DTE”, and Figure 3.3, “Set Up a Virtual Circuit -Call Rejected by Network” show the request for a virtual circuit being accepted, being rejected by the remote DTE, and being rejected by the network.

You can clear a call in either of the following ways:

Figure 3.4, “Clear a Virtual Circuit”shows how a virtual circuit is cleared.

X.25 and X.29 programs can issue $QIO(IO$_ACPCONTROL) calls to declare themselves as network processes. Each $QIO(IO$_ACPCONTROL) call specifies a filter to be used in determining which incoming calls the process will handle.

The filter specified in a $QIO(IO$_ACPCONTROL) call can be one of two types:

The IO$_ACPCONTROL call defines a number of other parameters to identify the incoming calls that the process will handle. Some of these parameters are the template, local subaddress, the remote DTE address, the user data field, and user group identification. A full list of parameters is provided in the VSI X.25 for OpenVMS Programming Reference manual.

When it has matched the parameters of an incoming call with those of a network process, X.25 for OpenVMS puts the NCB for the incoming call in the mailbox associated with the channel over which the IO$_ACPCONTROL was issued.

Your process can then accept, reject, or redirect the incoming call.

If you want the process to handle calls that match another combination of parameters, have the process issue another $QIO(IO$_ACPCONTROL).

The parameters used to identify acceptable incoming calls are contained in a Network Process Declaration Block (NPDB). This block consists of a string of variable length items. Each item has a two-word header giving its length (in bytes) and its type. The type codes, their description, and use are given in the VSI X.25 for OpenVMS Programming Reference manual.

To receive incoming calls, you first have to assign a channel (as with transmitting a call). Use the $ASSIGN system service to obtain a channel and to associate a mailbox with this channel.

For further details about this system service, refer to Section 3.1.2, “Assigning the Control and Data Channels”.

Use $QIO(IO$_ACCESS!IO$M_ACCEPT) to accept an incoming request to set up a virtual circuit. This $QIO call also allows you to negotiate facilities requested by the incoming call. If you subscribe to the fast select acceptance facility with no restriction on response, you can also use $QIO(IO$_ACCESS!IO$M_ACCEPT) to send user data.

You are advised to use the NCB received in the incoming call as an argument to this $QIO. Issue $QIO(IO$_READVBLK) to read the NCB from the mailbox associated with the control channel to NWAuu:. If you create a new NCB to accept the call, the new NCB must contain the incoming call identification field (PSI$C_NCB_ICI) from the mailbox’s NCB to associate the channel with the received call.

If the incoming call specifies fast select with no restriction on response and you wish to reply with user data, add a response data field (PSI$C_NCB_RESPDATA) to the NCB. Accepting the call changes it to a normal call request, and your program can read and transmit messages as usual.

You can modify the following items in the NCB and hence negotiate the associated facilities:

The items to be negotiated can either be specified individually in the NCB or collectively in a template using the PSI$C_NCB_TEMPLATE item code. Note that if the PSI$C_NCB_TEMPLATE item code is not specified, the template Default is used.

A template can also be used to specify parameters that are not defined in the NCB used to accept the call. In addition to the negotiated items, the following items can be added to the NCB:

To accept a request to set up a virtual circuit you require certain system resources, which are deducted from the quota for your process. This is described in Section 2.7, “System Resources Required for a Virtual Circuit”. If you want to change the limit on the quota that X.25 for OpenVMS will use, place a PSI$C_NCB_RCV_QUOTA item in the NCB.

X.25 for OpenVMS identifies the incoming calls that have been accepted by using the incoming call identification field (PSI$C_NCB_ICI). Never modify this field.

The operation completes when an acceptance is sent to the remote DTE.

If your process fails in attempting to accept the incoming call (for example, because the process has insufficient quota), X.25 for OpenVMS rejects the call.

Figure 3.5, “Accept a Request to Set Up a Virtual” shows how a request to set up a virtual circuit is accepted.

Use the $QIO(IO$_ACCESS!IO$M_ABORT) operation to reject a request to set up a virtual circuit. If you subscribe to the fast select acceptance facility, IO$_ ACCESS!IO$M_ABORT also offers you the option of returning data to the calling DTE.

You are advised to use the NCB received as part of the incoming call as an argument to this $QIO. Find the NCB in the mailbox associated with the channel which received the call.

If the incoming call specifies fast select with or without restriction on response, and you wish to reply with some data, add a response data field (PSI$C_NCB_ RESPDATA) to the NCB.

You can specify a diagnostic code field (PSI$C_NCB_DIAGCODE) to contain user-specified codes that show reasons for the rejection.

You can also specify or modify local facilities by adding a local facilities field (PSI$C_NCB_LOCFACR) to the NCB.

You may modify the called address extension facility (PSI$C_NCB_CALLED_ EXTENSION) in the NCB.

If you create a new NCB to reject the call, always copy the incoming call identification field (PSI$C_NCB_ICI) from the received NCB.

The operation completes when X.25 for OpenVMS sends the rejection to the remote DTE.

Figure 3.6, “Reject a Request to Set Up a Virtual Circuit” shows how a request to set up a virtual circuit is rejected.

Use the $QIO(IO$_ACCESS!IO$M_REDIRECT) operation to redirect a request to set up a virtual circuit to another process, before the request is accepted or rejected. $QIO(IO$_ACCESS!IO$M_REDIRECT) uses the fields, specified in the NCB in the normal way, to associate the request with a new process.

You are advised to use the NCB received as part of the incoming call as an argument to this $QIO. Find the NCB in the mailbox associated with the channel which received the call. You can modify the following fields in the NCB or add them if they are not present in the original call:

You may add the following fields:

Do not modify the incoming call identification field.

If you create a new NCB to redirect the call, X.25 for OpenVMS copies all fields not specified in the new NCB from the received NCB.

This $QIO allows you to write a process to receive some, or all, of the requests to set up a virtual circuit, and to redirect these requests to other processes using your own algorithms.

To redirect the request, you must return the NCB to the incoming call handler after doing at least one of the following:

Always pass on the incoming call identification information.

The redirect priority causes X.25 for OpenVMS to exclude filters that have a priority greater than or equal to the redirect priority. For example, you could change the filter priority item in the received NCB to the redirect priority and use the same NCB in the redirect request. The destination search would effectively restart after your destination and continue down the priority order.

The operation completes when X.25 for OpenVMS redirects the call.

To send data over a virtual circuit, use the $QIO(IO$_WRITEVBLK) operation.

For full details of $QIO(IO$_WRITEVBLK), refer to the VSI X.25 for OpenVMS Programming Reference manual. Figure 3.7, “Transmit Data” shows how data is transmitted over a virtual circuit.

To receive data transmitted from a remote DTE, use the $QIO(IO$_READVBLK) operation.

When a packet of data arrives, the NW device does one of the following:

Note that receiving a MSG$_INCDAT message does not guarantee that there is data to be read. Depending on the structure of the application, there may be none, one or many packets waiting, at the time the application processes the MSG$_INCDAT message.

There may be no packets waiting to be read if the application read data before it processed the MSG$_INCDAT message.

If more than one packet arrives, it will take more than one read to receive all the data.

For full details of $QIO(IO$_READVBLK), refer to the VSI X.25 for OpenVMS Programming Reference manual. Figure 3.8, “Receive Data” shows how data is received.

To receive incoming calls, the following entities must be created in addition to those entities specified in Section 4.1, “Minimum Configuration Entities”.

The X25 ACCESS FILTER entity is used to determine which calls a process will handle. You do not need to create a static filter if dynamic filters are used. Details on static and dynamic filters are provided in the VSI X.25 for OpenVMS Management Guide.

The X25 ACCESS SECURITY FILTER entity is used with the SECURITY DTE CLASS and SECURITY DTE CLASS REMOTE DTE entities to provide security for incoming calls.

To make an outgoing call, the X25 ACCESS TEMPLATE entity can be created in addition to those entities specified in Section 4.1, “Minimum Configuration Entities”.

The X25 ACCESS TEMPLATE entity needs to be created only if you intend to use the specified template to make an outgoing call. A template does not need to be created to make an outgoing call, but creating a template is a convenient way of specifying the call parameters to be used for an outgoing call.

If a template is created, an X.25 application can reference the template and the call parameters set up in the template are used to make the outgoing call. You can therefore change call parameters without recompiling the X.25 application. For example, by placing the DTE address of the DTE to be called in the template you can change the address without recompiling the X.25 application. Details on creating templates are provided in the VSI X.25 for OpenVMS Management Guide.

Your program can declare itself to be a Network Process, and enter its own filters in the X25 Access module.

To receive incoming calls, an X.25 Network Process must direct X25 Access to listen on one or more filters, and specify a mailbox into which the incoming call notifications will be placed.

When an incoming call matches one of the filters, an NCB describing the call is placed in the mailbox. The Network Process can then read the NCB and accept, reject, or redirect the call.

The programming steps for writing a Network Process are:

When X.25 for OpenVMS delivers an incoming call to an X.25 listener in the X25 ACCESS APPLICATION entity, it creates a mailbox, and places the NCB for the incoming call in the mailbox. Note that these actions are performed only if the maximum number of incoming call activations for the relevant application has not been reached or the Maximum Activations attribute of the APPLICATION entity has been set to zero. If the maximum number has been reached, the call will be cleared.

X.25 for OpenVMS then creates a process under the user name specified in the entry in the APPLICATION entity. This process runs the OpenVMS LOGINOUT image to verify the user name and password from the APPLICATION entity. If they are invalid, the call is cleared. If they are valid, X.25 for OpenVMS:

The command procedure can execute DCL commands, and it can also run a program to accept, redirect, or reject the incoming call.

The programming steps for writing an Access Application are:

Note that it is the responsibility of the user program to confirm RESETs and INTERRUPTs. As RESETs may be received at any time, make sure that your application allows for this. For further information about confirming receipt of RESETS, refer to Section 3.5, “Resetting a Virtual Circuit and Confirming a Reset”. For further information about confirming receipt of INTERRUPTS, refer to Section 3.4, “Transmitting and Confirming Receipt of Interrupts”.

When X.25 for OpenVMS delivers an incoming call to an X.25 listener in the X25 ACCESS APPLICATION entity, it creates a mailbox, and places the NCB for the incoming call in the mailbox. Note that these actions are performed only if the maximum number of incoming call activations for the relevant application has not been reached or the Maximum Activations attribute of the APPLICATION entity has been set to zero. If the maximum number has been reached, the call will be cleared.

X.25 for OpenVMS then creates a process under the user name specified in the entry in the APPLICATION entity. This process runs the OpenVMS LOGINOUT image to verify the user name and password from the APPLICATION entity. If they are invalid, the call is cleared. If they are valid, X.25 for OpenVMS:

The command procedure can execute DCL commands, and it can also run a program to accept, redirect, or reject the incoming call.

The programming steps are as follows:

Note that interrupts and resets are handled by the NV device, and do not require intervention by a user program. For further details of how to use the system services, refer to Chapter 3, Using System Services to Handle Calls.

Your program can declare itself to be a Network Process, and enter its own filters in the X25 Access module.

To receive incoming calls, an X.25 Network Process must direct X25 Access to listen on one or more filters, and specify a mailbox into which the incoming call notifications will be placed.

When an incoming call matches one of the filters, an NCB describing the call is placed in the mailbox. The Network Process can then read the NCB and accept, reject, or redirect the call.

The programming steps are as follows:

Note that interrupts and resets are handled by the NV device, and do not require intervention by the user program.

X.25 for OpenVMS accepts an incoming call when it delivers the call to an X.29 listener in the X25 ACCESS APPLICATION entity.

As the call has been accepted, your program cannot use the system service request $QIO(IO$_ACCESS!IO$M_REDIRECT) to redirect the call to another listener. However, your program may pass the NV device to another process (refer to Chapter 3, Using System Services to Handle Calls).

X.25 for OpenVMS handles incoming calls as follows:

The command procedure can execute DCL commands, and it can also run a program to handle the NV device. The programming steps are as follows:

Your program can enter its own filters in the X25 Access module by declaring itself to be a Network Process.

The programming steps are as follows:

Note that interrupts and resets are handled by the NV device, and do not require intervention by a user program. Refer to Chapter 3, Using System Services to Handle Calls for further details of how to use the system services.

To find the remote DTE address of the calling PAD, you can use either system services, or Digital Command Language (DCL):

The basic steps for writing an X.29 program to make an outgoing call to the PAD at a remote DTE are as follows:

If the remote DTE accepts the request, your program should go through steps 8to 10. Otherwise, your program should perform step 10.

Your program can control the meaning of the control requests for Interrupt and for Indication-of-Break by setting PAD parameter 7 (break). Do this by issuing the system service $QIO(IO$_NETCONTROL,PSI$K_X29_SET) with subfunction PSI$K_X29_PAD_PARAMS. For details of this parameter, refer to the VSI X.25 for OpenVMS Programming Reference manual.

Table 6.1, “PAD Interrupt and Indication-of-Break Messages” summarizes the actions relevant to Interrupt and Indication-of-Break.

Figure 6.1, “Response to INTERRUPT, with PAD Parameter 7 Set to 1”, Figure 6.2, “Response to INTERRUPT, with PAD Parameter 7 Set to 5”, and Figure 6.3, “Response to INTERRUPT, with PAD Parameter 7 Set to 21” show the action of the PAD and the NV device in response to INTERRUPT, with PAD parameter 7 set to 1, 5, and 21.

To set nonstandard parameters, specify a sequence of PAD parameter items as follows:

...and so on.

For details of the nonstandard PAD facilities that are supported, refer to the technical documentation supplied by the PSDN.

The NV Action Descriptor Block is a data structure of between 4 and 20 bytes, comprising:

For symbolic programming, the start location of the action string is PSI$T_X29_ACTION_STRING, and the maximum length of the string is PSI$S_X29_ACTION_STRING.

The action flags occupy the first four bytes. They determine what action the NV driver should take on receiving an Interrupt or an Indication-of-Break. Only the first three bits of byte 0 are used, and these bits contain the following action flags:

The action string PSI$T_X29_ACTION_STRING is a counted string of up to 15 bytes.

Figure 6.4, “NV Action Descriptor Block” illustrates the format of the NV Action Descriptor Block.

The OpenVMS terminal driver can operate in either local-echo or host-echo mode. The OpenVMS system default is host-echo mode. However, the system default can be set to local-echo. Refer to the VSI X.25 for OpenVMS Utilities Guide for details of how to do this.

To set the OpenVMS echo mode, you can either use DCL commands, or issue QIOs.

To set the OpenVMS echo mode with DCL commands, use the command SET TERMINAL.

For local-echo mode, use the following command:

$ SET TERMINAL/LOCAL_ECHO

For host-echo mode, use the following command:

$ SET TERMINAL/NOLOCAL_ECHO

To set the OpenVMS terminal mode using QIOs, issue $QIO(IO$_SETMODE) to the NV device.

To select LOCAL_ECHO mode, set TT$M_NOECHO and TT2$M_LOCALECHO.

To select HOST_ECHO mode, clear TT$M_NOECHO and TT2$M_LOCALECHO.

To set the PAD echo mode, use the system service $QIO(PSI$K_X29_SET) with the subfunction PSI$K_X29_PAD_PARAMS.

Note that in host-echo mode, the user input is echoed by the OpenVMS terminal driver, and the PAD echo must be turned off. Otherwise, the user at the X.29 terminal sees each input character twice.

In local-echo mode, the PAD echoes the user data.

You can set up the OpenVMS terminal driver to communicate with systems which use 7-bit ASCII, by specifying 7-bit ASCII and even parity. To do this, use the following command:

$ SET TERMINAL/NOEIGHT/PARITY=EVEN

You can set up 7-bit ASCII and even parity as the system default. For details of how to do this, refer to the VSI X.25 for OpenVMS Utilities Guide.