Query Line Description (QOLQLIND) API

Required Parameter Group:

Return code

Output

Binary(4)

Reason code

Output

Binary(4)

Number of bytes

Output

Binary(4)

User buffer

Output

Char(*)

Line description

Input

Char(10)

Format

Input

Char(1)

Optional Parameter Group:

Length of user buffer

Input

Binary(4)

Bytes available

Output

Binary(4)

Default Public Authority: *USE

Threadsafe: No

The Query Line Description (QOLQLIND) API queries an existing token-ring, Ethernet, wireless, FDDI, frame relay, or X.25 line description. The data received from the query is placed in the user buffer parameter.

The line description to be queried does not have to be associated with any links the application program has enabled. However, data in the line description may change after it is queried.

Authorities and Locks

None.

Required Parameter Group

Return code

OUTPUT; BINARY(4)

The recovery action to take. See Return and Reason Codes.

Reason code

OUTPUT; BINARY(4)

The error that occurred. See Return and Reason Codes.

Number of bytes

OUTPUT; BINARY(4)

The number of bytes of data returned in the user buffer.

User buffer

OUTPUT; CHAR(*)

The buffer where the data from the query will be received. Any unused space in the buffer will be filled with X'00'. The length of this character structure is determined using User Buffer Format.

User Buffer Format

Format

Group Parameter Passed

Length of Char(*)

256

1 or 2

Yes

Specified by the length user buffer parameter.

Note: You are recommended to set the length user buffer value to a number large enough to hold the system maximum values of virtual circuits, SAPs, and group addresses with additional space left for future needs.

Line description

INPUT; CHAR(10)

The name of the line description to query. An existing token-ring, Ethernet, wireless, FDDI, frame relay, or X.25 line description must be used.

Format

INPUT; CHAR(1)

The format of the data returned in the user buffer. The valid values are as follows:

X'01'

Use format 01.

X'02'

Use format 02.

See Format of Data in the User Buffer for more information.

Optional Parameter Group

Length of user buffer

INPUT; BINARY(4)

The number of bytes available for the API to use in the user buffer parameter. The valid values are from 0 to 32,767.

Notes:

This parameter is required if format 2 is specified in the format parameter. It is optional if format 1 is specified.
If length user buffer is specified, bytes available must also be specified.
If additional information exists that could not be reported, the bytes available parameter will contain a larger value than the bytes returned parameter.

Bytes available

OUTPUT; BINARY(4)

The total number of bytes of available information.

Notes:

This parameter is required if format 2 is specified in the format parameter. It is optional if format 1 is specified.
If bytes available is specified, length user buffer must also be specified.
If the bytes available parameter contains a number larger than the bytes returned parameter, there is additional information that the application cannot access.
If the return code parameter is nonzero, this value is set to zero.

Format of Data in the User Buffer

The data received in the user buffer from the query is made up of two parts. The first portion starts at offset 0 from the top of the user buffer and contains general query data. The format of this data does not depend on value of the format parameter supplied to the QOLQLIND API.

General Query Data

Field

Type

Description

Line description

CHAR(10)

The name of the token-ring, Ethernet, wireless, FDDI, frame relay, or X.25 line description that was queried.

Line type

CHAR(1)

The type of line description that was queried. The valid values are as follows:

X'04'

X.25

X'05'

Token-ring

X'09'

Ethernet

X'0D'

FDDI

X'0E'

Frame relay

X'10'

Wireless

Status

CHAR(1)

The current status of the line description. The valid values are as follows:

X'00'

Varied off

X'01'

Varied off pending

X'02'

Varied on pending

X'03'

Varied on

X'04'

Active

X'05'

Connect pending

X'06'

Recovery pending

X'07'

Recovery canceled

X'08'

Failed

X'09'

Diagnostic mode

X'FF'

Unknown

The second portion of the user buffer starts immediately after the general query data and contains data specific to the type of line description that was queried. The format of this data depends on the value of the format parameter supplied to the QOLQLIND API.

LAN Specific Data-Format 01

Field

Type

Description

Local adapter address

CHAR(6)

Specifies, in packed form, the local adapter address of this line. The special value of X'000000000000' indicates that the preset default address for the adapter card was configured. However, the line description must be varied on before this address can be retrieved.

Line speed

CHAR(1)

The speed of this line. The valid values are as follows:

X'01'

4 megabits/second

X'02'

10 megabits/second

X'03'

16 megabits/second

X'04'

100 megabits/second

Line capability

CHAR(1)

The capability of this line. The valid values are as follows:

X'00'

Non-Ethernet

X'01'

Ethernet Version 2

X'02'

Ethernet 802.3

X'03'

Both Ethernet Version 2 and Ethernet 802.3

Line frame size

BINARY(2)

