Copy, Pack, Translate

The CDS copyto and copyfm functions copy data to or from (respectively) a CDS region, with the other end of the copy in the process's local memory.  These functions take the form:
cds_copyto(rgid,offset,buffer,btype,cnvrsn)
cds_copyfm(rgid,offset,buffer,btype,cnvrsn)
Here, offset describes the number of bytes from the beginning of the CDS region where the copy is to begin, buffer describes the location in process memory where the copy is to begin, and btype describes how the copy is to take place, as described below.  cnvrsn denotes a conversion table which describes how different types of data are to be converted and/or aligned during the copy.  A cnvrsn value of zero may be supplied to suppress conversion (i.e. implement a straight copy), but useful values of cnvrsn can also be obtained from another CDS function, cds_transtab, which takes two CDS process IDs and returns the appropriate conversion table to convert between their respective data representations.

For copytofm, which copies between two CDS regions, buffer is not used, and instead two offsets are specified, one for each buffer:

cds_copytofm(rgid1,offset1,rgid2,offset2,btype,cnvrsn)
One other function,
cds_typlen(btype,cnvrsn,offset)
returns the number of bytes which would be copied to or from the region if the given arguments were used on a copy operation (assuming that there is sufficient room in the region to accomodate them).

The routines described here don't technically do anything that the programmer can't do entirely outside of CDS, but in a subsequent section (on message passing), having a well-defined copy interface within CDS becomes important.

How btype works

For the copy routines, btype is a CDS type, which is a sequence of type elements, each which can be considered as having the form
[+o][/]t[*n]
(The brackets enclose optional fields and are not actually part of the type.)  o is an integer representing an offset (assumed zero if omitted), the slash is an optional copy suppressor, n is an integer replicator (assumed 1 if omitted), and  t is either an atomic datatype from the set {int, float, longint, char} or another CDS type (i.e. a list of type elements) in parentheses.

Type conversion starts with a user-space pointer u beginning at buffer and a region-space pointer r beginning at the the beginning of the region or message (plus offset bytes if an offset argument is available in the specific function).   Then, the type elements are processed in order.

For each type element

The copy operation is terminated prematurely if there is insufficient room/data within the region to perform a copy operation.

Textual representation for CDS types

The user can represent a CDS type textually just as above (i.e. as a sequence of concatenated [+o][/]t[*n]), but this must be converted to an internal form before it can be used by CDS.  The function to do this conversion is
retval = cds_type(tstring, tterm, btype, btsize)
where tstring is the sequence of characters representing the CDS type, tterm is the character which terminates tstring, btype is an integer vector to contain the result, and btsize is the number of elements in btype. btsize should be a multiple of 3 because, in general, each type element will take 3 elements in btype.  The function returns the number of elements actually needed in btype (always a multiple of 3) negated if btsize was too small to accomodate this.  (Thus, it is possible to use this function first to query how large btype should be by calling with btsize equal to 0.)

Integer representation for CDS types

Often, a program finds it easier to manipulate a CDS type in its native form, as an array of integers, rather than as a character string.  This is easily done by using the following specification.  Each three consecutive vector elements in btype represents one type element--one vector element for o, one for t, and one for n, in that order.  For t, the types int, float, longint, and char are represented with predefined constants CDS_TINT, CDS_TFLT, CDS_TLINT, and CDS_TCHAR respectively.   If the suppressor (/) is present, the integer representing t must be or'd with CDS_TSUPP.  The last type element of a CDS type is denoted by or'ing the o field with CDS_TEND.  A nested CDS type (i.e. one with t in parens) is denoted by the predefined constant CDS_TNEST or'd with a positive integer offset in triples.  (That is, when CDS finds a t field containing the CDS_TNEST flag, it removes the flag and starts decoding the CDS type offset by
t * 3
integers from the beginning of the current triple.)
 

Examples

Note:  Technically, C does not define how its structure members will be stored/packed into memory, so it is technically not correct to define here how CDS can operate on such structures.  However, one can usually assume a relatively sensible layout from C, and in fact, the cnvrsn argument can be used to get even unusual C implementations to "do the right thing".

Example 1.  To copy a record having the following C struct type

struct {int vec[10];
        char flag;
        float x, y;}
except for the field named flag:
retval = cds_type("int*10 /char float*2", '/0', btype, 20);
would return the value 9 in retval and the following values in btype
0,        CDS_TINT,            10,
0,        CDS_CHAR | CDS_TSUPP, 1,
CDS_TEND, CDS_TFLT,             2
Example 2.  To copy just the left-most and bottom-most elements from a 10 by 10 array of floats in C (i.e. stored by row):
retval = cds_type("(float /float*9)*9 float*10", '/0', btype, 12);
would return the value 12 in retval and the following values in btype:
0,               2 | CDS_TNEST,  9,
CDS_TEND, CDS_TFLT,             10,
0,        CDS_TFLT,              1,
CDS_TEND, CDS_TFLT | CDS_TSUPP,  9

[Index]  On to Message Passing

Copyright 2000 © elepar   All rights reserved