NAME

D64::Disk::BAM - Processing the BAM (Block Availability Map) area of the Commodore disk images (D64 format only)

SYNOPSIS

use D64::Disk::BAM;

# Create new empty BAM object:
my $diskBAM = D64::Disk::BAM->new();

# Create new BAM object based on the BAM sector data retrieved from a D64 disk image file:
my $diskBAM = D64::Disk::BAM->new($sector_data);

# Get the BAM sector data:
my $sector_data = $diskBAM->get_bam_data();

# Clear the entire BAM sector data:
$diskBAM->clear_bam();

# Get disk name converted to an ASCII string:
my $to_ascii = 1;
my $disk_name = $diskBAM->disk_name($to_ascii);

# Set disk name converted from an ASCII string:
my $to_petscii = 1;
$diskBAM->disk_name($to_petscii, $disk_name);

# Get full disk ID converted to an ASCII string:
my $to_ascii = 1;
my $full_disk_id = $diskBAM->full_disk_id($to_ascii);

# Set full disk ID converted from an ASCII string:
my $to_petscii = 1;
$diskBAM->full_disk_id($to_petscii, $full_disk_id);

# Get the number of free sectors on the specified track:
my $num_free_sectors = $diskBAM->num_free_sectors($track);

# Check if the sector is used:
my $is_sector_used = $diskBAM->sector_used($track, $sector);

# Set specific sector to allocated:
$diskBAM->sector_used($track, $sector, 1);

# Check if the sector is free:
my $is_sector_free = $diskBAM->sector_free($track, $sector);

# Set specific sector to deallocated:
$diskBAM->sector_free($track, $sector, 1);

# Write BAM layout textual representation to a file handle:
$diskBAM->print_out_bam_layout($fh);

# Print out formatted disk header line to a file handle:
$diskBAM->print_out_disk_header($fh);

# Print out number of free blocks line to a file handle:
$diskBAM->print_out_blocks_free($fh);

DESCRIPTION

Sector 0 of the directory track contains the BAM (Block Availability Map) and disk name/ID. This package provides the complete set of methods essential for accessing, managing and manipulating the contents of the BAM area of the Commodore disk images (note that only D64 format is supported).

METHODS

new

Create new empty BAM object:

my $diskBAM = D64::Disk::BAM->new();

Create new BAM object based on the BAM sector data:

my $diskBAM = D64::Disk::BAM->new($sector_data);
my $diskBAM = D64::Disk::BAM->new(@sector_data);

Upon failure an undefined value is returned.

Be careful providing the right sector input data. $sector_data is expected to be the stream of bytes. @sector_data is expected to be the list of single bytes (not the numeric byte values!).

clear_bam

Clear the entire BAM sector data:

$diskBAM->clear_bam();

directory_first_track