The maximum frame size possible on this line.

Ethernet Version 2 frame size

BINARY(2)

The maximum size for Ethernet Version 2 frames. This will be 1502 if the line is capable of Ethernet Version 2 traffic. Otherwise, it will be zero.

Number of SSAPs

BINARY(2)

The number of source service access points (SSAPs) configured for this line.

Note: The following 3 rows are repeated for each SSAP configured for this line.

SSAP

CHAR(1)

The configured source service access point.

SSAP type

CHAR(1)

The SSAP type. The valid values are as follows:

X'00'

Non-SNA SSAP

X'01'

SNA SSAP

SSAP frame size

BINARY(2)

The maximum frame size allowed on this SSAP.

Number of group addresses

BINARY(2)

The number of group addresses configured for this line.

Note: This will always be zero for a token-ring line description.

Note: The following row is repeated for each group address configured for this line.

Group address

CHAR(6)

Specifies a group address, in packed form.

LAN Specific Data-Format 02

Field

Type

Description

Local adapter address

CHAR(6)

Line speed

CHAR(1)

The speed of this line. The valid values are as follows:

X'01'

4 megabits/second

X'02'

10 megabits/second

X'03'

16 megabits/second

X'04'

100 megabits/second

X'05'

Frame relay (line speed is specified separately)

Line capability

CHAR(1)

The capability of this line. The valid values are as follows:

X'00'

Non-Ethernet

X'01'

Ethernet Version 2

X'02'

Ethernet 802.3

X'03'

Both Ethernet Version 2 and Ethernet 802.3

Line frame size

BINARY(2)

The maximum frame size possible on this line.

Ethernet Version 2 frame size

BINARY(2)

The maximum size for Ethernet Version 2 frames. This will be 1502 if the line is capable of Ethernet Version 2 traffic. Otherwise, it will be zero.

Functional address field

CHAR(6)

The hexadecimal functional address configured for the line. An address of X'000000000000' indicates there are no functional addresses configured on this line description.

Note: For additional information on functional addresses, refer to the Token-Ring Architecture Reference manual, SC30-3374.

Number of group addresses

BINARY(2)

The number of group addresses configured for this line. This value is valid for Ethernet and wireless line descriptions only.

Offset to group addresses

BINARY(2)

Offset within this structure to the array of group addresses

Number of SSAPs

BINARY(2)

The number of SSAPs configured for this line.

Offset to SSAPs

BINARY(2)

Offset within this structure to the array of SSAPs

FR line speed

BINARY(4)

Frame relay line speed. This value is valid only when the line type field is set to X'0E'.

Reserved

CHAR(*)

Reserved for extension

Note: The following row is duplicated by the number of group addresses.

Group address

CHAR(6)

Specifies a group address, in packed form.

Note: The following three rows are duplicated by the number of SSAPs.

SSAP

CHAR(1)

The configured source service access point.

SSAP type

CHAR(1)

The SSAP type. The valid values are as follows:

X'00'

Non-SNA SSAP

X'01'

SNA SSAP

SSAP frame size

BINARY(2)

The maximum frame size allowed on this SSAP.

X.25 Specific Data-Format 01

Field

Type

Description

Local network address length

CHAR(1)

Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the local network address.

Local network address

CHAR(9)

Specifies, in BCD, the local network address of this line.

Extended network addressing

CHAR(1)

Specifies whether network addressing is extended to permit the use of 17 digits in an address. The valid values are as follows:

X'01'

Network addresses may be up to 15 digits

X'02'

Network addresses may be up to 17 digits

Address insertion

CHAR(1)

Specifies whether the system inserts the local network address in call request and call accept packets. The valid values are as follows:

'Y'

The local network address is inserted in call request and call accept packets.

'N'

The local network address is not inserted in call request and call accept packets.

Modulus

CHAR(1)

The X.25 modulus value. The valid values are as follows:

X'01'

Modulus 8

X'02'

Modulus 128

X.25 DCE support

CHAR(1)

Specifies whether the system communicates using the integrated X.25 DCE support. This allows the system, acting as the DCE, to communicate with another system without going through an X.25 network. The valid values are as follows:

X'01'

The system does not communicate using the X.25 DCE support

X'02'

The system does communicate using the X.25 DCE support

X'03'

The system negotiates whether it communicates using the X.25 DCE support.

Transmit maximum packet size

BINARY(2)

The transmit maximum packet size configured for this line.

Receive maximum packet size

BINARY(2)

The receive maximum packet size configured for this line.

Transmit default packet size

BINARY(2)

The transmit default packet size configured for this line.

Receive default packet size

BINARY(2)

The receive default packet size configured for this line.

Transmit default window size

BINARY(1)

The transmit default window size configured for this line.

Receive default window size

