This category includes the following APIs:

Serial device APIs control shared serial devices and their associated queues.

For an application to communicate with a device such as a serial printer or a plotter, the application must be able to communicate directly and interactively. The communication must allow commands to be submitted dynamically and protocols to be changed as the application runs. The LAN Server software defines these types of communication devices as serial devices. This definition is not limited to devices attached to hardware serial ports.

The serial device APIs are used with the CHARDEV.H and NETCONS.H header files.

The LAN Server software can pool serial devices of the same type into a serial device queue to which a requesting application makes its connection. A serial device queue can contain one or more serial devices and simultaneously allow multiple applications to connect to one of the available serial devices. Serial device queues can pool serial devices only on a server.

Note: Serial device queues exist only while they are being shared. In contrast, a spooled device queue (such as for a printer) exists from the time it is created (by calling the appropriate Add function) to the time it is removed.

Before an application can communicate with a serial device, the following must occur:

An explicit connection allows the application to refer to the serial device queue with a local device name. An explicit connection does not, however, open a serial device. For more information about redirecting a local device name to a shared resource, see Use Category.

To illustrate how serial devices and queues work on the LAN, consider the following scenario. Assume that there are 4 serial devices connected to the communication ports of a server in the following manner: 旼컴컴컴컴컴컴컴컴컴컫컴컴컴컫컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커쿛ORT � 쿏EVICE �
쳐컴컴컴컴컴컴컴컴컴컵컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑
� COM1, COM2, COM3 � � Printers �
쳐컴컴컴컴컴컴컴컴컴컵컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑
� COM4 � � Special �
읕컴컴컴컴컴컴컴컴컴컨컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸

Once the serial devices are connected to the ports of a server, an application can create a serial device queue by calling the NetShareAdd function and specifying the share type as a serial device queue. In this scenario, assume the NetShareAdd function is called three times, creating the following 3 queues: 旼컴컴컴컴컴컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커
� QUEUE NAME � PRIORITY � DEVICE NAME �
쳐컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑
� SPLQ � 5 � COM4 �
쳐컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑
� PRINTQ � 5 � COM1, COM2, COM3 �
쳐컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑
� VIPPRINT � 1 � COM3 �
읕컴컴컴컴컴컴컴컴컴컴컴컴좔컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸

The COM3 port is allocated for use by 2 different queues, PRINTQ and VIPPRINT. After calling the NetShareAdd function to create a queue, you can set a parameter to assign a priority to the queue by calling NetCharDevQSetInfo. The priority can be from 1 (high) through 9 (low). Generally, the LAN Server software allows requests to serial device queues with a higher priority to access the pool of serial devices before other queues with lower priorities.

At this point, an application can connect to the shared serial device queue and begin communicating with one of the pooled serial devices in the queue.

If more than 1 serial device happens to be available in a serial device queue, the queue returns the first available serial device to the requesting application. If no devices currently are available, the queue puts the request on a waiting list until a serial device becomes available. The queue waits only as long as the charwait parameter of a requester specifies. If the thread undergoes a timeout while waiting for a serial device to become available, the DosOpen function returns the ERROR_BAD_NET_RESP error code.

An application can check (1) a particular serial device to see if it is working by calling the NetCharDevGetInfo function, or (2) all devices by calling the NetCharDevEnum function. An application also can check to see if the queue is busy or where the request of the application is on the queue waiting list by calling the NetCharDevQGetInfo function. To check all queues, call the NetCharDevQEnum function.

Applications can call the NetCharDevQPurgeSelf function to eliminate all requests submitted to a particular serial device queue from the requester of that application. To remove all requests submitted by all applications from the queue, call NetCharDevQPurge. A process that currently has a device open is unaffected.

When the application no longer needs the device, it should call the DosClose function to return control of the serial device to the serial device queue, allowing another application to use it. If the application cannot call the DosClose function successfully to close the serial device queue, the application can call the NetCharDevControl function to force the serial device queue closed.

When an application successfully opens a remote serial device, the values of the chartime and charcount components from the wksta_info data structure control how information flows across the network to other pertinent requesters and servers. Any application changing these values on the requester where the open was performed should note the following:

[Back] [Next]