Virtual Circuit Definitions

The virtual circuits (switched and permanent) for X.25 are defined using the TERM definition line in the TTGEN configuration file. The virtual circuit definition defines those parameters required for level 3 of the X.25 protocol.

A sample virtual circuit definition is given below:

Term 120  01:4:1  X25.SVC.AUTO  X25_VC_Q0_D0    ~
   79 1 201 0 1  CALL:226633011  "X.25 SVC out to 33011"
Udata  "USERDATA"

This line defines a virtual circuit terminal on Mux 1, port 4, subchannel 1, which will issue an outgoing call when enabled and which will be automatically recovered after a link failure. The outgoing call will be made to the remote subscription address 226633011 unless overridden. User data of "USERDATA" will be included in outgoing calls made on this virtual circuit.

The Terminal-Definition takes the following general format:

Term  zlu  mux:port:subc device poll select 
	              appl_no inst_no brch_no wkst_no area_no CALL:<addr> name
	      <Option keyword>       <value>
      <Udata keyword>        <value>

More specific information on the parameters in the VC terminal definition follows.

zlu

This number (120 in the example) assigns a unique reference number for this Virtual Circuit terminal, which is used by the ACC X.25 software to relate errors displayed to a specific X.25 Virtual Circuit. The ZLU number is also used in the ACC X.25 API calls to control and configure specific X.25 Virtual Circuits.

mux:port:subc

The Mux must have been defined in a Mux Definition statement. The port must have been defined in a Port Definition statement. The ":subc" information must be supplied for a 4-port E1/T1 card and should be omitted for all other card types. The subc must have been defined in a Subch Definition statement.

This Mux and port must be valid for X.25 and there must be an X.25 link terminal defined on the port or subchannel.

device

The device parameter defines the type of virtual circuit being defined. The values (as defined in /opt/acc/cfg/zcomdevice.txt) are:

X.25.PVC	PVC
X.25.SVC	SVC outgoing
X.25.SVC.OUT	SVC outgoing
X.25.SVC.AUTO	SVC outgoing - call on enable
X.25.SVC.IN	SVC incoming, null call address
X.25.SVC.IO	SVC incoming/outgoing calls, null call address
X.25.SVC.NULL	SVC incoming/outgoing call on enable, null call address
X.25.SVC.IO.D	SVC incoming/outgoing call on enable, deactivate after message

poll/select

This parameter also uses keywords to specify a number of subparameters encoded into the 'POLL' and 'SELECT' fields. For the virtual circuit definition, this parameter specifies D-bit assignments, packet size, packet window size (for PVCs). For more information about this field, refer to “Configuration Parameters Definition” section below.

appl. no.

Application number, as for a normal terminal.

inst. no.

Institution number, as for a normal terminal.

brch. no.

Branch number, as for a normal terminal.

wkst. no.

Workstation number, as for a normal terminal.

area no.

Area number, as for a normal terminal.

call (dte)

For an 'X25.SVC.IN' or 'X25.SVC.IO' this number specifies the remote X.121 subscription address from which this virtual circuit will accept an incoming call. If omitted, then any remote address will be allowed to establish a call on this virtual circuit and the address will remain set in the physical terminal table from then on. An 'X25.SVC.NULL' is basically the same as an 'X25.SVC.IO' but is not allowed to have a call address initially configured, and when the virtual circuit changes state to the IDLE state the address is cleared back to NULL. For an 'X25.SVC.AUTO' or 'X25.SVC.IO' this number is required to set the X.25 address to which a call will be made when the SVC terminal is enabled.

call (dce)

For an 'X25.SVC.IN' or 'X25.SVC.IO' this number specifies the X.121 subscription address which this virtual circuit will accept as the called address in an incoming call. If omitted, then any called address will be accepted and a call established on this virtual circuit. For an X25.SVC, X25.SVC.AUTO or X25.SVC.IO this number is not required.

The call number is not specified for a permanent virtual circuit.

name

Choose a meaningful description of the X.25 virtual circuit, preferably including the remote subscription address where such is specified. This field is used in some ZMNTR displays.

option

Option Word Override (optional). This keyword allows you to override the value of the device option word parameter for this virtual circuit. This is useful for requesting that receiving applications be notified when CALL, CALL conf, RESET, or CLEAR is received, or for specifying that an acknowledgment is required from an application for incoming calls. These options are described in the section "Device Option Word Definition" below.

Udata

This parameter allows X.25 call user data to be specified for X25.SVC.AUTO, X25.SVC.IO or X25.SVC virtual circuits which will generate outgoing calls. This call user data will be stored in a logical terminal table (LTT) extension area.

The Udata entry is related to the previous Lterm or Term entry that came before it. In other words, the affected LTT extension area belongs to the LTT created for the previous Lterm or Term entry. A Udata entry after a Pterm entry will cause an error to be reported.

Call user data can be up to 16 bytes in length. These bytes may be ASCII characters (one character per byte) and non-ASCII byte values. You must specify a Udata string within a single pair of double quotes following the Udata keyword. Example:

