- Generated on Mon Aug 21 2023 17:36:29 for Fortran SFF API to data I/O streams in C++ by
1.8.14
|
Fortran SFF API to data I/O streams in C++
|
Contents of this page:
The WID2 line character string used in libsff is not able to hold the full content of an ::sff::WID2 structure without loss of information. libfapidxx provides interfaces to other data formats than SFF which are able to represent the full ::sff::WID2 structure content in their trace headers. However libsff requires WID2 data to be encoded in ASCII representation in a WID2 line character string and be passed this way to the wrinting function. we therefore use the fapidxx::WID2container to pass WID2 data internally.
Not all functions implemented in libfapidxx are able to handle the binary encoded WID2 line.
Reading functions return data ASCII encoded (SFF standard). They are expected to provide WID2 data to a Fortran program, which expects the WID2 data fields within the character string as defined by ths SFF definition.
Writing function are able handle the received character sequence either as binary encoded or as standard SFF. The actual encoding is determined automatically.
The function preparing the WID2 line for the writing functions always returns a binary encoded string.
Functions implemented in Fortran also handle both encodings. Prior to any action they call function sff_helper_decode_wid2__ to ensure ascii encoding in the character sequence.
Modification functions are implemented such that they are able to receive WID2 in both encodings (either SFF type ASCII encoding or binary encoding). fapidxx::WID2container remembers the original type of encoding such that these functions will return the WID2 data in the encoding used to pass the data.
Here is an example from sff_modwid2samps__:
In this case WID2 data is received in a Fortran character sequence wid2line. The WID2container::wid2 member field provides all data fields. After adjusting them, the data is encoded into the Fortran character sequence either in binary or ascii form, depending on its original encoding.
fapidxx::WID2container alternatively can be initialized from an ::sff::WID2 structure.
If a specifc encoding shall be used upon return from the function, this can be selected by setting the member data field fapidxx::WID2container::wasascii or by explicitely calling either fapidxx::WID2container::encodebinary or fapidxx::WID2container::encodeascii.
The standard sequence for writing data with libsff is, to call sff_PrepWid2() first to encode all WID2 data in a WID2 character line. This WID2 string then is passed to the subroutine which is actually writing the data. This is an undesired step for libfapidxx, since WID2 data has to be extracted from the WID2 line again, to be passed as a WID2 struct to libdatrwxx. The step of encoding and decoding WID2 data is not only unnecessary, it can also degrade WID2 data since round-off errors can occur when passing the sampling interval or a mircosecond offset might get lost, since in cannot be represented in the WID2 line format.
libfapidxx uses the following workaround: Store the WID2 struct in binary form in the character sequence of the WID2 line by the mimiciking function sff_prepwid2__().
The WID2 data comprises:
| item | size | total size |
|---|---|---|
| date | 7*4 bytes in libtime++ format | 28 bytes |
| 1 int | 4 bytes | 4 bytes |
| 5 double | 5*4 bytes | 20 bytes |
| character sequences | 18 bytes | |
| station | 5 bytes | |
| channel | 3 bytes | |
| auxid | 4 bytes | |
| instype | 6 bytes | |
| total | 70 bytes |
The WID2 line has a size of 132 characters.
The library actually uses a struct fapidxx::WID2container::WID2struct which uses 82 bytes to store all necessary data.
This concept is provided by fapidxx::WID2container. All WID2 data should be passed only within a WID2container. If WID2 data is received in form of a character sequence it has to be passed to a WID2 container which is able to decode it. All character strings which have to be produced in order to represent the WID2 data should be created by WID2container::encode.
WID2container::WID2struct is used to pass WID2 data internally in binary format. This means that the string created by sff_prepwid2__() is not a character string representation of the WID2 data. It is the memory representation of WID2container::WID2struct struct.
1.8.14