Get/set track location of the first directory sector (in theory it should be always set to 18, but it actually doesn't matter, and you should never trust what is here, you always use track/sector 18/1 for the first directory entry):

$diskBAM->directory_first_track($directory_first_track);
my $directory_first_track = $diskBAM->directory_first_track();

directory_first_sector

Get/set sector location of the first directory sector (in theory it should be always set to 1, but it actually doesn't matter, and you should never trust what is here, you always use track/sector 18/1 for the first directory entry):

$diskBAM->directory_first_sector($directory_first_sector);
my $directory_first_sector = $diskBAM->directory_first_sector();

dos_version_type

Get/set disk DOS version type:

$diskBAM->dos_version_type($dos_version_type);
my $dos_version_type = $diskBAM->dos_version_type();

When this byte is set to anything else than $41 or $00, we have what is called "soft write protection", thus any attempt to write to the disk will return the "DOS Version" error code 73, "CBM DOS V2.6 1541".

get_bam_data

Get the BAM sector data:

my $sector_data = $diskBAM->get_bam_data();
my @sector_data = $diskBAM->get_bam_data();

Depending on the context, either a reference or an array of bytes is returned.

disk_name

Get disk name:

my $disk_name = $diskBAM->disk_name($to_ascii);

The first input parameter indicates whether value returned should get converted to an ASCII string upon retrieval:

A false value defaults to the original 16-bytes long PETSCII string padded with $A0
A true value enforces conversion of the original data to an ASCII string

Set disk name:

$diskBAM->disk_name($to_petscii, $disk_name);

The first input parameter indicates whether $disk_name parameter should get converted to a PETSCII string before storing:

A false value indicates that $disk_name has already been converted to a 16-bytes long PETSCII string and padded with $A0
A true value enforces conversion of the original data to a valid PETSCII string

Make sure that you either provide a valid PETSCII stream of bytes or use this option to get your original ASCII string properly converted.

The second input parameter provides the actual disk name to be written to the BAM sector data.

disk_id

Get disk ID:

my $disk_id = $diskBAM->disk_id($to_ascii);

The first input parameter indicates whether value returned should get converted to an ASCII string upon retrieval:

A false value defaults to the original 2-bytes long PETSCII string padded with $A0
A true value enforces conversion of the original data to an ASCII string

Set disk ID:

$diskBAM->disk_id($to_petscii, $disk_id);

The first input parameter indicates whether $disk_id parameter should get converted to a PETSCII string before storing:

A false value indicates that $disk_id has already been converted to a 2-bytes long PETSCII string and padded with $A0
A true value enforces conversion of the original data to a valid PETSCII string

Make sure that you either provide a valid PETSCII stream of bytes or use this option to get your original ASCII string properly converted.

The second input parameter provides the actual disk ID to be written to the BAM sector data.

full_disk_id

Get full disk ID:

my $full_disk_id = $diskBAM->full_disk_id($to_ascii);

The first input parameter indicates whether value returned should get converted to an ASCII string upon retrieval:

A false value defaults to the original 5-bytes long PETSCII string padded with $A0
A true value enforces conversion of the original data to an ASCII string

Set full disk ID:

$diskBAM->full_disk_id($to_petscii, $full_disk_id);

The first input parameter indicates whether $full_disk_id parameter should get converted to a PETSCII string before storing:

A false value indicates that $full_disk_id has already been converted to a 5-bytes long PETSCII string and padded with $A0
A true value enforces conversion of the original data to a valid PETSCII string

Make sure that you either provide a valid PETSCII stream of bytes or use this option to get your original ASCII string properly converted.

The second input parameter provides the actual full disk ID to be written to the BAM sector data.

dos_type

Get DOS type:

my $dos_type = $diskBAM->dos_type($to_ascii);

The first input parameter indicates whether value returned should get converted to an ASCII string upon retrieval:

A false value defaults to the original 2-bytes long PETSCII string padded with $A0
A true value enforces conversion of the original data to an ASCII string

Set DOS type:

$diskBAM->dos_type($to_petscii, $dos_type);

The first input parameter indicates whether $dos_type parameter should get converted to a PETSCII string before storing:

A false value indicates that $dos_type has already been converted to a 2-bytes long PETSCII string and padded with $A0
A true value enforces conversion of the original data to a valid PETSCII string

Make sure that you either provide a valid PETSCII stream of bytes or use this option to get your original ASCII string properly converted.

The second input parameter provides the actual DOS type to be written to the BAM sector data.

num_free_sectors

Get the number of free sectors on an entire disk:

my $num_free_sectors = $diskBAM->num_free_sectors('all');

Get the number of free sectors on the specified track:

my $num_free_sectors = $diskBAM->num_free_sectors($track);

When successful the number of free sectors on that track will be returned.

Returns an undefined value if invalid track number has been provided.

sector_used

Check if the sector is used:

my $is_sector_used = $diskBAM->sector_used($track, $sector);

True value indicates that the sector is used, false value states that the sector is free.

Set specific sector to allocated:

$diskBAM->sector_used($track, $sector, 1);

Remove allocation from sector:

$diskBAM->sector_used($track, $sector, 0);

sector_free

Check if the sector is free:

my $is_sector_free = $diskBAM->sector_free($track, $sector);

True value indicates that the sector is free, false value states that the sector is used.

Set specific sector to deallocated:

$diskBAM->sector_free($track, $sector, 1);

Remove sector from the list of empty sectors:

$diskBAM->sector_free($track, $sector, 0);

print_out_bam_layout

Write BAM layout textual representation to a file handle:

$diskBAM->print_out_bam_layout($fh);

$fh is expected to be an opened file handle that BAM layout's textual representation may be written to.

print_out_disk_header

Print out formatted disk header line to a file handle:

$diskBAM->print_out_disk_header($fh, $as_petscii);

fh defaults to the standard output. as_petscii defaults to false (meaning that ASCII characters will be printed out by default).

print_out_blocks_free

Print out number of free blocks line to a file handle:

$diskBAM->print_out_blocks_free($fh, $as_petscii);

fh defaults to the standard output. as_petscii defaults to false (meaning that ASCII characters will be printed out by default).

BUGS

There are no known bugs at the moment. Please report any bugs or feature requests.

CAVEATS

There are some variations of the BAM layout, these are however not covered (yet!) by this module:

DOLPHIN DOS 40-track extended format (track 36-40 BAM entries)
SPEED DOS 40-track extended format (track 36-40 BAM entries)

The BAM entries for SPEED, DOLPHIN and ProLogic DOS use the same layout as standard BAM entries, hence should be relatively easy to get implemented. Extended versions of this package may appear or they might as well get supported through other modules by the means of inheritance.

EXPORT

None. No method is exported into the caller's namespace either by default or explicitly.

AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

VERSION

Version 0.05 (2021-01-16)

COPYRIGHT AND LICENSE

This library is free open source software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

PLEASE NOTE THAT IT COMES WITHOUT A WARRANTY OF ANY KIND!

To install D64::Disk::BAM, copy and paste the appropriate command in to your terminal.

cpanm

cpanm D64::Disk::BAM

CPAN shell

perl -MCPAN -e shell
install D64::Disk::BAM

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

new

clear_bam

directory_first_track

directory_first_sector

dos_version_type

get_bam_data

disk_name

disk_id

full_disk_id

dos_type

num_free_sectors

sector_used

sector_free

print_out_bam_layout

print_out_disk_header

print_out_blocks_free

BUGS

CAVEATS

EXPORT

AUTHOR

VERSION

COPYRIGHT AND LICENSE

Module Install Instructions