gcom.1

   1 .\" Paul Hardwick
   2 .\" paul@peck.org.uk
   3 .TH gcom 1 "04 January, 2006"
   4 .LO 1
   5 .SH NAME
   6 gcom  \- Option GlobeTrotter GPRS/EDGE/3G/HSDPA  and Vodafone 3G/GPRS datacard control tool
   7 .SH SYNOPSIS
   8 .B gcom
   9 .RB \-d
  10 .I "device"
  11 .RB -ehstvx
  12 .I "script"
  13 .SH OPTIONS
  14 .in +5
  15 .B \-d
  16 .I device
  17 .in +10
  18 set the device to be used to communicate with the data-card.
  19 Defaults to
  20 .I /dev/modem
  21 .PP
  22 .in +5
  23 .B \-e
  24 .in +10
  25 turn on serial communications echo.
  26 .PP
  27 .in +5
  28 .B \-h
  29 .in +10
  30 display summary help and exit.
  31 .PP
  32 .in +5
  33 .B \-s
  34 .in +10
  35 don\'t run the internal
  36 .I default
  37 script before an external script.
  38 .PP
  39 .in +5
  40 .B \-t
  41 .in +10
  42 change to an alternate line terminator (default "\n").
  43 .PP
  44 .in +5
  45 .B \-v
  46 .in +10
  47 run in verbose mode. This traces scripts as they are executed.
  48 It is intended to help in debugging scripts.
  49 .PP
  50 .in +5
  51 .B \-x
  52 .in +10
  53 for internal and external scripts, any reference to 115200 baud is converted to 57600.
  54 This is useful for data cards that don't like 115200 baud such as the GlobeTrotter EDGE.
  55 .PP
  56 .in -10
  57 .SH DESCRIPTION
  58 .B gcom
  59 is a scripting language interpreter useful for establishing
  60 communications on serial lines and through PCMCIA modems
  61 as well as GPRS and 3G datacards.
  62 .PP
  63 .B gcom
  64 has some features that are rarely found in other utilities of the same type.
  65 .in 5
  66 .SS Features
  67 .nf
  68 - Pre-defined built-in scripts for 2G/3G datacard control
  69 - Simple, BASIC-like script language.
  70 - Command-line and file sourcing of script.
  71 - Multi-response waitfor.
  72 - waitquiet permits line stabilization.
  73 - In-line text capture.
  74 - Multi-process support: fork, wait, kill, exit.
  75 - Debugging verbose and log output.
  76 - logging to file.
  77 - Flow control: goto, gosub, return, if, else.
  78 - Low-impact on system resources.
  79 - Time commands and functions.
  80 - String manipulations.
  81 - Environment manipulation: env(), putenv.
  82 - External utilities system calls: system, exec.
  83 .PP
  84 .SS Supported GPRS and 3G datacards
  85 .B gcom
  86 has been tested against GlobeTrotter GPRS,EDGE, Combo EDGE, 3G, 3G EDGE, HSDPA
  87 and GlobeTrotter Fusion as well as Vodafone 3G.
  88 It can set the PIN and display information about datacards before a PPP
  89 connection is started.
  90 Additionally, because the GlobeTrotter and Vodafone 3G/GPRS datacard have
  91 a secondary serial interface, these datacards can be monitored while a PPP
  92 connection is in existence and transferring data.
  93 .PP
  94 .B gcom
  95 is primarily designed to work with the GlobeTrotter range of datacards but
  96 should be compatible with any other GPRS or 3G datacard provided its
  97 interface is implemented as one or more serial or USB serial devices
  98 and it is controlled and queried by an implementation of the Hayes
  99 command interface with the same AT command extensions used by the listed
 100 datacards.
 101 .
 102 .SS Using gcom
 103 .B gcom
 104 has only one function: to run a script. This may be one of a number
 105 of "standard" internal scripts or an external script. Both types of script are
 106 invoked in the same way. The "standard" scripts are built into
 107 .B gcom
 108 and will work for serially connected modems, built-in modems, PCMCIA modems
 109 as well as the GlobeTrotter GPRS and the Vodafone 3G/GPRS datacards.
 110 .PP
 111 .SS Built-in scripts
 112
 113 .in -5
 114 .I gcom
 115 .in +5
 116 This runs the default internal script. Running
 117 .B gcom
 118 without any script specified, e.g.,
 119 .I gcom -d /dev/ttyS1
 120 it will check for a PIN and
 121 prompt you if it is required. The next thing it does is wait for the
 122 device to register, it then reports the signal strength.
 123 If you don\'t specify a port with the
 124 .B -d
 125 option then
 126 .I /dev/modem
 127 is assumed.
 128 If the -s switch is not used then this default script is run before any external script.
 129
 130 .in -5
 131 .I gcom help
 132 .in +5
 133 Lists these and the other options available.
 134 .PP
 135 .in -5
 136 .I gcom info
 137 .in +5
 138 Lists the datacard configuration.
 139
 140 .in -5
 141 .I gcom sig
 142 .in +5
 143 Prints the signal strength.
 144
 145 .in -5
 146 .I gcom reg
 147 .in +5
 148 Prints the registration state.
 149
 150 .in -5
 151 .I gcom 3G
 152 .in +5
 153 Puts a GlobeTrotter 3G/Fusion and Vodafone 3G into 3G network only
 154 mode (UMTS/HSDPA).
 155
 156 .in -5
 157 .I gcom 2G
 158 .in +5
 159 Puts a GlobeTrotter 3G/Fusion and Vodafone 3G into 2G network only
 160 mode (GSM/GPRS/EDGE).
 161
 162 .in -5
 163 .I gcom 3G2G
 164 .in +5
 165 Puts a GlobeTrotter 3G/Fusion and Vodafone 3G into 3G preferred
 166 mode (UMTS/HSDPA and GSM/GPRS/EDGE).
 167
 168 .in -5
 169 .I gcom GTEDGE
 170 .in +5
 171 Use this command to initialise GlobeTrotter EDGE and GlobeTrotter
 172 Combo EDGE cards before doing anything else. (It switches on the radio).
 173
 174 .in -5
 175 .I gcom USA
 176 .in +5
 177 Switch to 900/1900 MHz band for USA operation. GlobeTrotter GPRS datacards only.
 178
 179 .in -5
 180 .I gcom EUROPE
 181 .in +5
 182 Switch to 900/1800 MHz band for European operation. GlobeTrotter GPRS datacards only.
 183
 184 .PP
 185 .SS Custom Scripts
 186
 187 As well as built in scripts you can make your own. The following
 188 script sets a Vodafone 3G datacard or Option Fusion card\'s UMTS mode to GPRS:
 189 .PP
 190 .in +5
 191 #Set GPRS only mode
 192 .br
 193 set com 115200n81
 194 .br
 195 set senddelay 0.05
 196 .br
 197 waitquiet 1 0.2
 198 .br
 199 send "AT_OPSYS=0^m"
 200 .br
 201 print "Setting GPRS only mode"
 202 .PP
 203 If you saved the above script as GPRS you would call it like this:
 204 .PP
 205 .in +5
 206 .I gcom GPRS
 207 .in -5
 208 .PP
 209 If you needed to specify the port as well then do this:
 210 .PP
 211 .in +5
 212 .I gcom -d /dev/ttyS1 GPRS
 213 .in -5
 214 .PP
 215 You can also pass environment parameters to a
 216 .B gcom
 217 script via
 218 .I $env().
 219 .
 220
 221 .SS Replacing chat
 222 .B chat
 223 is a utility that comes with the ppp package (for Linux, anyway) that,
 224 with a set of expect-send string couples, does enough to connect most people
 225 to ISPs and such.  While chat\'s use is very simple, it isn\'t very flexible.
 226 That\'s where
 227 .B gcom
 228 takes over.
 229 .PP
 230 .B gcom
 231 can be used in place of
 232 .B chat
 233 using the same strategy.
 234 For example, a pppd
 235 line reading:
 236 .PP
 237 .in +5
 238 .nf
 239 pppd connect \\
 240      \'chat -v "" ATDT5551212 CONNECT "" ogin: ppp \\
 241      word: whitewater\' \\
 242      /dev/cua1 38400 debug crtscts modem defaultroute
 243 .fi
 244 .in -5
 245 .PP
 246 Would, using
 247 .B gcom,
 248 read:
 249 .PP
 250 .in +5
 251 .nf
 252 pppd connect \'gcom /root/scripts/isp.scr\' /dev/cua1 38400 \\
 253      debug crtscts modem defaultroute
 254 .fi
 255 .in -5
 256 .PP
 257 And the isp.scr script would read:
 258 .PP
 259 .nf
 260      send "ATDT5551212^m"
 261      waitfor 60 "ogin:"
 262      send "ppp^m"
 263      waitfor 60 "word:"
 264      send "whitewater^m"
 265 .fi
 266 .PP
 267 Of course it then becomes trivial to make this script a whole lot more
 268 functional by adding code for busy detect, re-dialing, etc...
 269 .
 270 .SS Verbose output
 271
 272 When the verbose option is turned on,
 273 .B gcom
 274 reports everthing on
 275 the standard error channel.
 276 If turned on from the command line (-v), the output contains 4 sections.
 277 .PP
 278 - Command line argument actions
 279 .in +2
 280 These are actions taken because they were specified from the command
 281 line, such as opening a communication device (-d), etc...
 282 For these to be output, you must specify -v as the first argument.
 283 .in -2
 284 .PP
 285 - List of arguments
 286 .in +2
 287 The number and list of arguments passed. This is useful in case
 288 you have a bunch of environment variables or quotes, back-quotes,
 289 backslashes on the command line and you\'re not sure what the
 290 script really sees.
 291 .in -2
 292 .PP
 293 - Script list
 294 .in +2
 295 A list of the script to execute.  This may be a concatenation of
 296 the default internal script, unless this is suppressed by the -s
 297 option, and a script file.  Every line is listed with its
 298 line number and character position.
 299 .in -2
 300 .PP
 301 - Execution output
 302 .in +2
 303 List of commands as they are executed. The parser prints the
 304 line its currently on, starting from the exact point where its
 305 at to the end of the line. Multiple command groups on a single
 306 line produce multiple output lines. Verbose output may be mixed
 307 with script output (print, eprint or lprint.)
 308 .in -2
 309 .PP
 310 Here\'s an example:
 311 .PP
 312 .in +2
 313 .nf
 314 $ gcom -v -d/dev/cua1 -s blah.scr
 315 gcom 00:18:46 -> Verbose output enabled
 316 gcom 00:18:46 -> Script file: blah.scr
 317 gcom 00:18:46 -> argc:5
 318 gcom 00:18:46 -> argv[0]=gcom
 319 gcom 00:18:46 -> argv[1]=-v
 320 gcom 00:18:46 -> argv[2]=-d/dev/cua1
 321 gcom 00:18:46 -> argv[3]=-s
 322 gcom 00:18:46 -> argv[4]=blah.scr
 323 gcom 00:18:46 ->  ---Script---
 324 .in +3
 325 1@0000 set com 38400n81 let a=2
 326 2@0025 print "9x",a,"=",9*a,"\\n"
 327 3@0051 sleep 5
 328 4@0059 exit 0
 329 .in -3
 330 gcom 00:18:46 ->  ---End of script---
 331 gcom 00:18:46 -> @0000 set com 38400n81 let a=2
 332 gcom 00:18:46 -> @0017 let a=2
 333 gcom 00:18:46 -> @0025 print "9x",a,"=",9*a,"\\n"
 334 9x2=18
 335 gcom 00:18:46 -> @0051 sleep 5
 336 gcom 00:18:51 -> @0059 exit 0
 337 .in -2
 338 .fi
 339 .
 340 .SH Programming manual
 341 .SS Syntax
 342 The syntax used for
 343 .B gcom
 344 scripts is rather simple, somewhat BASIC-like.
 345 A script is a non-tokenized, pure ASCII text file containing lines terminated
 346 by newline characters (Unix standard.)  Scripts can be created and/or modified
 347 using any standard text editor (vi, vim, joe, pico, emacs, ed, microEmacs)
 348 Lines in a
 349 .B gcom
 350 script read like so:
 351 .nf
 352
 353  - Empty line
 354  - [indent]rem remark
 355  - [indent][[:|label] LABEL] [command [arguments]] rem remark
 356  - [indent][[:|label] LABEL] [command [arguments]] [command [arguments]]...
 357 .PP
 358 Characters used for indentation are the space and tabulation characters.
 359 The rem command makes the script parser skip the rest of the line.
 360 The rem command can also be written as "#" or "//".
 361 .PP
 362 Labels consist of lowercase and uppercase letters and digits.
 363 Case is ignored in labels.
 364 .PP
 365 Commands and their arguments are separated by spaces and/or tabs.
 366 Command groups are separated by spaces, tabs, or newlines.
 367 .PP
 368 Expressions must not contain spaces or tabs.
 369 .nf
 370 This is ok : let n=x+76
 371 This is not: let n= x + 76
 372   Because this space ^ would terminate the let command group.
 373 .fi
 374 .
 375 .SS Error reporting
 376
 377 When
 378 .B gcom
 379 detects a script error, it immediately turns on verbose mode,
 380 generates a dump (see the dump command), reports the error in three lines
 381 and stops the execution.  The first line reported is the command group
 382 being executed, the second one shows where the parser got and the third
 383 line reports the character position of the program counter, the error and
 384 the exit code.
 385
 386 Here\'s an example:
 387 .PP
 388 .in +5
 389 .nf
 390 $ gcom -vs blar2.scr
 391 .fi
 392 .in -5
 393 .PP
 394 Where the blar2.scr script is:
 395 .PP
 396 .nf
 397 .in +5
 398 inc n
 399 dec d3
 400 let a=58/3
 401 let $d="fod"
 402 let c=1/0
 403 let $y4="sdfgsdfgsdfg"
 404 .in -5
 405 .fi
 406 .PP
 407 The trace and error report looks like this:
 408 .PP
 409 .in +5
 410 .nf
 411 gcom 11:20:15 -> Verbose output enabled
 412 gcom 11:20:15 -> Script file: blar2.scr
 413 gcom 11:20:15 -> argc:3
 414 gcom 11:20:15 -> argv[0]=gcom
 415 gcom 11:20:15 -> argv[1]=-vs
 416 gcom 11:20:15 -> argv[2]=blar2.scr
 417 gcom 11:20:15 ->  ---Script---
 418 .in +3
 419 1@0000 inc n
 420 2@0007 dec d3
 421 3@0015 let a=58/3
 422 4@0027 let $d="fod"
 423 5@0041 let c=1/0
 424 6@0052 let $y4="sdfgsdfgsdfg"
 425 .in -3
 426 gcom 11:20:15 ->  ---End of script---
 427 gcom 11:20:15 -> @0000 inc n
 428 gcom 11:20:15 -> @0007 dec d3
 429 gcom 11:20:15 -> @0015 let a=58/3
 430 gcom 11:20:15 -> @0027 let $d="fod"
 431 gcom 11:20:15 -> @0041 let c=1/0
 432 gcom 11:20:15 -> -- Error Report --
 433 gcom 11:20:15 -> ---->         ^
 434 gcom 11:20:15 -> Error @49, line 5, Division by zero. (6)
 435 .fi
 436 .in -5
 437 .
 438 .SS Exit codes
 439 When
 440 .B gcom
 441 terminates, it does so with an "exit code".  That is a number passed
 442 back to the calling process to signify success or failures.  In every-day
 443 Unix, 0 (zero) means success and everything else means whatever the author
 444 of the program wants it to mean.  In a shell script, or directly on the command
 445 line, you may look at the content of
 446 .I $?
 447 after having called
 448 .B gcom
 449 to examine its exit code.
 450 .PP
 451 Example:
 452 .PP
 453 .in +5
 454 .nf
 455 #!/bin/sh
 456 gcom /root/bin/call-isp
 457 if [ $? != 0 ]; then
 458   echo "Oops! Something went wrong."
 459 fi
 460 .fi
 461 .in -5
 462 .PP
 463 Internal
 464 .B gcom
 465 error codes are as follows:
 466 .PP
 467 .in +5
 468 .nf
 469 0 : No problems whatsoever.  Apparently.
 470 1 : Communication device problems.
 471 2 : Console (tty) device problems.
 472 3 : Memory problems.
 473 4 : File or pipe problems.
 474 5 : Syntax errors.
 475 6 : Division by zero.
 476 7 : Variable mis-management.
 477 8 : System problems.  (Couldn\'t call /bin/sh or some such)
 478 .fi
 479 .in -5
 480 .
 481 .SS Commands
 482 .PP
 483 .nf
 484 Command     : :   Alias: label
 485 Description : Notes an anchor point for goto or gosub to branch to.
 486 Syntax      : Keyword must not contain any special characters.
 487 Note        : Must be first statement in a line.
 488 See Also    : goto, gosub, return.
 489 Example:
 490               :loop
 491               gosub bravo
 492               print "The time is ",$time(),"\\n"
 493               sleep 1
 494               goto loop
 495               label bravo
 496               print "Twonk!\\n"
 497               return
 498
 499 Command     : abort
 500 Description : Causes gcom to call abort() and produce a core dump.
 501 Syntax      : abort
 502 See Also    : dump, exit.
 503
 504
 505 Command     : cd
 506 Description : Change directory.
 507 Syntax      : cd directory
 508 Notes       : -1 is returned in % if the change could not be made.
 509 Notes       : directory is a string and thus could be a variable.
 510 See Also    : $cwd().
 511 Example:
 512               cd "duh"
 513               if % != 0 print "Could not cd into duh.\\n"
 514
 515
 516 Command     : close
 517 Description : closes file previously opened with open.
 518 Syntax      : close file
 519 See Also    : open.
 520
 521
 522 Command     : dec
 523 Description : Decrements the content of an integer variable by 1.
 524 Syntax      : dec x
 525 Notes       : x is from a to z or a0 to z9.
 526 Notes       : Note that "let x=x-1" also works.
 527 See Also    : let, inc.
 528
 529
 530 Command     : dump
 531 Description : Lists all non-zero integer variables and modified string
 532 Description : variables as log entries (standard error channel.)
 533 Syntax      : dump
 534 See Also    : abort, exit
 535
 536
 537 Command     : else
 538 Description : Alternatively execute commands if last "if" tested false.
 539 Syntax      : else commands...
 540 See Also    : if
 541 Example:
 542               if w<350 print "Wow! Imagine that.\\n"
 543               else print "Rush Limbaugh is a big fat bastard.\\n"
 544
 545
 546 Command     : eprint
 547 Description : print a comma-separated list of arguments on stderr.
 548 Syntax      : eprint var,stringvar,"text",...
 549 Notes       : Like print but on the standard error file descriptor.
 550 Notes       : The error output can be re-directed with "2>file" on
 551 Notes       : the command line.
 552 See Also    : print.
 553
 554
 555 Command     : exec
 556 Description : Replaces current gcom process with another process.
 557 Syntax      : exec "command -args..."
 558 See Also    : system, fork.
 559 Example:
 560               #Finished script, call cu.
 561               exec "cu -l "+$dev()+" -s "+$baud()
 562
 563
 564 Command     : exit
 565 Description : terminates script execution with exit code.
 566 Syntax      : exit exit_code
 567 See Also    : abort, dump.
 568 Example:
 569               :error
 570               exit 1
 571               :smeggit
 572               exit 0
 573
 574
 575 Command     : flash
 576 Description : Toggles DTR on communication device for a specified time.
 577 Syntax      : flash float_constant
 578 Notes       : float_constant is precise down to 1/100th sec.
 579 Notes       : Causes modem to drop carrier or go to command mode,
 580 Notes       : depending on modem settings.  Setting the baud rate to 0
 581 Notes       : for a time has the same effect.
 582 See Also    : sleep, set com.
 583 Example:
 584               :disconnect
 585               flash 0.5
 586               exit 0
 587
 588
 589 Command     : fprint
 590 Description : print a comma-separated list of arguments in a file.
 591 Syntax      : fprint var,stringvar,"text",...
 592 Notes       : Like print but appended to a file previously opened
 593 Notes       : by open.
 594 See Also    : print.
 595
 596
 597 Command     : fork
 598 Description : forks gcom process in two.  Both processes continue
 599 Description : executing the script.
 600 Syntax      : fork
 601 Notes       : % returns 0 for child process, new process ID for
 602 Notes       : parent or -1 for error.
 603 See Also    : wait, kill, pid(), ppid().
 604 Example:
 605               fork
 606               if % = -1 goto error
 607               if % = 0 goto child
 608               :parent
 609               ...
 610
 611 Command     : get
 612 Description : get string from communication device.
 613 Syntax      : get timeout "terminators" $string
 614 Notes       : timeout is a float constant, terminators is a
 615 Notes       : list of characters that, when received, terminate
 616 Notes       : get.  Terminators are ignored when received first.
 617 See Also    : waitfor.
 618 Example:
 619               waitfor 60 "connect"
 620               if % != 0 goto error
 621               get 2 " ^m" $s
 622               print "Connection parameters: ",$s,"\\n"
 623
 624
 625 Command     : gosub
 626 Description : calls a subroutine.
 627 Syntax      : gosub label
 628 Notes       : Currently, gcom only supports 128 levels of gosub
 629 Notes       : calls (enough!)
 630 See Also    : :, goto, return.
 631 Example:
 632               gosub routine
 633               sleep 1
 634               gosub routine
 635               goto end
 636               :routine
 637               print "Flim-flam!\\n"
 638               return
 639
 640
 641 Command     : goto
 642 Description : Sends execution somewhere else in the script.
 643 Syntax      : goto label
 644 See Also    : :, gosub, return.
 645 Example:
 646               :win95
 647               print "Today I want to go and use Linux, thank you.\\n"
 648               goto win95
 649
 650
 651 Command     : hset
 652 Description : Set the hundreds timer.
 653 Syntax      : hset value
 654 Notes       : This command resets the hundreds of seconds timer to
 655 Notes       : a value for htime to start from.
 656 See Also    : htime().
 657 Example:
 658               hset 0
 659               :loop
 660               print "Time in 1/100 of a sec.: ",htime(),"\\n"
 661               sleep 0.01
 662               goto loop
 663
 664
 665 Command     : if
 666 Description : tests a condition
 667 Syntax      : if test_condition commands...
 668 Notes       : Conditionnaly executes commands if test condition is true.
 669 Notes       : Test operators are = (equal), != (not equal),
 670 Notes       : <> (not equal to) < (less than), > (greater than),
 671 Notes       : <= (less or equal), >= (greater or equal).
 672 Notes       : All operators can be used with integers and strings.
 673 Notes       : If test_condition is false, if skips to
 674 Notes       : the next line.
 675 See Also    : else.
 676 Example:
 677               if n>30 print "Oh-ho! too many sheep!\\n" goto error
 678               if n=17 print "Hurray! we\'ve enough sheep\\n" goto party
 679               if n<17 print "Murray, get more sheep.\\n" goto getmore
 680               if $z < "Marmaluke" goto ...
 681               if 3*a>5+b goto ...
 682
 683
 684 Command     : inc
 685 Description : increments the content of an integer variable by 1.
 686 Syntax      : inc x
 687 Notes       : x is a-z or a0-z9.
 688 See Also    : dec, let.
 689
 690
 691 Command     : input
 692 Description : input string from keyboard into string variable.
 693 Syntax      : input $x
 694 Notes       : input terminates entry only with the ENTER key.
 695 Notes       : Spaces, tabs and other funny characters are all
 696 Notes       : stored in the variable.
 697 See Also    : set echo.
 698 Example:
 699               print "Enter your full name :"
 700               input $n4
 701
 702
 703 Command     : kill
 704 Description : Sends a signal to a process.
 705 Syntax      : kill signal processID
 706 Notes       : Both signal and processID are integer values.  Same as
 707 Notes       : standard unix kill except that signal aliases are not
 708 Notes       : accepted and signal is not optional.
 709 Notes       : 0 is returned in % if the signal could be sent, -1
 710 Notes       : otherwise.
 711 Notes       : Signal 0 can be used to detect process existance.
 712 See Also    : wait, pid(), ppid().
 713 Example:
 714               fork
 715               let p=%
 716               if p = 0 goto child
 717               sleep 300
 718               kill 15 p
 719               sleep 1
 720               kill 0 p
 721               if % != 0 print "Child terminated\\n" goto ok
 722               print "Could not terminate child!\\n"
 723               kill 9 p
 724               sleep 1
 725               kill 0 p
 726               if % = 0 print "Could not kill child!\\n" goto error
 727               print "Child killed.\\n"
 728               :ok
 729               ...
 730
 731
 732 Command     : let
 733 Description : Does a variable assignment.
 734 Syntax      : let x=content
 735 Notes       : x is [$]a0-z9.
 736 See Also    : inc, dec.
 737 Example:
 738               let a=5
 739               let b=(time()-a)+5
 740               let y7=6809
 741               let z=0%11010111  #Binary
 742               let z=077324      #octal
 743               let z=0xf5b8      #hexadecimal
 744               let $c="Daniel "
 745               let $d=$c+" Chouinard"
 746               let $s5="Frimpin\' Jeosaphat!"
 747
 748
 749 Command     : lprint
 750 Description : Print a comma-separated list of arguments to the log.
 751 Syntax      : fprint var,stringvar,"text",...
 752 Notes       : Like print but printed like a log entry if verbose is on.
 753 Notes       : logging is sent to stderr.
 754 See Also    : print, eprint, fprint.
 755
 756
 757 Command     : open
 758 Description : Opens a file or a communication device.
 759 Syntax      : open com device, open com (stdin), open file FILE
 760 See Also    : close.
 761 Example:
 762               open com /dev/cua1
 763               set com 38400n81
 764               open file "/tmp/log"
 765               fprintf "This is a log\\n"
 766               close file
 767
 768
 769 Command     : print
 770 Description : print a comma-separated list of arguments.
 771 Syntax      : print var,stringvar,"text",...
 772 Notes       : Spaces and newlines are not automatically added.
 773 See Also    : eprint, fprint, lprint.
 774 Example:
 775               let b=26
 776               let $c="text variables"
 777               print "Contstant text ",b," ",$c," time: ",$time(),"\\n"
 778
 779
 780 Command     : putenv
 781 Description : Sets an environment variable.
 782 Syntax      : putenv "var=content"
 783 Notes       : Environment variables are automatically exported,
 784 Notes       : never returned. Children processes inherit the
 785 Notes       : environment.
 786 See Also    : $env().
 787 Example:
 788               putenv "SCRIPTDIR=/usr/lib/gcom/scripts"
 789               system "dothat"  # dothat reads env. var. SCRIPTDIR...
 790
 791
 792 Command     : rem  Aliases: #, //
 793 Description : Remark.  Rest of line is ignored.
 794 Syntax      : Note that a space must follow "rem".
 795 Example:
 796               #This is a remark
 797               // So is this
 798               rem This ain\'t no disco.
 799
 800
 801 Command     : return
 802 Description : Returns from subroutine.
 803 Syntax      : return
 804 See Also    : gosub.
 805
 806
 807 Command     : send
 808 Description : sends a string to the communication line (modem usually).
 809 Syntax      : send string
 810 Notes       : Carriage return (ENTER) is not sent automatically
 811 Notes       : (use ^m).
 812 Example:
 813               send "atdt555-1212^m"
 814               send $g+"^m"
 815               send "The time is "+$time()+"^m^j"
 816
 817
 818 Command     : set
 819 Description : sets working parameters.
 820 Syntax      : set parameter value
 821 Notes       :
 822
 823 Command                       Description
 824 ----------------------------- -------------------------------------------------
 825 set echo on|off               Keyboard echo on-screen.
 826 set comecho on|off            Received characters echoed on-screen.
 827 set senddelay time_constant   In-between character delay for "send"
 828 set ignorecase on|off         Case sensitivity for "waitfor".
 829                               Default=on.
 830 set clocal on|off             clocal on = ignore modem signals
 831 set umask mode                file mode creation defaults.
 832                               See man umask.
 833 set verbose on|off            verbose on = debug output enabled.
 834 set com com_params            communication parameters.
 835                                    ex.: 19200n81, 300e71
 836                                              baud |||
 837                                            Parity    |
 838                                         Data bits     |
 839                                         Stop bits      |
 840
 841 Example:
 842               set echo off
 843               print "Password :"
 844               input $p
 845               print "\\n"
 846               set echo on
 847               set comecho on
 848               set clocal on
 849               set senddelay 0.1
 850               set ignorecase on
 851               set com 38400n81
 852               set umask 022 # Must be octal (leading zero)
 853               ...
 854
 855 Note on clocal:
 856   If want your script to keep working after the carrier detect
 857   signal has dropped, set clocal on, otherwise, a CD drop causes
 858   the device line to close (hang up).  This could happen if,
 859   let\'s say, your script calls and connects, then disconnects or
 860   drops dtr (flash), then tries to re-connect again.
 861
 862
 863 Command     : sleep
 864 Description : Pauses execution.
 865 Syntax      : sleep float_constant
 866 Notes       : Float_constant is precise down to 1/100th sec, unless
 867 Notes       : more than 100 seconds, in which case the precision
 868 Notes       : falls down to 1 sec.
 869
 870 Example:
 871               sleep 0.06
 872               sleep 3
 873               sleep 86400 /* A whole day */
 874
 875
 876 Command     : system
 877 Description : Calls a system (unix) command
 878 Syntax      : system "command"
 879 See Also    : exec.
 880 Example:
 881               :dir
 882               print "listing of directory ",$cwd(),\\n"
 883               system "ls -l |more"
 884
 885
 886 Command     : testkey
 887 Description : Tests keyboard for keystroke, returns 1 in % if present.
 888 Syntax      : testkey
 889 Notes       : Can only test for ENTER key.  Future versions of gcom
 890 Notes       : will test for more and return keycodes in %.
 891 See Also    : input.
 892 Example:
 893               let n=1
 894               :loop
 895               print n," sheep... ZZZzzz...\\n"
 896               sleep n
 897               inc n
 898               testkey
 899               if % = 0 goto loop
 900
 901
 902 Command     : wait
 903 Description : Wait for a child process to terminate.
 904 Syntax      : wait
 905 Notes       : Process ID of terminated child is returned in %
 906 See Also    : fork, kill.
 907 Example:
 908               fork
 909               let p=%
 910               if p=0 goto child
 911               if p=-1 goto error
 912               print "Waiting for child to finish..."
 913               wait
 914               print "\\n"
 915               if %!=p print "Wait got wrong PID!\\n" goto error
 916               print "Child is done.\\n"
 917
 918
 919 Command     : waitfor
 920 Description : Waits until one of a list of strings is received
 921 Syntax      : waitfor timeout "string1","string2","string3"...
 922 Notes       : Timeout is a floating time constant.  waitquiet returns
 923 Notes       : 0 for the first string received, 1 for the second, etc...
 924 Notes       : and -1 for a timeout.  Case is ignored by default unless
 925 Notes       : ignorecase is set to off.
 926 See Also    : get.
 927 Example:
 928               :dial
 929               send "atdt555-4411^m"
 930               waitfor 60 "no carrier","busy","no dial tone","connect"
 931               if % = -1 goto timedout
 932               if % = 0 goto nocd
 933               if % = 1 goto redial
 934               if % = 2 goto error
 935               if % = 3 goto connected
 936
 937
 938 Command     : waitquiet
 939 Description : Waits until communication line stops receiving for a time.
 940 Syntax      : waitquiet timeout quiettime
 941 Notes       : Both timeout and quiettime are floating time constants
 942 Notes       : with 1/100th sec. accuracy.  Usefull for "swallowing"
 943 Notes       : incoming characters for a while or waiting for an
 944 Notes       : unknown prompt.
 945 Example:
 946               :closecon
 947               send "logoff^m"
 948               waitquiet 10 0.5
 949               send "yes^m"
 950 .fi
 951 .
 952 .SS Integer functions
 953 .PP
 954 .nf
 955 I-Function  : Access
 956 Description : Verifies access rights to a file
 957 Syntax      : let x=access("/tmp/file","frwx")
 958 Notes       : The second string contains one or more of
 959 Notes       : \'f\',\'r\',\'w\',\'x\' to repectively check
 960 Notes       : existence, read, write and execute permissions.
 961 Notes       : Under root id, the only useful check is \'f\', as
 962 Notes       : all others will return true.
 963 Return Value: 0 if the file exists, is readable, writable,
 964 Return Value: executable, or -1 if not.
 965 See Also    : man access(2)
 966
 967 I-Function  : baud
 968 Description : Returns current baudrate of communication line.
 969 Syntax      : let x=baud()
 970 Notes       : Does not necessarily match the modem connection speed.
 971 See Also    : $baud().
 972
 973 I-Function  : len
 974 Description : Returns the length of a string.
 975 Syntax      : let x=len($s)
 976 Notes       : "" is zero.  Strings currently have a maximum length of
 977 Notes       : 1024 characters. gcom doesn\'t handle string overflow
 978 Notes       : at all.
 979
 980 I-Function  : htime
 981 Description : Returns hundreds of seconds since start of script.
 982 Syntax      : let x=htime()
 983 Notes       : Set to a specific value with hset.
 984 See Also    : hset.
 985
 986 I-Function  : pid
 987 Description : Returns process ID number of current process (gcom)
 988 Syntax      : let x=pid()
 989 See Also    : ppid(), fork
 990
 991 I-Function  : ppid
 992 Description : Returns process ID number of parent process.
 993 Syntax      : let x=ppid()
 994 Notes       : Can be used by forked child to detect parent
 995 Notes       : process.
 996
 997 I-Function  : time
 998 Description : Returns time in seconds since Jan 1, 00:00:00 1970 GMT.
 999 Syntax      : let x=time()
1000 Notes       : Used to calculate time differences.
1001 See Also    : $time()
1002
1003
1004 I-Function  : val
1005 Description : Returns value of string.
1006 Syntax      : let x=val($x)
1007 Notes       : String is not an expression; must only contain [0-9]
1008 Notes       : characters. Future versions of gcom will be able to
1009 Notes       : evaluate expressions. (Maybe) (This was written 6
1010 Notes       : years ago.)
1011
1012
1013 I-Function  : verbose
1014 Description : Returns value of verbose setting.
1015 Syntax      : let x=verbose()
1016 Notes       : 0=off, 1=on.
1017 .nf
1018 .
1019 .SS String functions
1020 .PP
1021 .nf
1022 S-Function  : basename
1023 Description : Returns basename part of path.
1024 Syntax      : let $x=$basename($p)
1025 Notes       : $basename("/usr/bin/more")="more"
1026 See Also    : $dirname().
1027
1028 S-Function  : baud
1029 Description : Returns string representation of current baud rate.
1030 Syntax      : let $x=$baud()
1031 Notes       : Defined by "set com"
1032 See Also    : baud(), set com.
1033
1034 S-Function  : cwd
1035 Description : Returns current working directory pathname.
1036 Syntax      : let $x=$cwd()
1037 See Also    : cd.
1038
1039 S-Function  : dev
1040 Description : Returns current communication device pathname.
1041 Syntax      : let $x=$dev()
1042 Notes       : defined by "-d" command line argument or "open com"
1043 See Also    : open com.
1044
1045 S-Function  : dirname
1046 Description : Returns directory name part of path.
1047 Syntax      : let $x=$dirname($p)
1048 Notes       : $dirname("/usr/bin/more")="/usr/bin"
1049 See Also    : $basename().
1050
1051 S-Function  : env
1052 Description : Returns content of an environment variable
1053 Syntax      : let $x=$env("HOME")
1054 Notes       : Non-existant variables return an empty string.
1055 See Also    : putenv.
1056
1057 S-Function  : hex
1058 Description : Converts value to hexadecimal representation
1059 Syntax      : let $x=$hex(x)
1060 Notes       : Letters a-f in lowercase, no preceding "0x"
1061 See Also    : $hexu(), $oct().
1062
1063 S-Function  : hexu
1064 Description : Converts value to hexadecimal representation
1065 Syntax      : let $x=$hex(x)
1066 Notes       : Letters A-F in uppercase, no preceding "0x"
1067 See Also    : $hex(), $oct().
1068
1069 S-Function  : hms
1070 Description : Converts number of seconds into time string
1071 Syntax      : let $x=$hms(x)
1072 Notes       : Format is "HH:MM:SS".  Useful for chronometer displays
1073 Notes       : Use with "time()", do not try to increment a variable
1074 Notes       : every second using "sleep 1".  (See ISP script example)
1075 Notes       : Format becomes "HHH:MM:SS" after 99 hours, 59 minutes,
1076 Notes       : 59s...
1077 See Also    : time().
1078
1079 S-Function  : left
1080 Description : Returns left portion of a string
1081 Syntax      : let $x=$left($s,l)
1082 Notes       : $s=Source string, l=length
1083 Notes       : l must be less than the length of the string.
1084 See Also    : $right(), $mid().
1085
1086 S-Function  : mid
1087 Description : Returns midsection of a string.
1088 Syntax      : let $x=$mid($s,s,l)
1089 Notes       : $s=Source string, s=start, l=length
1090 Notes       : s must be less than the length of the string, l can be
1091 Notes       : some huge number (9999) to return the right side of a
1092 Notes       : string to the end.  the first character of a string is
1093 Notes       : position 0, not 1.
1094 See Also    : $right(), $left().
1095
1096 S-Function  : oct
1097 Description : Converts value to octal representation.
1098 Syntax      : let $x=$oct(x)
1099 See Also    : $hex(), $hexu().
1100
1101 S-Function  : right
1102 Description : Returns right portion of a string.
1103 Syntax      : let $x=$right($s,l)
1104 Notes       : $s=Source string, l=length
1105 Notes       : l must be less than the length of the string.
1106 See Also    : $left(), $mid().
1107
1108 S-Function  : rpipe
1109 Description : Returns the first line from a system piped command
1110 Syntax      : let $x=$rpipe("/bin/ls |grep myfile")
1111 Notes       : Not very useful unless used with head, tail, grep,
1112 Notes       : etc...
1113 See Also    : system.
1114
1115 S-Function  : time
1116 Description : Returns 24 character local time string
1117 Syntax      : let $x=$time()
1118 See Also    : time().
1119 Notes       : Time is in this format: Mon Apr  8 14:21:22 1996
1120                                       012345678901234567890123
1121                                                 1         2
1122
1123 S-Function  : tolower
1124 Description : Returns lowercase\'d string.
1125 Syntax      : let $x=$tolower($y)
1126
1127 S-Function  : toupper
1128 Description : Returns uppercase\'d string.
1129 Syntax      : let $x=$toupper($y)
1130 .fi
1131 .
1132 .SS Test operators
1133 .PP
1134 .nf
1135 Operator Description       Example       Result
1136 =        equal             if 1+2=3      yes
1137 !=       not equal         if 1+2!=3     no
1138 <>       not equal         if 1+2<>3     no
1139 >        Greater than      if 1+3>3      yes
1140 <        Less than         if 1+3<3      no
1141 >=       Greater or equal  if 3>=3       yes
1142 <=       Greater or equal  if 2<=3       yes
1143 .nf
1144 .PP
1145 Strings can be compared using the same operators.
1146 .PP
1147 .nf
1148 "aaa" < "aab",  "aaaa" > "aaa", "Test" != "test", "One" = "One",
1149 "A" > "a", "Fumble" <= "Fumigate", "Farsical" <> "Comedic"
1150 .fi
1151 .PP
1152 .B Note
1153 that "set ignorecase on" does NOT apply to string comparisons.
1154 .
1155 .SS Expression operators
1156 .PP
1157 .nf
1158 Operator  Description      Example           Result
1159 +         Addition         let a=2+2         4
1160 +         Concatenation    let $b="aa"+"bb"  "aabb"
1161 -         Substraction     let e=2-5         -3
1162 *         Multiplication   let f=11*2        22
1163 /         Division         let g=34/11       3
1164 &         Bit-Wise AND     let h=42&7        2
1165 |         Bit-Wise OR      let a=42|5        47
1166 ^         Bit-Wise XOR     let a=42^7        45
1167 .fi
1168 .PP
1169 Mixed expression examples:
1170 .PP
1171 .nf
1172 #Returns number of seconds since 00:00:00
1173 let $t=$time() #Take a snapshot.
1174 let a=(val(mid$($t,11,2))*3600)+(val(mid$($t,14,2))*60)+val(mid$($t,17,2))
1175 #Notice the extra sets of parenthesis because gcom\'s expression
1176 #evaluator is brain-dead.
1177 #For example, 5-2+1 should give you 4, right?  Well, according to
1178 #getvalue(), it actually gives 2, because it does it somewhat from
1179 #right to left.
1180 #So to evaluate 5-2+1 correctly, use (5-2)+1.  If you\'re using
1181 #simple, two-element calculations, don\'t worry about it.
1182 #5-2 will give you 3.
1183 .PP
1184 #Concatenation  (Calls cu)
1185 exec "cu -l "+$dev()+" -s "+$baud()"
1186 .PP
1187 #In a test condition
1188 if a+c > strlen($c) goto toomuch
1189 .PP
1190 #String comparison
1191 let $t=$mid($time(),11,8)
1192 if $t > "19:59:59" print "Too late for that!\\n" goto toolate
1193 if $t < "08:00:00" print "Too early!\\n" goto tooearly
1194 if $t = "00:00:00" print "Oh god!  It\'s Twinkee time!\\n"
1195 .fi
1196 .
1197 .SH KNOWN "FEATURES"
1198 The getvalue() parser.  It makes me laugh so I think I\'ll leave it that way.
1199 - Daniel.Chouinard@pwc.utc.com
1200 .
1201 .SH AUTHORS
1202 .PP
1203 Daniel.Chouinard <Daniel.Chouinard@pwc.utc.com> wrote the original
1204 .B dcon
1205 utility.
1206 .PP
1207 Paul Hardwick <paul@peck.org.uk> updated it for the latest compilers,
1208 provided the built-in script functionality and tested it against
1209 GPRS and 3G datacards.
1210 .PP
1211 Martin Gregorie <martin@gregorie.org> wrote the original manpage for
1212 .B gcom
1213 from the
1214 .B dcon
1215 documentation and packaged
1216 .B gcom
1217 for distribution.
1218 .
1219 .SS History
1220 Daniel
1221 Chouinard wrote most (90%) of
1222 .B dcon
1223 back in 1989 when he started doing Unix Apps tech support mostly
1224 by modem to customer
1225 systems.  He was tired of typing all those passwords and funny call-charging
1226 codes everytime he used cu.  Also, the company he worked for needed a system
1227 that would log call times and estimated costs.  Thus
1228 .B dcon
1229 was born.
1230 Six or seven years later (1996) and he was using pppd to connect to
1231 his ISP site.  He was more or less happy with
1232 .B chat
1233 but found it lacked flow control and multiple response checks
1234 from "atdt...".
1235 He wanted it to do different things for "no carrier", "no dial tone",
1236 and "busy".
1237 Although he thought that
1238 .B chat
1239 would probably be enhanced someday, when he found dcon.c on one of his
1240 old 45M tapes he
1241 tried compiling it on his Linux box and, lo and behold, it did.
1242 In the end, he added a few things to it (kill, fork, wait, 1/100 sec. times)
1243 and left it at that.
1244 .PP
1245 A couple of years ago Paul Hardwick found the
1246 program,
1247 .B dcon 0.97,
1248 last modified in 1996. The purpose of this
1249 program was to run scripts that would control Linux serial ports. The
1250 implementation was very similar to something he had written for
1251 Windows. Anyway, rather than reinvent he contacted the author, Daniel
1252 Chouinard, and asked his permission to reuse the code.
1253 Happily he gave permission and a basic but useful utility
1254 called
1255 .B gcom
1256 was created. Paul takes no credit for the engine,
1257 apart from making it compatible with todays compilers.
1258 It is basically
1259 .B dcon
1260 repackaged.
1261
1262