tcl.poke Verb: Access/TCL


Command tcl.poke Verb: Access/TCL
Applicable release versions: AP 5.2.3
Category TCL (746)
Description sends either a string of characters or one or more TCL commands to the input buffer of another port.

The "port.number" designates the target port number.

The "text" may contain any characters, except segment marks (x'ff') and may be unlimited in length. The text may optionally be preceded by a space. When the text is omitted, a <return> is sent to the target port. The "text" string may optionally be enclosed in single quotes ('), double quotes (") or backslashes ().

One or more TCL commands may be sent directly to the target port. Each TCL command must be followed by an <escape>, which is treated as a <return> on the receiving port.

An item containing one or more valid TCL commands may also be transmitted directly from a file. The transmitted item must contain one valid TCL command on each attribute. This feature is accomplished by simply poking an <escape> to the target port. The process prompts for the filename and item-id of the item to transmit and execute.

The "poke" command displays the number of characters it has successfully poked to the target port's input buffer. The number reported may be not match the actual number of characters sent due to the condition of the target port's input buffer.

Since the <escape> key is used by "poke" to terminate commands, a special provision applies for transmitting an actual <escape>. This is accomplished by pressing <escape> twice. A set of two <escape>'s is treated (and poked) as one <escape>.
Syntax poke port.number{,{ text}}
poke port.number{ }<escape> {file.reference {item-id}}
poke port.number<escape>
poke port.number TCL.command<escape> {TCL.command{<escape>}...}
poke 16
[1028] 1 characters poked.
Sends a <return> to port 16.

poke 16,
[1028] 1 characters poked.
This also sends a <return> to port 16.

poke 16,answer the phone!
[1028] 17 characters poked.
Sends the string, "answer the phone!" to port 16, without following 
the (poked) string with a <return>.

poke 16,"answer the phone!"
[1028] 17 characters poked.
This is exactly the same as the previous example. Quotes (single or double) and 
backslashes have no effect on the string being sent, unless the string happens 
to begin with, but not be followed by, a literal quote. See the next example.

poke 16 "hi
[2] Uneven number of delimiters (' " ).
This fails because the string is preceded by a quote. The next example shows 
that a trailing quote is accepted.

poke 16 hi"
[1028] 3 characters poked.

poke 16,don't panic!
[1028] 12 characters poked.
Embedded quotes are allowed.

In all of the previous examples, no <return> was sent at the end of the 
"poked" strings.

poke 16 who[
In this form of a "poke", the string being sent is an actual TCL 
command. The "[" character is the character echoed by the 
<escape> key. This pokes a "who" to port 16 and issues a 
<return> to process the command.

poke 16 who[time[ovf
This pokes the "who", "time" and "ovf" commands 
to port 16 and executes them.

poke 16[<return>
poke from file-name item-name:md script1
This form uses the port number, followed by an <escape>, then a 
<return>. The process then prompts for the filename and item-id of the 
item to transmit. Each attribute of the specified item, starting at the first 
attribute, is treated as a valid TCL command. For example, "script1" 
could look like this:

   id:   script1
att 1:   who
att 2:   time
att 3:   ovf

poke 16[md<return>
poke from item-name:script1
This is the same as example 10, but the filename is supplied on the command 
line. The process only prompts for the item-id of the item to transmit.

poke 16[md script1<return>
[1028] 13 characters poked.
This is the same as example 11, but the filename and item-id are specified on 
the command line.

poke 16[
poke from file-name item-name:[
0001  :who<return>
0002  :time<return>
0003  :ovf<return>
0004  <return>
[1028] 13 characters poked.
In this form, an item is constructed on-the-fly, then poked into the target 
port's input buffer. This example executes the "who", 
"time" and "ovf" commands on port 16.

poke 16 [[
[1028] 1 characters poked.
Poking two <escape>'s results in one <escape> being sent.

execute "poke 16 " : char(24):char(5):"y"
This illustrates using "execute" to "poke" characters to 
another port. This instruction pokes a <ctrl>+x, followed by 
<ctrl>+e, followed by a literal "y". This would explicitly exit 
the receiving port from the current item in the Update processor.
Related tcl.tcl