perlorb.3p BRTT Antelope 4.10

NAME

perlorb - perl interface to orb and packet routines

SYNOPSIS

use orb ;
use Datascope ;

These perl extension routines provide a fairly complete interface to the Antelope orb and Pkt libraries. There are routines to open and close a connection to an orbserver, to get status information, to position the packet pointer, to select and reject packets based on srcname, and to get and put packets. In addition, there is an unstuffPkt routine, which returns various objects depending on packet type. A database row, a parameter file object, or samples from a data packet may be obtained.

In this package, when the corresponding c routine returns a complex structure (e.g., orbsources(3), orbclients(3), unstuffPkt(3)), the perl interface routine returns one or more objects. These objects have methods which return various values from the c struct.

Orb routines

orbopen(orbname, perm)
open the specified orbname with permission perm ("r", "w", "r&", or "w&")
```
$orb = orbopen ( "igpprt:anza", "r&" ) ;
```
orbclose(orb)
Close an orbconnection
```
orbclose($orb) ;
```
orbselect(orb, select)
orbreject(orb, reject)
Select packets with sourcenames which match the regular expression select. Reject packets with sourcenames which match the regular expression reject.
```
$n = orbselect ( $orb, "AZ_.*|CI_.*" ) ;
$n = orbreject ( $orb, "/db/detection" ) ;
```
orbstashselect(orb, stashselect)
Specify screening criteria for stash packets; stashselect is one of "STASH_ALL", "STASH_ONLY", or "NO_STASH".
```
$n = stashselect ( $orb, "STASH_ONLY" ) ;
```
The default is to return all packets, stash or not. If stashselect is "STASH_ONLY", only stash packets are returned from future orbreaps.
orbseek(orb, which)
Position the orb connection packet pointer according to which; which may be an explicit pktid, or "ORBCURRENT", "ORBPREV", "ORBNEXT", "ORBNEXT_WAIT", "ORBOLDEST", or "ORBNEWEST".
```
$pktid = orbseek ($orb, "ORBOLDEST") ;
$pktid = orbseek ($orb, 15327 ) ;
```
orbposition(orb, from)
Position the orb connection packet pointer according to from; from may newest, oldest, or any (UTC) time string recognized by str2epoch(3).
```
$pktid = orbposition ( $orb, "-0:10" ) ;
$pktid = orbposition ( $orb, "23:52 2001-163" ) ;
$pktid = orbposition ( $orb, "oldest" ) ;
```
orbtell(orb)
Return the current orb connection position (pktid).
```
$pktid = orbtell($orb) ;
```
orbafter(orb, time)
Position the orb connection packet pointer to the first packet after the specified time. Time must be a UTC epoch time in seconds, not a string.
```
$pktid = orbafter($orb, $time) ;
```
orbping(orb)
Test if the specified orb responds; returns a version number.
```
$version = orbping($orb) ;
```
orbwait(orb, re, mintime, timeout) ** deprecated **
Use orbput_nolag or orblag instead.

