LINEIN -- Read one or more characters from COM port

Syntax:	LINEIN	[ variable ] [ /options ]
Arguments:	[ variable ]	A variable to store characters read from the port; if the variable does not previously exist, it is created.
Options:	/allowall	Do not strip unprintable characters; these characters are replaced with the configured LINEIN fill character.
	/flush	Flush the receive buffer before starting read.
	/length=xx	Maximum number of characters to receive; if not specified the maximum of 1020 characters is used; if 0, and either a terminating character or terminating sequence is specified, then LINEIN accepts an unlimited number of characters until the termination condition is matched; all of the characters except the terminating sequence itself are discarded.
	/termchr=lf	Terminate LINEIN when a line-feed is received; this changes the default of a carriage-return terminating character.
	/termchr=none	Do not use either a line-feed or carriage-return as a terminating character.
	/termseq="xxx"	Terminate LINEIN when the specified termination sequence is received.
	/timeout=nn	Time-out in seconds to wait for a character to be received; the default time-out is 30 seconds.

This script command receives characters from an open COM port and saves the characters in a string variable. The various options control how many characters are received.

This command is generally used to accept printable characters from the COM port. By default FileLink removes any unprintable characters before they are saved in the specified variable. If the loss of unprintable character alters the resulting string in an undesirable way by altering character position, for example, you may use the /allowall option. When this option is used, the relative character position of the string is preserved by replacing the unprintable characters with the configured LINEIN fill character. The fill character defaults to a space.

By default, LINEIN terminates when a carriage-return character is received. You may alter this behavior by using either the /termchr=lf or /termchr=none options. LINEIN also terminates if the maximum number of characters has been received, when a user-defined string pattern is detected, or a time-out expires.

If /termchr=none is specified and /termseq is not, LINEIN terminates after a fixed number of characters has been received - either the number specified by the /length option or the default value of 1020 characters.

The following is a more specific example showing how the LINEIN command may be used to scan incoming characters for a specific prompt. For the sake of this example, let’s assume that the remote system sends the following banner and user name prompt immediately after a connection is established.

One way to handle this character sequence would be to use four LINEIN statements in the FileLink script file. This is fine when you can be certain that the prompt is always to be found in the fourth line. However, using a single LINEIN command, as shown below, is simpler and more dependable since it is not dependent on knowing how many lines there will be before the prompt appears.

If you are unsure of the number of characters that may be received before the prompt, or if this number may be greater than 1020, add the /length=0 option to the command. This results in FileLink discarding all the received characters except for the terminating sequence. It is strongly recommended that you use the /timeout option in this case to prevent the LINEIN command from hanging in any case where the terminating sequence is not received.