PassThruSelect v5.0

Select channels for message monitoring

Last updated: January 13, 2026

Description

The function allows the application to select channels for monitoring the availability of messages (including indications). The application may specify any combination of physical and logical communication channels, the minimum number of channels with available messages, and a timeout.

The function does not return control until one of the following occurs:

The Timeout expires
The number of channels in ChannelList with available messages reaches or exceeds ChannelThreshold
An error occurs

long PassThruSelect(
    SCHANNELSET *ChannelSetPtr,
    unsigned long SelectType,
    unsigned long Timeout
)

Purpose: PassThruSelect allows the application to check for and wait on message availability across multiple channels without constantly calling PassThruReadMsgs. This minimizes data exchange between the application and the device, improving performance.

Important: PassThruSelect does NOT return the messages themselves — only information about which channels have available messages. To retrieve the messages, PassThruReadMsgs must be called.

Parameters

ChannelSetPtr

Input parameter. A pointer to an application-allocated SCHANNELSET structure.

SelectType

Input parameter. Specifies the purpose of the channel selection. The only valid value is:

Value	Description
`READABLE_TYPE`	Monitor channels for available messages (incoming messages or indications)

Timeout

Input parameter. Minimum time (in milliseconds) to wait for the required number of messages to become available.

Range: 0 — 30000 ms
Precision: at least 10 ms
Tolerance: from 0 to +50 ms
Value 0: the function returns immediately with the list of channels that have available messages (equivalent to ChannelThreshold = 0)

SCHANNELSET structure

typedef struct {
    unsigned long ChannelCount;      // Number of channels in the list
    unsigned long ChannelThreshold;  // Minimum number of channels with messages
    unsigned long *ChannelList;      // Pointer to the array of channel IDs
} SCHANNELSET;

Structure fields

Field	In/Out	Description
`ChannelCount`	In/Out	On call: the number of channels in `ChannelList`. On return: the number of channels remaining in `ChannelList` (with available messages).
`ChannelThreshold`	In	The minimum number of channels that must have at least one available message. A value of 0 causes the function to return immediately (equivalent to `Timeout = 0`). Must be ≤ `ChannelCount`.
`ChannelList`	In/Out	On call: a pointer to an array of channel IDs (physical and/or logical) to monitor. On return: a subset of the original list — only channels with available messages (order is not guaranteed).

Return error codes

Code	Description
STATUS_NOERROR	Function completed successfully. `ChannelList` contains the channels with available messages.
ERR_CONCURRENT_API_CALL	A J2534 API function was called before the previous call completed
ERR_DEVICE_NOT_OPEN	`PassThruOpen()` has not been successfully called
ERR_NULL_PARAMETER	`ChannelSetPtr` or `ChannelList` is NULL
ERR_INVALID_CHANNEL_ID	One of the channel IDs in `ChannelList` is invalid. The `SCHANNELSET` structure is not modified.
ERR_DEVICE_NOT_CONNECTED	Communication error with the pass-thru device. The device has been disconnected.
ERR_NOT_SUPPORTED	The DLL does not support this function
ERR_SELECT_TYPE_NOT_SUPPORTED	The `SelectType` value is invalid or unknown
ERR_EXCEEDED_LIMIT	The `ChannelThreshold` value is greater than `ChannelCount`
ERR_BUFFER_EMPTY	No messages are available on any of the specified channels
ERR_TIMEOUT	The timeout expired and the number of channels with messages is less than `ChannelThreshold`. Applies only when `Timeout` is non-zero and at least one message is present.
ERR_FAILED	Undefined error. Use `PassThruGetLastError()` to get a description.

Examples

C/C++ example

#include "j2534_dll.hpp"

// Channel IDs obtained from PassThruConnect/PassThruLogicalConnect
unsigned long canChannelID = ...;
unsigned long isoChannelID = ...;

// Array of channels to monitor
unsigned long channels[2] = { canChannelID, isoChannelID };

// Structure for PassThruSelect
SCHANNELSET channelSet;
channelSet.ChannelCount = 2;
channelSet.ChannelThreshold = 1;  // Wait for at least 1 channel with a message
channelSet.ChannelList = channels;

// Wait for messages for up to 1000 ms
long ret = PassThruSelect(&channelSet, READABLE_TYPE, 1000);

if (ret == STATUS_NOERROR) {
    printf("Channels with messages: %lu\n", channelSet.ChannelCount);

    // Read messages from channels that have data
    for (unsigned long i = 0; i < channelSet.ChannelCount; i++) {
        unsigned long channelID = channelSet.ChannelList[i];
        printf("Channel %lu has messages\n", channelID);

        // Read the messages
        PASSTHRU_MSG msg[10];
        unsigned long numMsgs = 10;
        ret = PassThruReadMsgs(channelID, msg, &numMsgs, 0);
        // ...process the messages...
    }
} else if (ret == ERR_BUFFER_EMPTY) {
    printf("No messages available\n");
} else if (ret == ERR_TIMEOUT) {
    printf("Timeout, but %lu channels have messages\n", channelSet.ChannelCount);
} else {
    char error[256];
    PassThruGetLastError(error);
    printf("Error: %s\n", error);
}

Python example (ctypes)

from ctypes import *

j2534 = cdll.LoadLibrary("libj2534_v05_00.dylib")

# SCHANNELSET structure
class SCHANNELSET(Structure):
    _fields_ = [
        ("ChannelCount", c_ulong),
        ("ChannelThreshold", c_ulong),
        ("ChannelList", POINTER(c_ulong))
    ]

# Channel IDs
can_channel_id = c_ulong(...)  # from PassThruConnect
iso_channel_id = c_ulong(...)  # from PassThruLogicalConnect

# Array of channels
channels = (c_ulong * 2)(can_channel_id.value, iso_channel_id.value)

# Structure for PassThruSelect
channel_set = SCHANNELSET()
channel_set.ChannelCount = 2
channel_set.ChannelThreshold = 1
channel_set.ChannelList = channels

READABLE_TYPE = 0x01

# Wait for messages for up to 1000 ms
ret = j2534.PassThruSelect(byref(channel_set), READABLE_TYPE, 1000)

if ret == 0:  # STATUS_NOERROR
    print(f"Channels with messages: {channel_set.ChannelCount}")
    for i in range(channel_set.ChannelCount):
        print(f"Channel {channel_set.ChannelList[i]} has messages")
elif ret == 0x10:  # ERR_BUFFER_EMPTY
    print("No messages available")
elif ret == 0x09:  # ERR_TIMEOUT
    print(f"Timeout, channels with messages: {channel_set.ChannelCount}")
else:
    error = create_string_buffer(256)
    j2534.PassThruGetLastError(error)
    print(f"Error: {error.value.decode()}")

Related functions

PassThruReadMsgs() - Read messages from a channel
PassThruConnect() - Create a physical connection
PassThruLogicalConnect() - Create a logical channel