BINARY(1)

The receive default window size configured for this line.

Number of logical channels

BINARY(2)

The number of logical channels configured for this line.

Note: The following 4 rows are repeated for each logical channel configured for this line

Logical channel group number

CHAR(1)

The logical channel group number. This together with the logical channel number makes up the logical channel identifier.

Logical channel number

CHAR(1)

The logical channel number. This together with the logical channel group number makes up the logical channel identifier.

Logical channel type

CHAR(1)

The logical channel type. The valid values are as follows:

X'01'

Switched virtual circuit (SVC).

X'02'

Permanent virtual circuit (PVC) that is eligible for use by a network controller.

Note: This does not necessarily mean that this PVC is available for use. Another job running on the network controller attached to this line may already have this PVC in use.

X'22'

PVC that is not eligible for use by a network controller. For example, a PVC that is already attached to an asynchronous controller description.

Logical channel direction

CHAR(1)

The direction of calls allowed on the logical channel. The valid values are as follows:

X'00'

Not applicable (PVC logical channel).

X'01'

Only incoming calls are allowed on this logical channel.

X'02'

Only outgoing calls are allowed on this logical channel.

X'03'

Both incoming and outgoing calls are allowed on this logical channel.

X.25 Specific Data-Format 02

Field

Type

Description

Local network address length

CHAR(1)

Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the local network address.

Local network address

CHAR(9)

Specifies, in BCD, the local network address of this line.

Extended network addressing

CHAR(1)

Specifies whether network addressing is extended to permit the use of 17 digits in an address. The valid values are as follows:

X'01'

Network addresses may be up to 15 digits

X'02'

Network addresses may be up to 17 digits

Address insertion

CHAR(1)

Specifies whether the system inserts the local network address in call request and call accept packets. The valid values are as follows:

'Y'

The local network address is inserted in call request and call accept packets.

'N'

The local network address is not inserted in call request and call accept packets.

Modulus

CHAR(1)

The X.25 modulus value. The valid values are as follows:

X'01'

Modulus 8

X'02'

Modulus 128

X.25 DCE support

CHAR(1)

Specifies whether the system communicates using the integrated X.25 DCE support. This allows the system, acting as a DCE, to communicate with another system without going through an X.25 network. The valid values are as follows:

X'01'

The system does not communicate using the X.25 DCE support

X'02'

The system does communicate using the X.25 DCE support

X'03'

The system negotiates whether it communicates using the X.25 DCE support.

Transmit maximum packet size

BINARY(2)

The transmit maximum packet size configured for this line.

Receive maximum packet size

BINARY(2)

The receive maximum packet size configured for this line.

Transmit default packet size

BINARY(2)

The transmit default packet size configured for this line.

Receive default packet size

BINARY(2)

The receive default packet size configured for this line.

Transmit default window size

BINARY(1)

The transmit default window size configured for this line.

Receive default window size

BINARY(1)

The receive default window size configured for this line.

Number of logical channels

BINARY(2)

The number of logical channels configured for this line.

Maximum frame size

BINARY(2)

The maximum frame size configured in the line description. The valid values are as follows:

1024
2048
4096

ISDN interface

CHAR(1)

Indicates if the line uses an ISDN interface. The valid values are as follows:

X'00'

X.25 line does not run over an ISDN interface.

X'01'

X.25 line runs over an ISDN interface.

Note: The following section applies only if the ISDN interface is specified as X'01'. The sections of format 02 on the call direction field to the offset to logical channel array field are not meaningful if an ISDN interface is not used and will return zeros in these fields if an ISDN interface is not specified.

Call direction

CHAR(1)

The direction of the ISDN call. The valid values are as follows:

X'00'

Incoming switched call

X'01'

Outgoing switched call

X'02'

Either a nonswitched call or not ISDN-capable.

Note: The following fields are only meaningful if the line description is switched.

Length of call ID information

BINARY(2)

Length includes type and plan, as described below, and the call identify information element.

Type of number and numbering plan

BINARY(1)

Type and plan as represented by the following bit sequence: tttt pppp, where tttt equals the category of the calling number and pppp equals the numbering plan identification used when the calling party number was created.

Type '0000 xxxx'

Unknown number

Type '0001 xxxx'

International number

Type '0010 xxxx'

National number

Type '0011 xxxx'

Network specific number

Type '0100 xxxx'

Subscriber number

Type '0110 xxxx'

Abbreviated number

Type '0111 xxxx'

Reserved for extension

Plan 'xxxx 0000'

Unknown

Plan 'xxxx 0001'

ISDN/telephony numbering plan

Plan 'xxxx 0011'

Data numbering plan

Plan 'xxxx 0100'

Telex numbering plan

Plan 'xxxx 1000'

National standard numbering plan