wait for all reading clients of orb with a program name which matches the regular expression re to have read packets younger than mintime. If timeout is non-zero, then orbwait returns with an error code if the timeout expires before the specified program catch up.
```
$result = orbwait($orb, "orb2db", 300, 0 ) ;
```
orblag(orb, match, reject)
returns oldest and newest pktid, maximum pktid, and the number of pktids in use (range), plus a list of lag parameters for each client matching the match/reject parameters. Each line contains: lag, thread, pktid, who, what.
```
my ($oldest, $newest, $maxpktid, $range, @clients) = orblag($orb, "orb2orb", "" ) ;
foreach (@clients) {
    my($lag, $thread, $pktid, $who, $what) =  split (' ', $_, 5) ;
}
```
orbget(orb, which)
Get a single packet selected by which: an explicit pktid, or "ORBCURRENT", "ORBPREV", "ORBNEXT", "ORBNEXT_WAIT", "ORBOLDEST", or "ORBNEWEST".
```
($pktid, $srcname, $time, $packet, $nbytes) =
                            orbget($orb, "ORBNEWEST") ;
```
orbgetstash(orb, srcname)
Get a single stash packet selected by srcname.
```
($time, $packet, $nbytes) = orbget($orb, "TA_Z14A/MGENC/M40") ;
```
orbreap(orb)
Get the next packet from the orb; this is the fastest, most efficient way of reading packets.
```
($pktid, $srcname, $time, $packet, $nbytes) = orbreap($orb) ;
```
orbreap_timeout(orb, maxseconds)
Get the next packet from the orb, but return early if no packets have appeared in maxseconds. In this case, the returned pktid is undef.
```
($pktid, $srcname, $time, $packet, $nbytes ) =
                            orbreap_timeout($orb, 1) ;
```
orbput(orb, srcname, time, packet, nbytes)
orbputx(orb, srcname, time, packet, nbytes)
Put the specified packet onto the orb. The orbputx version returns the pktid of the output packet.
```
orbput($orb, $srcname, $time, $packet, $nbytes) ;
```
orbstat(orb)
Get the standard status values from the orb; this returns an object with methods for the various values: when, address, version, pid, host, port, started, orb_start, who, maxdata, maxpkts, maxsrc, nclients, nsources, connections, messages, opens, closes, errors, and rejected.
```
$stat = orbstat($orb) ;
printf "At %s, the orbserver had %d clients and %d sources\n",
            strtime($stat->when), $stat->nclients, $stat->nsources ;
```
orbclients(orb)
returns a scalar when, followed by a list of client objects, one object per client. Each object has the following methods: started, lastpkt, pktid, packets, bytes, read, written, nreads, nwrites, nrequests, mymessages, lastrequest, priority, errors, nselect, select, nreject, reject, fd, thread, address, port, who, host, what, pid, and perm.
```
($when, @clients) = orbclients($orb) ;
foreach (@clients) {
    printf "%-8s %-12s %s\n", $_->who, $_->host, $_->what ;
}
```

orbsources(orb)
returns a scalar when, followed by a list of source objects, one object per source. Each object has the following methods: srcname, active, soldest, slatest, npkts, nbytes, soldest_time, and slatest_time.



($when, @sources) = orbsources($orb) ;
foreach $source (@sources) {
    printf "%-15s %8d %6.0f %s\n",
        $source->srcname, $source->npkts, $source->nbytes/1024.,
        strtdelta($when-$source->slatest_time) ;
}

Packet routines

showPkt(pktid, srcname, time, packet, nbytes, mode)
print out packet summary, depending on mode. Use either the PKT_* name or the corresponding integer. The output is written to stdout.

PKT_DUMP	1	hex dump
PKT_UNSTUFF	2	unstuff, print all data samples
PKT_NOSAMPLES	3	unstuff, print no data samples
PKT_TERSE	4	just show the header information
PKT_PEEK	5	show first 10 samples of waveform packets

unstuffPkt(srcname, time, packet, nbytes)
unstuffPkt calls the c routine to unstuff the input packet, returning a result code and a packet object. The result code indicates what kind of packet was unpacked:

result kind of packet
Pkt_wf waveform packet
Pkt_st status packet
Pkt_db database row
Pkt_pf parameter file
Pkt_cn control messages
Pkt_rw arbitrary binary data, wrapped in orb packet
Pkt_ch arbitrary character string
Pkt_tp test packet
Pkt_stash	stash packet

Unsurprisingly, the unstuffPkt routine has the most complex set of objects and methods. It returns an object with methods which also return objects, and certain methods return values only for the proper kind of packet. E.g., only a database packet (currently) returns a database pointer.

The packet object has methods which return various values from the c Packet structure: parts, time, PacketType, nchannels, channels(i), pf, string, db, dfile, and version.

The parts method returns a list of net, sta, chan, loc, suffix and subcode.

