Query Line Description (QOLQLIND) API
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:
- 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.
- This parameter is required if format 2 is specified in the format
parameter. It is optional if format 1 is specified.
- 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.
- This parameter is required if format 2 is specified in the format
parameter. It is optional if format 1 is specified.
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:
|
||||||||||||||||||||||
Status | CHAR(1) | The current status of the line
description. The valid values are as follows:
|
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:
|
||||||||
Line capability | CHAR(1) | The capability of this line. The
valid values are as follows:
|
||||||||
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:
|
||||||||
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:
|
||||||||||
Line capability | CHAR(1) | The capability of this line. The
valid values are as follows:
|
||||||||||
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:
|
||||||||||
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:
|
||||||||
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:
|
||||||||
Modulus | CHAR(1) | The X.25 modulus value. The valid
values are as follows:
|
||||||||
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:
|
||||||||
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:
|
||||||||
Logical channel direction | CHAR(1) | The direction of calls allowed on the
logical channel. The valid values are as follows:
|
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:
|
||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||
Modulus | CHAR(1) | The X.25 modulus value. The valid
values are as follows:
|
||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||
ISDN interface | CHAR(1) | Indicates if the line uses an ISDN
interface. The valid values are as follows:
|
||||||||||||||||||||||||||||
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:
|
||||||||||||||||||||||||||||
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.
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.
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:
|
||||||||||||||||||||||||||||
Type of calls allowed | CHAR(1) | Types of calls supported on the
logical channel. The valid values are as follows:
|
||||||||||||||||||||||||||||
Availability | CHAR(1) | Specifies whether the virtual circuit
is available or currently is in use. The valid values are as follows:
|
Return and Reason Codes
Return and Reason Codes for the QOLQLIND API
Return / Reason Code | Meaning | Recovery |
---|---|---|
00/0000 | Operation successful. | Continue processing.
Notes:
|
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