NAME

canlink - a Perl module for the encoding and decoding of the MultiCAN Cryptic CAN Link definition.

SYNOPSIS

use canlink;

DESCRIPTION

Preface

This module contains functions that are used to decode and encode the EPICS hardware link definition that is used in MultiCAN. The EPICS device and driver support for the CAN bus that was developed for the HZB II control system. Note that HZB has the copyright on this software. It may not be used or copied without permission from HZB.

Implemented Functions:

interview
```
%link_definition= canlink::interview()
```
This functions creates a CAN link definition by asking the user several questions. Note that this function is interactive and uses simple terminal I/O.
explain
```
print canlink::explain(%link_definition)
```
This function returns a string that contains a short explanation on each hash key that is used in %link_definition. When called with no parameter, is returns an explanation on each hash-key known in this module.
pretty_print
```
print canlink::pretty_print(%link_definition)
```
This function returns a string that can be used to print the contents of the link-definition in a human-readable form.
tab_print
```
print canlink::tab_print(%link_definition)
```
This function is similar to pretty_print. It returns a string that can be used to print the contents of the link-definition in a human-readable form, but in a single line. So this function can be used to print tables. If called without any parameter, it returns the table-heading. Note that strings returned by tab_print are NOT terminated with a linefeed ("\n").
encode
```
$link_string= canlink::encode(%link_definition)
```
This function returns the string that is used in the MultiCAN implementation in the hardware-link field.
decode
```
%link_definition= canlink::decode($link_string)
```
This function takes the string that is used in the MultiCAN implementation in the hardware-link field as parameter and returns the link-definition in form of a hash.
complete
```
%completed_link_definition= canlink::complete(%link_definition)
```
This function completes the link-definition by adding default-values for some missing hash-keys. E.g. if the "signed" field is missing, the default, signed==0 which means "unsigned" is added. It also calculates node-id and connection-id (nid,cid) or node-id and sub-object-ids (SOBs) from the given can-object-ids (COBs).
calc_cob
```
%completed_link_definition= canlink::calc_cob(%link_definition)
```
This function completes the link-definition by calculating the can-object-ids (COBs) from the given node-id and connection-id (nid,cid) or node-id and sub-object-ids (SOBs).
calc_cidnidsob
```
%completed_link_definition= canlink::calc_cidnidsob(%link_definition)
```
This function completes the link-definition by calculating the node-id and connection-id (nid,cid) or node-id and sub-object-ids (SOBs) from the given can-object-ids (COBs)
cob2cidnid
```
($cid,$d,$nid)= canlink::cob2cidnid($cob)
```
This function calculates the connection-id, direction-flag and node-id, (cid,d,cid) from the given can-object-id (COB)
cidnid2cob
```
$cob= canlink::cidnid2cob($cid,$d,$nid)
```
This function calculates the can-object-id (COB) from the given connection-id, direction-flag and node-id (cid,d,cid)
cob2sobnid
```
($sob,$nid)= canlink::cob2sobnid($cob)
```
This function calculates the sub-object-id and node-id (sob,nid) from the given can-object-id (COB)
sobnid2cob
```
$cob= canlink::sobnid2cob($sob,$nid)
```
This function calculates the can-object-id (COB) from the given sub-object-id and node-id

the property hash

The property-hash may have the following contents:

server: This field specifies wether the host is a CAL server or a CAL server. Set this field to "1" for a server, and "0" for a client.
multi: This field specifies the multiplex-type. Set this field "1" \ for a multiplex-variable, and "0" for a basic-variable.
access: This field specifies the accessability of the CAL variable. Set is to "r" for a read-only variable, to "w" for a write-only variable and to "rw" for a read-write variable.
type: This specifies the basic data-type of the CAL variable. Known types are "zero", "string", "char", "short", "mid" and "long". "mid" is a special, 24-bit integer, "zero" is a datatyoe with a length of 0 bytes.
raw: This field specifies, whether the CAL byte-order is used (little-endian format) or wether the byte-order is left as it is. Set "0" to enforce CAL byte-order, and "1" for current byte order.
signed: This field is only used, when the type is not "string". Set it to "1" if the basic type (see type) is signed, or "0" if it is unsigned.
array: This field defines, wether a CAL array-variable is used. In this case, several elements of the basic type (see type) are packed into a single CAN frame. But note, that a CAN frame has a maximum length of 8 bytes. Set to "1" for array-variables or "0" else.
maxlength: This is the actual length of the CAN frame in bytes.
port: This is the number of the output-port (see sci - documentation for details).
out_cob: This is the COB for the outgoing CAN-object.
in_cob: This is the COB for the incoming CAN-object.
multiplexor: This is the multiplexor-index. It is only needed for multiplex variables (see multi).
inhibit: This is the inhibit-time in milliseconds. Note that this is a floating-point number.
timeout: This is the timeout in milliseconds. This parameter is an integer.
arraysize: This is the size (that means number of elements) of the CAL array. This field is only needed, if the CAL variable is an array (see array).
nid: This is the node-id of the CAL-server.
cid: This is the channel-id of the CAL variable.
in_sob: This is the sub-object id of the incoming CAN object.
out_sob: This is the sub-object id of the outgoing CAN object.

specification of a CAL variable via the property hash

In order to define a CAL variable by using the property hash, the following fields are always mandatory:

access
type
port
inhibit
timeout

Here is a list of fields that can be used, but have a default, when they are not specified:

server: default: 0
multi: default: 0
multiplexor: mandatory when multi is "1"
signed: default: 0
array: default: 0
arraysize: mandatory when array is "1"
raw: default:0 mandatory when type is neither "string" nor "char"

Specifying the COB's that are actually used, is a bit complicated. There are 3 ways:

Specify the COB's directly. In this case, the fields in_cob and out_cob must be specified.
Specify NID and IN-SOB and OUT-SOB. In this case, the node-id of the server, nid, the IN-SOB, in_sob and the OUT-SOB, out_sob must be specified.
Specify NID and CID, in this case, define nid and cid

EXAMPLES

format a user-defined can-link:

use canlink;

print "please specify a can link:";
my %link= canlink::interview();
print canlink::encode(%link),"\n";

decode and pretty-print a given MultiCAN link-string

use canlink;

print "please enter a can link string:";
my $str= <STDIN>;
my %link= canlink::decode($str);
die if (!%link);
print canlink::pretty_print(%link),"\n";

explain all known hash-fields

use canlink;

print canlink::explain();

AUTHOR

Goetz Pfeiffer, Goetz.Pfeiffer@helmholtz-berlin.de