Set Filter (QOLSETF) API
| 1 | Return code | Output | Binary(4) |
| 2 | Reason code | Output | Binary(4) |
| 3 | Error offset | Output | Binary(4) |
| 4 | Communications handle | Input | Char(10) |
Threadsafe: No
The Set Filter (QOLSETF) API activates and/or deactivates one or more filters for a link that is currently enabled in the job in which the application program is running. The application program must provide the required filter information in the output buffer that was created when the link was enabled. The output buffer descriptor is not used. See Format of Filter Information for details on the format of the filter information in the output buffer.
Filters contain inbound routing information that user-defined communications support uses to route incoming data to a link that is enabled by an application program. The incoming data that is routed depends on the type of communications line the link is using. On an X.25 communications line, the incoming data is an incoming switched virtual circuit (SVC) call. On a token-ring, Ethernet, wireless, or FDDI communications line, the incoming data is the actual data frame.
The type of filters activated for a link determine the way incoming data is routed to that link.
Note: All active filters for a link must be of the same type.
For links using a token-ring, Ethernet, wireless, or FDDI communications line, there are three types of filters. The following list of filters is from most to least restrictive:
- Destination service access point (DSAP), source service access point (SSAP), frame type, optional sending adapter address, and protocol (or group) ID.
- Destination service access point (DSAP), source service access point (SSAP), optional frame type, and sending adapter address
- DSAP, SSAP, and optional frame type
- DSAP
For links using an X.25 communications line, there are two types of filters. The following list of filters is from most to least restrictive:
- Protocol identifier (PID) and calling data terminal equipment (DTE) address
The system treats the first byte of call-user data in an X.25 call request packet as the PID.
- PID
The order for checking filters when multiple links are using the same communications line, is from most to least restrictive. For example, suppose two user-defined communications application programs (application program A and B) in different jobs each have a link enabled that use the same token-ring communications line. Further suppose that application program A has activated a filter on DSAP X'22' and application program B has activated a filter on DSAP X'22' and SSAP X'22'. If a data frame comes in with a DSAP of X'22' and an SSAP of X'22', application program B will receive the frame. If a data frame comes in with a DSAP of X'22' and an SSAP not equal to X'22', application program A will receive the frame.
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.
- Error offset
- OUTPUT; BINARY(4)
The offset from the top of the output buffer to the incorrect filter header data or to the incorrect filter in the filter list.
The content of this parameter is only valid for 83/1999 and 83/3003 return/reason codes.
- Communications handle
- INPUT; CHAR(10)
The name of the link on which to perform the filter operation.
Format of Filter Information
The application must provide all filter information in the output buffer that was created when the link was enabled. The application should treat the output buffer as one large space with the size equal to the number of data units created for the output buffer multiplied by the size of each data unit. This information is returned by the QOLELINK API when the link was enabled.
The filter information in the output buffer is made up of two parts. The first portion starts at offset 0 from the top of the output buffer and contains filter header data. The second portion of the filter information starts immediately after the filter header data in the output buffer and contains the filters that make up the filter list.
Filter Header Data
| Field | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Function | CHAR(1) | The filter function to perform. The valid values are as follows:
|
||||||||||||
| Filter type | CHAR(1) | The type of the filters in the filter list. All filters in the filter list must be of this type. In addition, this must be the same type as the filters currently active for this link, if any. The valid values are as follows:
Note: The filter type field must be set even if there are no filters in the filter list. |
||||||||||||
| Number of filters | BINARY(2) | The number of filters in the filter list. Any value between 0 and 256 may be used.
Note: The maximum number of filters that can be specified in the filter list is also limited by the total size of the output buffer which may accommodate less than 256 filters. |
||||||||||||
| Filter length | BINARY(2) | The length of each filter in the filter list. This value must be 16 for filter types X'00' and X'01', and 14 for filter types X'02', X'03', and X'04', and 25 for filter type X'08'.
Note: The filter length field must be set even if there are no filters in the filter list. |
The format of each filter in the previous list of filters is described in the following table. All filters in the list of filters must be contiguous with each other and be of the type specified in the filter type field in the filter header data.
X.25 Filters (Filter Types X'00' and X'01')
| Field | Type | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| PID length | CHAR(1) | The length of the PID on which to route incoming calls. The valid values are as follows:
|
||||||||||||||||
| PID | CHAR(1) | The PID on which to route incoming calls. This should be set to X'00' when the PID length field is set to X'00'. Otherwise, any value may be used.
Note: Care should be taken when setting the PID field to an SNA PID (X'C3', X'C6', X'CB', X'CE'), asynchronous PID (X'01', X'C0'), or TCP/IP PID (X'CC'). See the X.25 Network Support |
||||||||||||||||
| Calling DTE address length | CHAR(1) | Specifies, in hexadecimal, the number of binary coded decimal (BCD) digits in the calling DTE address on which to route incoming calls. The valid values are as follows:
|
||||||||||||||||
| Calling DTE address | CHAR(12) | Specifies, in binary coded decimal (BCD), the calling DTE address on which to route incoming calls. This should be set to BCD zeros when the calling DTE address length field is set to X'00'. Otherwise, any valid DTE address left-justified and padded on the right with BCD zeros may be used. | ||||||||||||||||
| Additional routing data | CHAR(1) | Specifies additional data on which to route incoming calls. This field is applicable for all X.25 filter types and is bit-sensitive with bit 0 (leftmost bit) defined for reverse charging options and bit 1 defined for fast select options. The remaining bits are undefined and should be set off ('0'B).
The valid values for bit 0 are as follows:
The valid values for bit 1 are as follows:
For example, consider the following values for the additional routing data field:
|
manual for more information.LAN Filters (Filter Types X'02', X'03', and X'04')
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
| DSAP address length | CHAR(1) | The length of the DSAP address on which to route incoming frames. This must be set to X'01'. | ||||
| DSAP address | CHAR(1) | The DSAP address on which to route incoming frames. The DSAP address is the service access point on which the incoming frame arrived. Any service access point configured in the token-ring, Ethernet, wireless, or FDDI line description as *NONSNA may be used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. Therefore, to receive Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL. |
||||
| SSAP address length | CHAR(1) | The length of the SSAP address on which to route incoming frames. The valid values are as follows:
|
||||
| SSAP address | CHAR(1) | The SSAP address on which to route incoming frames. The SSAP address is the service access point on which the incoming frame was sent. The valid values are as follows:
|
||||
| Frame type length | CHAR(1) | The length of the frame type on which to route incoming frames. The valid values are as follows:
|
||||
| Frame type | CHAR(2) | The frame type on which to route incoming frames. The frame type is defined in an Ethernet Version 2 frame to indicate the upper layer protocol being used. This must be set to X'0000' when the frame type length field is set to X'00'. Otherwise, any value except X'80D5' (encapsulated LLC) may be used, but should be in the range of X'05DD'-X'FFFF'. | ||||
| Sending adapter address length | CHAR(1) | Specifies, in hexadecimal, the length of the sending adapter address on which to route incoming frames. The valid values are as follows:
|
||||
| Sending adapter address | CHAR(6) | Specifies, in packed form, the sending adapter address on which to route incoming frames. This must be set to X'000000000000' when the sending adapter address length field is set to X'00'. Otherwise, any valid adapter address may be used. |
LAN Filters (Filter Type X'08')
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
| DSAP address length | CHAR(1) | The length of the DSAP address on which to route incoming frames. This must be set to X'01'. | ||||
| DSAP address | CHAR(1) | The DSAP address on which to route incoming frames. The DSAP address is the service access point on which the incoming frame arrived. Any service access point configured in the token-ring, Ethernet, wireless, or FDDI line description as *NONSNA may be used.
Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. Therefore, to receive Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL. |
||||
| SSAP address length | CHAR(1) | The length of the SSAP address on which to route incoming frames. The valid values are as follows:
|
||||
| SSAP address | CHAR(1) | The SSAP address on which to route incoming frames. The SSAP address is the service access point on which the incoming frame was sent. The valid values are as follows:
|
||||
| Frame type length | CHAR(1) | The length of the frame type on which to route incoming frames. The valid values are as follows:
|
||||
| Frame type | CHAR(2) | The frame type on which to route incoming frames. The frame type is defined in an Ethernet Version 2 frame to indicate the upper layer protocol being used. This must be set to X'0000' when the frame type length field is set to X'00'. Otherwise, any value except X'80D5' (encapsulated LLC) may be used, but should be in the range of X'05DD'-X'FFFF'. | ||||
| Sending adapter address length | CHAR(1) | In hexadecimal, the length of the sending adapter address on which to route incoming frames. The valid values are as follows:
|
||||
| Sending adapter address | CHAR(6) | In packed form, the sending adapter address on which to route incoming frames. This must be set to X'000000000000' when the sending adapter address length field is set to X'00'. Otherwise, any valid adapter address may be used. | ||||
| Protocol ID length | CHAR(1) | In hexadecimal, the length of the protocol ID on which to route incoming frames. This must be set to X'03'. | ||||
| Protocol ID | CHAR(3) | In hexadecimal, the protocol ID (or organization ID) to route incoming frames. | ||||
| Reserved field | CHAR(7) | This field must be initialized to hexadecimal zeros, X'00000000000000'. |
General Rules for Using Filters
The following is a list of rules for activating and deactivating filters:
- All active filters for a link must be of the same type
- A link can have a maximum of 256 active filters
- The maximum number of filters that can be specified in the filter list can be no more than 256, and may be less, depending on the size of the output buffer
- A request to activate a filter for a link that already has the same filter active will be successful, but the filter will only be activated once
- A request to deactivate a filter for a link that has no such filter active will be successful
- If the return and reason code from the QOLSETF API is not 0/0, none of the specified filters were activated or deactivated
- Once a filter is activated, it will remain active until one of the following occurs:
- It is deactivated by explicitly calling the QOLSETF API
- The link that the filter was active for is disabled
- It is deactivated by explicitly calling the QOLSETF API
Return and Reason Codes
| Return/Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | Operation successful. | Continue processing. |
| 80/2200 | Queue error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Then correct the error, enable the link, and try the request again. |
| 80/2401 | Output buffer error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Then correct the error, enable the link, and try the request again. |
| 80/3002 | A previous error occurred on this link that was reported to the application program by escape message CPF91F0 or CPF91F1. However, the application program has attempted another operation. | Ensure the link is disabled and see messages in the job log for further information. If escape message CPF91F0 was sent to the application program, then report the problem using the ANZPRB command. Otherwise, correct the error, enable the link, and try the request again. |
| 80/4000 | Error recovery has been canceled for this link. | Ensure the link is disabled and see messages in the job log for further information. Then correct the condition, enable the link, and try the request again. |
| 80/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. |
| 83/1998 | The size of the output buffer is not large enough for the specified number of filters. | Reduce the number of filters in the filter list so that the size of the filter list plus the size of the filter header data is less than or equal to the size of the output buffer. Try the request again. |
| 83/1999 | Incorrect filter header data or incorrect filter in the filter list. If the filter header data is incorrect, the error offset parameter will point to the field in error. If a filter in the filter list is incorrect, the error offset parameter will point to the beginning of the incorrect filter. | Correct the incorrect filter header data or the incorrect filter in the filter list. Try the request again. |
| 83/3001 | Link not enabled. | Correct the communications handle parameter. Try the request again. |
| 83/3003 | One of the following is true of a filter in the filter list. The error offset parameter will point to the beginning of the offending filter.
|
Do one of the following, and try the request again:
|
| 83/3004 | Link is enabling. | Wait for the enable-complete entry to be sent to the data queue or user queue. If the link was successfully enabled, try the request again. |
| 83/3200 | All resources are currently in use by asynchronous operations that have not yet completed.
Note: This return and reason code is only possible for links using an X.25 communications line. See Send Data (QOLSEND) API for more information. |
Wait for at least one of the asynchronous operations to complete. Notification of completion of these operations will be received from the QOLRECV API. Try the request again. |
| 83/4001 | Link failure, system starting error recovery for this link. | Wait for the link to recover. Try the request again. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C90 E | Literal value cannot be changed. |
| CPF91F0 E | Internal system error. |
| CPF91F1 E | User-defined communications application error. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1