SET CHANNEL

version 3

SET CHANNEL (port | operation{; settings | document})

The SET CHANNEL command opens a serial port or a document. You can open only one serial port or one document at a time with this command. To close an opened serial port, pass SET CHANNEL (11).

Historical Note: This command was originally the first 4D command used for working with serial ports and documents on disks. Since that time, new commands have been added. Today, you will typically work with documents on disk using the commands Open document, Create document and Append document. With these commands, you can read and write characters to and from documents using SEND PACKET or RECEIVE PACKET (these commands work with SET CHANNEL, too). However, if you want to use the commands SEND VARIABLE, RECEIVE VARIABLE, SEND RECORD and RECEIVE RECORD, you must use SET CHANNEL to access the document on disk.

The description of SET CHANNEL is composed of two sections:

• Working with Serial Ports

• Working with Documents

The first form of the SET CHANNEL command opens a serial port, setting the protocol and other port information. Data can be sent with SEND PACKET, SEND RECORD or SEND VARIABLE, and received with RECEIVE BUFFER, RECEIVE PACKET, RECEIVE RECORD or RECEIVE VARIABLE.

The first parameter, port, selects the port and the protocol.

You can address up to 99 serial ports (one at a time). The following table lists the values for port:

Important: The value you pass in port must refer to an existing serial COM port recognized by the operating system. For example, in order to be able to use the values 101, 103 and 125, the serial ports COM1, COM3 and COM25 must have been set up correctly.

In a standard configuration Mac OS and Windows support two serial ports: on Mac OS, the modem port and the printer port; on Windows, the COM1 and COM2 ports. However, additional serial ports can be added by the use of extension boards. Originally, 4th Dimension only adressed two standard serial ports and it was only later that the support of additional ports was implemented. For compatibility reasons, both addressing systems were kept.

- If you want to address a standard serial port (printer/COM2 or modem/COM1), you can either pass in the port parameter one of the following values 0, 1, 20, 21, 30 and 31 (that corresponds to the old addressing method), or a value greater than 100 (please see the following explanation).

- If you want to address additional serial ports, you need to pass the value N+100 (where N is the value of the port to address). You may also consider adding 100 or 200 to the value mentioned above (N+100), if you want to select respectively a software or a hardware protocol.

1. If you want to use the printer/COM2 port with no protocol, you can use one of the following syntaxes:

   SET CHANNEL (0;param)

or

   SET CHANNEL (102;param)

2. If you want to use the modem/COM1 port with the XON/XOFF protocol, you can use one of the following syntaxes:

   SET CHANNEL (21;param)

or

   SET CHANNEL (201;param)

3. If you want to use the COM 25 port with the RTS/CTS protocol, you need to use the following syntax:

   SET CHANNEL (325;param)

The settings parameter sets the speed, number of data bits, number of stop bits, and parity. You determine the value for settings by adding the speed, data bits, stop bits, and parity values as listed in the following table. For example, to set 1200 baud, 8 data bits, 1 stop bit, and no parity, you would add 94 + 3072 + 16384 + 0 = 19550. You would then use 19550 as the value of the setup parameter.

Tip: The various numeric values to be accumulated and passed in port and settings (but not including the values for COM1...COM99) are available as predefined constants in the theme Communications within the Design environment Explorer windows. For COM1...COM99, use numeric literals.

The second form of the SET CHANNEL command allows you to create, open, and close a document. Unlike the System documents commands, it can open only one document at a time. The document can be read from or written to.

The operation parameter specifies the operation to be performed on the document specified by document. The following table lists the values of operation and the resulting operation with different values for document. The first column lists the allowed values for operation. The second column lists the allowed values for document. The third column lists the resulting operation.

For example, to display an Open File dialog box to open a text file, you would use the following line:

   SET CHANNEL (13; "")

All of the operations in this table set the Document system variable if appropriate. They also set the OK system variable to 1 if the operation was successful. Otherwise, the OK system variable is set to 0.

See examples for the commands RECEIVE BUFFER, SET TIMEOUT and RECEIVE RECORD.

Append document, Create document, GET SERIAL PORT MAPPING, Open document, RECEIVE BUFFER, RECEIVE PACKET, RECEIVE RECORD, RECEIVE VARIABLE, SEND PACKET, SEND RECORD, SEND VARIABLE, SET TIMEOUT.