Query Line Description (QOLQLIND) API

  Required Parameter Group:

1 Return code Output Binary(4)
2 Reason code Output Binary(4)
3 Number of bytes Output Binary(4)
4 User buffer Output Char(*)
5 Line description Input Char(10)
6 Format Input Char(1)

  Optional Parameter Group:

7 Length of user buffer Input Binary(4)
8 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(*)
1 No 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:

  1. This parameter is required if format 2 is specified in the format parameter. It is optional if format 1 is specified.

  2. If length user buffer is specified, bytes available must also be specified.

  3. 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:

  1. This parameter is required if format 2 is specified in the format parameter. It is optional if format 1 is specified.

  2. If bytes available is specified, length user buffer must also be specified.

  3. If the bytes available parameter contains a number larger than the bytes returned parameter, there is additional information that the application cannot access.

  4. 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) 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
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:

  1. 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.

  2. 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 ]