The PacketType method returns the packet kind (also returned by unstuffPkt) and the corresponding description.

The channels method takes an argument -- an index (0 to nchannels-1) into the packet's list of channels. It returns a channel object with its own methods: the familiar net, sta, chan, loc, time, nsamp, samprate, calib, calper, segtype, data, and some extra variables which occur only in some packets and have diverse uses there: duser1, duser2, iuser1, iuser2, iuser3, cuser1, cuser2. Of these, only the data method is exceptional: it returns all the waveform data in a list of integers.



($result, $pkt) = unstuffPkt($srcname, $time, $packet, $nbytes) ;
($net, $sta, $chan, $loc, $suffix, $subcode) = $pkt->parts() ;
($type, $desc) = $pkt->PacketType() ;

for ( $i=0 ; $i<$pkt->nchannels ; $i++ ) {
    $achan = $pkt->channels($i) ;
    printf "%s_%s_%s_%s",
        $achan->net, $achan->sta, $achan->chan, $achan->loc ;
    printf " %s",         strtime($achan->time) ;
    printf " %12.6f",     $achan->samprate ;
    printf " %8d\n",      $achan->nsamp ;
    @data = $achan->data ;
    for ( $i=0 ; $i<10 ; $i++ ) {
        printf "\n    %2d ", $i if $i % 5 == 0 ;
        printf " %10d", $data[$i] ;
    }
    printf "\n" ;
}

$pf = $pkt->pf ;
if ( defined $pf ) {
    $ref = pfget($pf, "" ) ;
    %pf = %$ref ;
    foreach ( sort keys %pf ) {
        printf "%-15s %s\n", $_, $pf{$_} ;
    }
}

@db = $pkt->db ;
if ( $db[0] >= 0 ) {
    printf "pkt->db = ( @db )\n" ;
    $schema = dbquery (@db, "dbSCHEMA_NAME" ) ;
    $table = dbquery (@db, "dbTABLE_NAME" ) ;
    printf "Record from table $schema:$table\n" ;
    @fields = dbquery (@db, "dbTABLE_FIELDS") ;
    foreach $field (@fields) {
        $value = dbgetv(@db, $field) ;
        printf "    %-15s %s\n", $field, $value ;
    }
}

$dfile = $pkt->dfile() ;
if ( defined $dfile ) {
    printf "\npkt->dfile is\n'$dfile'\n\n" ;
}
$version = $pkt->version ;
if ( defined $version ) {
    printf "pkt->version is '$version'\n" ;
}

$string=$pkt->string ;
if ( defined $string ) {
    printf "pkt->string is '$string'\n" ;
}

orbresurrect($orb, $pktid, $pkttime)
Restore the orb position to previous position as dictated by previous state file (created by bury), returning the packet id and time in the variables pktid and pkttime. Subsequent calls to bury save the current packet id and time in the state file.
split_srcname(srcname)
split_srcname returns net, sta, chan, loc, suffix, and subcode corresponding to $srcname
join_srcname(net, sta, chan, loc, suffix, subcode)
returns srcname corresponding to net, sta, chan, loc, suffix and subcode
orbpkt_string(srcname, time, packet, nbytes)
returns string corresponding to forb(5) representation of packet.
($name, $content, $desc) = suffix2pkttype(suffix)
returns name, content type and description for packet type suffix.

BUGS AND CAVEATS

The interface has many static variables in the implementation, which prevent it from being used in a threaded application.

There is no stuffPkt interface.

AUTHOR

Daniel Quinlan

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
- Orb routines
- Packet routines
SEE ALSO
BUGS AND CAVEATS
AUTHOR

Antelope Release 4.10 Linux SuSE 9.3 (i586) 2.6.11.4 2008-05-02
Boulder Real Time Technologies, Inc

http://www.brtt.com

2045 Broadway, Suite 400
Boulder, CO 80302
USA

For more information, contact support@brtt.com