Enable Link (QOLELINK) API
| 1 | Return code | Output | Binary(4) |
| 2 | Reason code | Output | Binary(4) |
| 3 | Data unit size | Output | Binary(4) |
| 4 | Data units created | Output | Binary(4) |
| 5 | LAN user data size | Output | Binary(4) |
| 6 | X.25 data unit size | Input | Binary(4) |
| 7 | Input buffer | Input | Char(20) |
| 8 | Input buffer descriptor | Input | Char(20) |
| 9 | Output buffer | Input | Char(20) |
| 10 | Output buffer descriptor | Input | Char(20) |
| 11 | Key length | Input | Binary(4) |
| 12 | Key value | Input | Char(256) |
| 13 | Qualified queue name | Input | Char(20) |
| 14 | Line description | Input | Char(10) |
| 15 | Communications handle | Input | Char(10) |
Optional Parameter Group:
| 16 | Queue type | Input | Char(1) |
| 17 | Network interface description | Input | Char(10) |
| 18 | Extended operations | Input | Char(1) |
Default Public Authority: *USE
Threadsafe: No
The Enable Link (QOLELINK) API enables a link for input and output on a communications line. The communications line, described by the line description parameter, must be a token-ring, Ethernet, wireless, FDDI, or X.25 line. The link being enabled can only be accessed within the job in which the QOLELINK API was called.
Before calling the QOLELINK API to enable a link, you must configure the following objects:
- Token-ring, Ethernet, wireless, FDDI, or X.25 line description
- Data queue or user queue
- Network interface description for X.25 networks running over ISDN
See Configuring User-Defined Communications Support for more information on configuration.
The QOLELINK API creates the input and output buffers and buffer descriptors used for the link being enabled. The network controller description and the network device description, associated with the link being enabled, are also created, if necessary. In addition, the following are varied on, if necessary.
- Line description
- Network controller description
- Network device description
- Network interface descriptions used by the line description
If the X.25 switched network interface list has multiple network interface
descriptions configured, all of them can be varied on at one time. For more
information on varying on network interface descriptions, see the Communications Management 
manual.
When the QOLELINK API returns, your application program should examine the codes to determine the status of the link. Successful return and reason codes (both zero) indicate the link is being enabled and an enable-complete entry will be sent to the data queue or user queue specified on the call to the QOLELINK API when the enable operation completes. See Enable-Complete Entry for more information on the enable-complete entry. Unsuccessful return and reason codes indicate the link could not be enabled and the enable-complete entry will not be sent to the data queue or user queue. Return and Reason Codes provides more information on the QOLELINK API return and reason codes.
Authorities and Locks
- User Space Authority
- *READ
- User Space Library Authority
- *USE and *ADD. *OBJOPR plus *READ is equivalent to *USE.
- User Space Lock
- *EXCL
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.
- Data unit size
- OUTPUT; BINARY(4)
The total number of bytes allocated for each data unit in the input and output buffers. For token-ring links, this includes user data (LAN user data size parameter), general LAN header information, and optional routing information. For Ethernet, wireless, and FDDI links, this includes user data (LAN user data size parameter) and general LAN header information. For X.25 links, this includes user data (X.25 user data size parameter). For more information on the general LAN header, see Return and Reason Codes.
- Data units created
- OUTPUT; BINARY(4)
The number of data units created for the input buffer and the output buffer. This parameter also specifies the number of elements created for the input buffer descriptor and the output buffer descriptor. The only valid value is:
8 All protocols Note: Because user-defined communications support always returns an 8, you should write your application program to avoid having to recompile should this value ever change.
- LAN user data size
- OUTPUT; BINARY(4)
The number of bytes allocated for token ring, Ethernet, wireless, or FDDI in each data unit of the input and output buffers. This does not include general LAN header information and optional routing information.
The content of this parameter is only valid when enabling a token-ring, Ethernet, wireless, or FDDI link.
Note: The maximum amount of token-ring, Ethernet, wireless, or FDDI user data that can be sent or received in each data unit is determined on a service access point basis in the line description or by the 1502 byte maximum for Ethernet Version 2 frames, and may be less than the LAN user data size. See Query Line Description (QOLQLIND) API for information on retrieving these values.
- X.25 data unit size
- INPUT; BINARY(4)
The number of bytes allocated for X.25 user data in each data unit of the input and output buffers. This is equal to the maximum amount of X.25 user data that can be sent or received in each data unit. The content of this parameter is only valid when enabling an X.25 link.
Range 512 bytes-4096 bytes
- Input buffer
- INPUT; CHAR(20)
The name and library of the input buffer that the QOLELINK API creates for this link. The first 10 characters specify the name for the input buffer and the second 10 characters specify the name of an existing library that the input buffer will be created in. Both entries are left-justified. The special values of *LIBL and *CURLIB can be used for the library name.
Note: A user space object with the same name as the input buffer must not already exist in the specified library.
- Input buffer descriptor
- INPUT; CHAR(20)
The name and library of the input buffer descriptor that the QOLELINK API creates for this link. The first 10 characters specify the name of the input buffer descriptor and the second 10 characters specify the name of an existing library that the input buffer descriptor will be created in. Both entries are left-justified. The special values of *LIBL and *CURLIB can be used for the library name.
Note: A user space object with the same name as the input buffer descriptor must not already exist in the specified library.
- Output buffer
- INPUT; CHAR(20)
The name and library of the output buffer that the QOLELINK API creates for this link. The first 10 characters specify the name of the output buffer and the second 10 characters specify the name of an existing library that the output buffer will be created in. Both entries are left-justified. The special values of *LIBL and *CURLIB can be used for the library name.
Note: A user space object with the same name as the output buffer must not already exist in the specified library.
- Output buffer descriptor
- INPUT; CHAR(20)
The name and library of the output buffer descriptor that the QOLELINK API creates for this link. The first 10 characters specify the name of the output buffer descriptor and the second 10 characters specify the name of an existing library that the output buffer descriptor will be created in. Both entries are left-justified. The special values of *LIBL and *CURLIB can be used for the library name.
Note: A user space object with the same name as the output buffer descriptor must not already exist in the specified library.
- Key length
- INPUT; BINARY(4)
The key length when using a keyed data queue or user queue.
0 The data queue or user queue is not keyed. Range 1-256
- Key value
- INPUT; CHAR(256)
The key value (left justified) when using a keyed data queue or user queue.
- Qualified queue name
- INPUT; CHAR(20)
The name and library of the data queue or user queue where the enable-complete, disable-complete, permanent-link-failure, and incoming-data entries for this link will be sent. See Queue Entries for more information about these queue entries. The first 10 characters specify the name of an existing queue and the second 10 characters specify the library in which the queue is located. Both entries are left-justified. The special values of *LIBL and *CURLIB can be used for the library name.
- Line description
- INPUT; CHAR(10)
The name of the line description that describes the communications line the link being enabled will use. An existing token-ring, Ethernet, wireless, FDDI, or X.25 line description must be used.
- Communications handle
- INPUT; CHAR(10)
The name assigned to the link being enabled. Any name complying with system object naming conventions may be used.
Optional Parameter Group
- Queue type
- INPUT; CHAR(1)
The type of queue you specified for the Queue name parameter.
D Data queue U User queue
- Network interface description
- INPUT; CHAR(10)
The name of the network interface description. This value is specified if you are running X.25 and need to specify a particular network interface to use. Otherwise, this value should be set to blanks.
Note: This parameter along with the line description parameter causes only the network interface description specified to be varied on. If this value is not specified and the line description parameter contains a switched network interface list, all network interface descriptions within the list are varied on when the QOLELINK API is called.
Specifying this parameter causes only the line and the network interface that are passed to be varied on during enable processing.
- Extended operations
- INPUT; CHAR(1)
Indicates whether or not extended operations are supported.
Extended operations affect all connections (UCEPs, PCEPs) on the link. X'B311' and X'B111' are receive extended operations. X'B110' is a send extended operation.
1 Operations supported 0 Operations not supported
Return and Reason Codes
Return and Reason Codes for the QOLELINK API
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | Operation successful, link enabling. | Wait to receive the enable-complete entry from the data queue or user queue before doing input/output on this link. |
| 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. Then, report the problem using the ANZPRB command. |
| 82/1000 | User data size not valid for X.25 link. | Correct the X.25 user data size parameter. Then, try the request again. |
| 82/1001 | Key length not valid. | Correct the key length parameter. Then, try the request again. |
| 82/1002 | Queue name not valid. | Correct the queue name parameter. Then, try the request again. |
| 82/1003 | Communications handle not valid. | Correct the communications handle parameter. Then, try the request again. |
| 82/1012 | Queue type not valid. | Queue type must be D or U. Correct the queue type and try the request again. |
| 82/1013 | Extended operations value not valid. | Extended operations value must be 1 or 0. Correct the extended operations value and try the request again. |
| 82/1020 | Group parameters not valid (not all the parameters within a group were passed). | Pass all parameters within the group and try the operation again. |
| 82/2000 | Line name not valid or protocol is not supported. | The line name specified must be for a line of type Ethernet, wireless, token ring, FDDI, or X.25. Correct the line name and try the request again. |
| 82/2001 | Line description, network controller description, or network device description not in a valid state. | See messages in the job log indicating the affected object and recommended recovery. Do the recovery, and try the request again. |
| 82/2002 | Not authorized to the line description or network controller description. | See messages in the job log indicating the affected object and get authorization to it. Then, try the request again. |
| 82/2003 | Could not allocate the network device description. | Try the request again. If the problem continues, report the problem using the ANZPRB command. |
| 82/2004 | Could not create the network controller description or network device description. | See messages in the job log indicating the affected object and recommended recovery. Do the recovery, and try the request again. |
| 82/2005 | Could not vary on the network interface, line description, network controller description, or network device description. | See messages in the job log indicating the affected object and recommended recovery. Do the recovery, and try the request again. |
| 82/2006 | Line description not found. | Correct the line description parameter. Then, try the request again. |
| 82/2007 | Line description damaged. | Delete and re-create the line description. Then, try the request again. |
| 82/2008 | Unsupported interface. An error occurred that indicated the network interface specified cannot be associated with the line specified. For example, you specified a network interface for a token-ring, Ethernet, or wireless line. | The network interface value is not correct for the line name value. Correct the configuration or your application. |
| 82/2009 | Network interface description not found. | Specify the correct network interface name and try the request again. |
| 82/2010 | Network interface description specified could not be used. | Check the network interface description for possible errors. Correct any errors and try the request again. |
| 82/2400 | An error occurred while creating the input buffer, input buffer descriptor, output buffer, or output buffer descriptor. | See messages in the job log indicating the affected object and recommended recovery. Do the recovery, and try the request again. |
| 82/3000 | Communications handle already assigned to another link that is enabled in this job. | Either disable the link that was assigned this communications handle, or correct the communications handle parameter so it does not specify a communications handle that is already assigned to a link enabled in this job. Then, try the request again. |
| 82/3005 | Line description already in use by another link that is enabled in this job. | Disable the link that is using this line description. Then, 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