Plan 'xxxx 1001'

Private numbering plan

Plan 'xxxx 1111'

Reserved for extension

Note: Refer to CCITT Recommendation Q.931 for more information.

Reserved

BINARY(1)

Reserved for extension.

Call ID digits

CHAR(128)

Calling party number of remote system received off the D-channel, specified in IA5 code (ASCII).

Length of subaddress information

BINARY(2)

Length includes type, odd-even indicator, and the subaddress information element. Values can range from X'0001' to X'00FF'. The user specified subaddress is restricted to 20 bytes.

Type of subaddress and odd-even indicator

BINARY(1)

Type and odd-even indicator as represented by the following bit sequence: tttt ixxx, where tttt equals the type of subaddress and i equals whether the address has an even or odd number of digits.

Type '0000 xxxx'

NSAP

Type '0010 xxxx'

User specified

Type remaining

Reserved

Plan 'xxxx 0xxx'

Even number of address digits

Plan 'xxxx 1xxx'

Odd number of address digits

Note: Refer to CCITT Recommendation Q.931 for more information.

Reserved

BINARY(1)

Reserved for extension.

Subaddress

CHAR(128)

Calling party subaddress information, received from the D-channel, specified in the IA5 code set (a superset of ASCII).

Offset to logical channel array

BINARY(2)

Offset within this structure to the array of logical channels

Reserved

CHAR(*)

Reserved for extension

Note: The following 5 rows are repeated for each logical channel configured for this line. This section is not specific to ISDN interfaces.

Logical channel group number

CHAR(1)

The logical channel group number. This together with the logical channel number makes up the logical channel identifier.

Logical channel number

CHAR(1)

The logical channel number. This together with the logical channel group number makes up the logical channel identifier.

Logical channel type

CHAR(1)

The logical channel type. The valid values are as follows:

X'01'

Switched virtual circuit (SVC).

X'02'

Permanent virtual circuit (PVC) that is eligible for use by a network controller.

Note: This does not necessarily mean that this PVC is available for use. Another job running on the network controller attached to this line may already have this PVC in use.

Type of calls allowed

CHAR(1)

Types of calls supported on the logical channel. The valid values are as follows:

X'00'

Not applicable (PVC logical channel).

X'01'

Only incoming calls are allowed on this logical channel.

X'02'

Only outgoing calls are allowed on this logical channel.

X'03'

Both incoming and outgoing calls are allowed on this logical channel.

Availability

CHAR(1)

Specifies whether the virtual circuit is available or currently is in use. The valid values are as follows:

X'00'

Available

X'01'

In use

Return and Reason Codes

Return and Reason Codes for the QOLQLIND API

Return / Reason Code

Meaning

Recovery

00/0000

Operation successful.

Continue processing.

Notes:

When calling QOLQLIND (specifying an X.25 line description, format 1, and not specifying group parameters), up to 54 logical channels can be contained in the user buffer because it is limited to a size of 256 bytes. To increase the size of the user buffer so that it is sufficient to contain all of the logical channels, the group parameters should be used. To determine if there are more than 54 logical channels configured, use the Display Line Description (DSPLIND) command.
The application should check to ensure that the bytes available value returned is less than or equal to the bytes returned value. If so, there is additional information that the application may want to receive. To receive this information, the application must re-issue the call, specifying the length user buffer equal to or greater than the bytes available value.

81/9999

Internal system error detected. Escape message CPF91F0 will be sent to the application program when this return and reason code is received.

See messages in the job log for further information. Report the problem using the ANZPRB command.

83/1005

Format not valid.

Correct the format parameter. Try the request again.

83/1014

Length user buffer value not valid. This value cannot be negative.

Correct the length user buffer value to a zero or a positive value less than 32K and try the operation again.

83/1020

Group parameters not valid.

All parameters within the group must be specified. Correct the parameter list and try the request again.

83/1021

Required parameter not specified.

Format 2 was requested and the required group parameters (length user buffer and bytes available) were not specified. Correct the parameter list and try the request again.

83/1998

User buffer parameter too small.

Either the length user buffer value is negative or it contains a positive value and the system was not able to put the data into the user buffer provided by the application. Correct the application and try the request again.

83/2000

Line description not configured for token-ring, Ethernet, wireless, or X.25.

Correct the line description parameter. Try the request again.

83/2002

Not authorized to line description.

Get authorization to the line description. Try the request again.

83/2006

Line description not found.

Correct the line description parameter. Try the request again.

83/2007

Line description damaged.

Delete and re-create the line description. Try the request again.

Error Messages

Message ID

Error Message Text

CPF3C90 E

Literal value cannot be changed.

CPF91F0 E

Internal system error.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R1

[ Back to top | Communications APIs | APIs by category ]