A-Shell Development History

COMIO.SBR enhancement: new opcode (0) to query COM devices, intended to make it easier for applications using COMIO to automatically determine the COM port associated with the device of interest. This will be helpful because in the world of USB-to-COM port interfaces, it is common for the COM port number to be assigned automatically when a device is plugged in, making it otherwise difficult to write code that can adapt dynamically.

xcall COMIO, COMOP_QUERY, propid, comary(1), status, count

COMOP_QUERY [in]

Opcode, defined as 0 (in COMIO.DEF)

propid (num) [in]

Identifies the property to retrieve in the COMARY, using the symbols defined below (from COMIO.DEF). Note that these should match up with the properties available on the Device Manager Properties dialog Details panel. The idea is to give you the ability to select an additional property (besides the device description property, which is always returned) to help you identify the device of interest. Note that the property id symbols are standard Windows symbols, so if you can't identify them from the symbol name, or by matching it up to properties listed in the Device Manager dialog, then you can probably locate more information via an Internet search.

 

comary (ST_COMARY) [out]

Array of structures to return details about the available devices. ST_COMARY is defined in COMIO.DEF as:

 

defstruct ST_COMARY         ! structure used in COMOP_QUERY

map2 port,s,20          ! e.g. "COM4"

   map2 descr,s,128        ! e.g. "Prolific USB-to-Serial Port"

   map2 property,s,128     ! selected additional property to retrieve endstruct

 

The actual array instance can be mapped as:

map1 comary(5),ST_COMARY

 

or

 

dimx comary(n),ST_COMARY

 

The size of the array should be sufficient to capture all of the expected COM devices; see count parameter.

Note that you must pass the first element of the array, i.e. comary(1), not comary.

Depending on the propid, the associated property may be a text string, an array of text strings, or a numeric value. In the case of the array, the elements will be separated with a "|". For the numeric properties, the returned format will be a hex value preceded by "&h". You can convert that to a decimal number using the VAL() function; you'll have to search the Internet for details on the meaning of the numeric property values. If the request for the property returns an error, the property string will contain "Error: #", where # will be a Windows System Error code.

status (signed num) [out]

Returns status codes, as in other COMIO opcodes

count (num) [in/out]

On input, must specify the number of elements of the comary array (to prevent overwriting memory if there are actually more COM devices than will fit in the array). On return, it will contain the number of COM devices actually copied to the array.

The COMIO.BP program in [908,54] of the SOSLIB has been updated to demonstrate the new feature.

ASHINC:COMIO.DEF has been added and contains the opcode symbols (COMOP_xxx), the structures, the property ID symbols, etc.