PREV UP next The Ftape Tools Manual - API


8.4.2.4: Creating new entries and modifying certain fields.

Library Function: int ftvt_add_volume (ftvt *VOLUMES, int NUM_VOLUMES)

Nearly a dummy function. Checks whether one additional volume entry would fit into the volume table and set the format code of the entry. All other fields are uninitialised.

Arguments
const ftvt *VOLUMES

The libraries volume table representation. This must be the same pointer as given to ftvt_read().


int NUM_VOLUMES

The number of volumes as returned by ftvt_read() or a previous call to ftvt_add_volume().


Return Value

The new number of volumes (i.e. NUM_VOLUMES + 1), or -1 if no more volumes would fit into the volume table.


Side effects

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error message is generated by ftvt_add_volume().Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Too many volumes: NUM_VOLUMES (MAX_VOLUMES max)

The new number of volumes would exceed the number of volumes which fit into the volume table segment.


Example
if ((num_volumes = ftvt_add_volume(volumes, num_volumes)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_add_volume() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}
Library Function: char * ftvt_decode_date (u_int32_t TIMESTAMP)

Decode the date stored in timestamp in the format described in the various QIC-something standards. This is year 2000 proof, but will overflow in year 2097 :-)

Arguments
u_int32_t TIMESTAMP

Time stamp in the format described in the various QIC standards (QIC Home Page).


Return Value

The date and time in the %T %D format. See Formatting Date and Time (info file libc) or `man 3 strftime'.

Note that this way the year gets only two digits. It is clear, however, that `01' means `2001' and not `1901'. Ambiguities will appear in the year 2070, however. But I don't care :-)

Note that the return value is a pointer to a statically allocated storage area.


Side effects

None.


Diagnostics

The string invalid (or its translations into the various languages supported by the ftape-tools library) is return if the date given in TIMESTAMP is not a valid QIC time stamp.


Example
const char *date = ftvt_decode_date(0x01ea6dff);

This should yield `23:59:59 12/31/70'.

Library Function: int ftvt_set_date (ftvt *VOLUMES, int MAXNUM, const char *DATE, int VTBL_NO)

Set the date field of the given volume table entry.

Arguments
ftvt *VOLUMES

Pointer to the libraries volume table representation.


int MAXNUM,

Number of entries in VOLUMES (as returned by ftvt_read() or ftvt_add_volume().


const char *DATE

A date string in the `%T %D' format. See Formatting Date and Time (info file libc) or `man 3 strftime'. This seems to not be year 2000 proof, however, it will work until 2070.


int VTBL_NO

The number of the volume table entry to modify, i.e. the index into VOLUMES.


Return Value

-1 on error 0 otherwise.


Side effects

The volume table entry modified by this function is flagged `dirty' and this will be written to tape if ftvt_write() is called.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error message is generated by ftvt_set_date(). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Volume number too big or negative: VTBL_NO

Self-explanatory.


Example
if (ftvt_set_date(volumes, maxnum, "23:59:59 12/31/70", 1)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_set_date() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}
Library Function: int ftvt_set_label (ftvt *VOLUMES, int MAXNUM, const char *DESC, int VTBL_NO)

Set the label field of the given volume table entry.

Arguments
ftvt *VOLUMES

Pointer to the libraries volume table representation.


int MAXNUM

Number of entries in VOLUMES (as returned by ftvt_read() or ftvt_add_volume().


const char *DESC

The new '\0' terminated volume label. The function truncates the label to 44 bytes, or fills the label with spaces if too short (according to QIC standards).


int VTBL_NO)

The number of the volume table entry to modify, i.e. the index into VOLUMES.


Return Value

-1 on error 0 otherwise.


Side effects

The volume table entry modified by this function is flagged `dirty' and this will be written to tape if ftvt_write() is called.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error message is generated by ftvt_set_label(). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Volume number too big or negative: VTBL_NO

Self-explanatory.


Example
if (ftvt_set_label(volumes, maxnum, "Bugs Bunny", 1)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_set_label() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}
Library Function: int ftvt_set_bounds (ftvt *VOLUMES, int MAXNUM, int START, int END, int VTBL_NO)

Set the segment bounds for a given volume table entry.

Arguments
ftvt *VOLUMES

Pointer to the libraries volume table representation.


int MAXNUM

Number of entries in VOLUMES (as returned by ftvt_read() or ftvt_add_volume().


int START
int END

Start and end segments for this volume. The function performs some range checking against the dimensions of the inserted cartridge, but does not check for overlapping volumes.


int VTBL_NO)

The number of the volume table entry to modify, i.e. the index into VOLUMES.


Return Value

-1 on error 0 otherwise.


Side effects

The volume table entry modified by this function is flagged `dirty' and this will be written to tape if ftvt_write() is called.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error messages are generated by ftvt_set_label(). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Volume number too big or negative: VTBL_NO

Self-explanatory.


Start segment (START) should be less than end segment (END)

Self-explanatory.


End segment (END) must be less than LAST_DATA_SEGMENT

Obviously, END should be less or equal than the last segment of this cartridge.


Example
if (ftvt_set_bounds(volumes, maxnum, 11, 12, 1)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_set_bounds() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}
Library Function: int ftvt_set_id (ftvt *VOLUMES, int MAXNUM, const char *ID, int VTBL_NO)

Set the volume entry ID.

Arguments
ftvt *VOLUMES

Pointer to the libraries volume table representation.


int MAXNUM

Number of entries in VOLUMES (as returned by ftvt_read() or ftvt_add_volume().


const char *ID

The id-string of the volume table entry. Should be one of "VTBL", "XTBL", "UTID" or "EXVT", according QIC standards (QIC Home Page).

ID must be a '\0' terminated four byte string.


int VTBL_NO)

The number of the volume table entry to modify, i.e. the index into VOLUMES.


Return Value

-1 on error 0 otherwise.


Side effects

The volume table entry modified by this function is flagged `dirty' and this will be written to tape if ftvt_write() is called.

In case of an error an error string is generated and remembered. It can be retrieved by a call to ftvt_get_ctrl(). See Option Settings.


Diagnostics

The following error message is generated by ftvt_set_id(). Note that libftvt has native language support, so the actual message might differ from the messages below depending on your `locale' setting.

Volume number too big or negative: VTBL_NO

Self-explanatory.


Volume ID must consist of exactly four characters

Self-explanatory.


Example
if (ftvt_set_id(volumes, maxnum, "VTBL", 1)) == -1) {
        struct ftvt_ctrl *info = ftvt_get_ctrl();

        fprintf(stderr, "ftvt_set_id() failed: %s\n", info->errstr);

        (void)ftvt_close(tapefd);
        exit(1);
}

ftape logo Use these buttons to jump to the top menu

TOP (previous node) TOP (parent node) TOP (next node) TOP (this node)