Udata "abcdef"

A non-ASCII byte value may be specified using the following notation: "\0<octal_value>"

'0' is the zero ASCII character. <octal_value> is the octal representation of the byte value that you want. Any octal value greater than that which can be held in a byte ("\0377") will be flagged as an error. Note that when specifying a byte value of zero, you must use "\00". If you place leading zeroes between the required leading zero and your <octal_value>, these extra leading zeroes will be ignored.

You may also intermix ASCII characters and the non-ASCII byte notation. Example:

Udata "abc\045def"

This will place the ASCII characters "abc" into the Udata buffer, followed by a binary octal value 45 in the next byte, followed by the ASCII characters "def".

If you want the characters "\0" to be interpreted as ASCII characters for Udata rather than as an indicator of a non-ASCII binary byte, then place a '\' in front of them to "escape" them. Example:

Udata "abc\\045def"

This will place the ASCII characters "abc\045def" into the Udata buffer.

Note that the X25UDT Logical-Data area must be defined before you can use the Udata parameter. Refer to the “Reserved Logical Data Area Definition” section on how to allocate this storage.

Note that call user data is always assumed to start from byte 0 in its X25UDT Logical-Data area. Contrast this with Ldata, which can be offset anywhere within its Logical-Data area. Udata and Ldata areas in the Logical-Data area must not overlap or go beyond the end of the Logical-Data area. If you wish, you are allowed to define the X25UDT Logical-Data area to be bigger than is needed for Udata and place Ldata entries in the remaining space in the Logical-Data area after the Udata area.

Udata and Ldata are associated with the Term or Lterm entry previously defined before them. Term and Lterm entries have application numbers associated with them. Udata and Ldata reside in a Logical-Data area that has an application number associated with it. The application number of this Logical-Data area and the Term or Lterm entry must match, or the application number of the Logical-Data area must be zero (0). Else an error will be reported.

(Note that instead of using the Udata parameter, the user could specify call user data using the Ldata parameter. However, the user would have to specify some things explicitly using the Ldata parameter whereas the Udata parameter simplifies this process by automatically determining some of these things. For example, which Logical-Data area to use, the size of the data. In particular, Udata allows the user to more easily intermix ASCII characters and non-ASCII bytes in the same buffer. This could be done with multiple Ldata parameters, but it would require painstaking attention to detail to make sure the offsets and buffer locations were correct.)

Configuration Parameters Definition

The following configuration values are currently defined for use in X.25 configuration as a replacement for the POLL and SELECT address fields. These values are used as a symbolic way of configuring the associated two 16-bit hexadecimal values. For example, X25_VC_DFLT_Q_D can be used to set the POLL address to 0 and the SELECT address to 0. If a particular desired configuration value is not provided by these values, then two hexadecimal values can be used instead.

  X25_VC_DFLT_Q_D   0000h   0000h
  X25_VC_Q0_D0      1000h   0000h

The POLL and SELECT words configure the following parameters for the X.25 Virtual Circuit (terminal type 26) configuration:

D: provide D-bit capability (end-to-end packet acknowledgment) for automatic call packet
Set D: is set to indicate above value should be used (else use default in X.25 Link Terminal's Option word)
Logical Channel No.: Logical Channel Number is defined here for PVCs only
Packet Size: only set for PVCs
Window Size: only set for PVCs

They are formatted in the POLL and SELECT words as follows:

Poll Word for X.25 PVC Configuration

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
	D		STD	Logical Channel Number (LCN)

D: 1 => Allow data packets with the D-bit set to 1 to be sent over this PVC.
STD: 1 => take D value from bit 14 of POLL word, else take D value from X.25 Link Option word D bit
LCN: PVCs Set for PVCs as per subscription

Poll Word for X.25 SVC Configuration

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
	D		STD	Not Used (must be 0)

D: 1 => Set D-bit (End-to-End packet acknowledge) in auto call packet
STD: 1 => take D value from bit 14 of POLL word, else take D value from X.25 Link Option word D bit

Select Word for X.25 PVC Configuration

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Out-packet					Out-window			In-packet				0	In-window

Out_packet In_packet

The packet size is configured here for PVCs only. The packet sizes available are:

0 - 128		8 - 256
1 - Reserved		9 - 512
2 - Reserved		10 - 1024
3 - Reserved		11 - 2048
4 - 16		12 - 4096
5 - 32		13 - Reserved
6 - 64		14 - Reserved
7 - 128		15 - 240

Out_window In_window

The window size is configured here for PVCs only. May be from one (1) to seven (7) - (0 is not allowed).

Select Word for X.25 SVC Configuration

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Not Used (default to 0)

VC Device Option Word Definition

The option word for the X.25 logical channel (VC) terminal defines whether the channel is to be a permanent or switched virtual circuit (PVC or SVC), the type of SVC, and other operational characteristics to be used between the application and the X.25 protocol driver. Note that the number of VCs of each type (PVC, IN, OUT, IO) should match the subscription parameters specified in the X.25 link terminal definition.

The format of the X.25 logical channel (VC) terminal option word is as follows:

15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Not Used (0)				Out	RSET	CNT	ACK	VCT	IN	CLL	NLL	DEA	APD	INTC	0

OUT

If set, then outgoing calls are allowed on this SVC. If both the OUT and IN bits are set, this is a two-way SVC.

RSET

If set, then the application will confirm inbound VC Resets using the zx25reset_conf() routine. If clear, then the X.25 protocol driver will automatically send a Reset Confirm packet when a VC Reset Request is received.

CNT

If set, then all applications setup as receivers for this VC ZLU will be notified through unsolicited status messages when Call, Call Accept, Reset Request, Reset Confirm, Clear Request, and Clear Confirm packets are received. Note that the status message will also contain the pertinent data from the X.25 level 3 protocol packet. If the application needs to receive facility, call user data, called and calling addresses, etc., then this bit must be set. If this bit is clear, then the application will not be notified.

ACK

If set, the application will confirm incoming CALLs using zx25callacc(). If clear, then the X.25 protocol driver will automatically accept an inbound call by sending an X.25 level 3 Call Accept protocol packet. Note that if this bit is set, the CNT bit should also be set so that the application is notified that an inbound call has arrived.

VCT

Virtual circuit type - 0=SVC, 1=PVC.

IN

If set, then incoming Calls are allowed.

CLL

This bit controls the actions taken on a PVC/SVC when it is enabled or on recovery of an X.25 link. If set, an outgoing Call Request is automatically issued for a SVC when the SVC ZLU is enabled or the X.25 link is restarted. For PVCs, a Reset Request is automatically issued when the PVC ZLU is disabled. If the CLL bit is clear, no action is taken.

NLL

If set, the Call address (X.121) for this SVC is automatically set to NULL when the call is cleared. This address is kept in the Physical Terminal Table ptcnfg field. For inbound calls it specifies that calling address that will be accepted in an inbound call. For outbound calls placed as a result of an SVC enable or when the called address was not supplied to the zx25callout() routine, the address in the ptcnfg field is used as the calling address in the Call Request packet. If the address is automatically set to NULL, then an inbound call from any calling address will be acceptable. If this bit is clear, the Call address in ptcnfg is not set to NULL when the call is cleared. Note that for inbound calls, the calling address is automatically placed into the ptcnfg field. For outbound calls, the called address is placed into the ptcnfg field.

DEA

If set, the VC ZLU is deactivated after every received message. A deactivated VC will generate an X.25 level 3 RNR when an inbound data packet is received. Sending a zcntl() to activate the VC will generate an X.25 level 3 RR packet and allow one more inbound data packet to be received. If this bit is clear, the VC ZLU will only be deactivated through explicit zcntl() calls by the application.

APD

This bit is used to control how inbound data packets which have the D-bit set, should be acknowledged and when definite write completion status messages are returned for transmitted messages which have the D-bit set. If this bit is zero, then inbound data packet are automatically acknowledged (RR'd) by the ACC X.25 firmware and write completion status (definite) is received when outbound data messages are RR'd at level 2. If this bit is set to one, application end-to-end acknowledgment is selected. Inbound data messages or message fragments are not RR'd automatically by the firmware and outbound data messages receive write completion (definite) status only after a level 3 acknowledgment (RR) has been received. When setting this bit to one, special application programming is required! See the section on “D-Bit Handling” in Chapter 4 “X.25 Application Programming” for a description of the application programming rules.




	WARNING! Using end-to-end acknowledgments with the D-bit set in data messages can severely reduce the maximum achievable throughput on a VC.

INTC

This bit is used to control how confirmations are handled for inbound interrupt data packets. If this bit is zero, then inbound interrupt data packets are automatically confirmed by the ACC X.25 firmware. If this bit is set to one, application handling of interrupt confirms is selected. Inbound interrupt data messages are not confirmed automatically by the firmware. When setting this bit to one, special application programming is required! See the section on “Receiving and Confirming Interrupt Data” in Chapter 4 “X.25 Application Programming” for a description of the application programming rules.

Seven possible valid combinations of these option bits are covered by the predefined device types defined in /opt/acc/cfg/zcomdevice.txt.

Predefined Name	VC Type	Description	Option Word
X25.SVC	SVC	outgoing calls	0x800
X25.SVC.IN	SVC	incoming calls, null call address	0x050
X25.SVC.AUTO	SVC	outgoing calls on enable	0x820
X25.SVC.OUT	SVC	outgoing calls	0x800
X25.SVC.IO	SVC	in/out going calls, null call address	0x850
X25.SVC.NULL	SVC	in/out going calls, null call address	0x850
X25.SVC.IO.D	SVC	in/out going, deactivate after message	0x868
X25.PVC	PVC		0x080

One of these predefined types is typically used in the device parameter of the virtual circuit terminal definition statement.

Additional customization of the option words may be achieved either by modifying zcomdevice.txt and using the 'ZDGEN' program to create a new device type, or by using the "option" parameter.

'ZDGEN' and 'TTGEN' are documented in the ACC Utilities Reference Guide.