.\" bsc.1 by Neil Parker -- 17 Dec 1992
.\" bsc version 1.2
.TH BSC 1 "Dec. 17, 1992"
.SH NAME
bsc \- Encode a file in the BinSCII format for transmittion to an Apple II
.SH SYNOPSIS
.B bsc
.RB [ \-t
.IR type ]
.RB [ \-a
.IR auxtype ]
.RB [ "\-m dnbiwr" ]
.RB [ \-n
.IR name ]
.RB [ \-s
.IR num ]
.RB [ \-o
.IR outfile ]
.RB [ \-h ]
.I filename
.SH DESCRIPTION
.I Bsc
encodes a file in the
.I BinSCII
format, which is an ASCII-only format similar to
.IR uuencode (1),
and which is suitable for transmittion through text-only communication
channels such as electronic mail and brain-dead terminal servers.  The
.I BinSCII
format originated on the Apple II family of microcomputers (hence the
references to the Apple II ProDOS operating system below), and can be
decoded by the
.I BINSCII
program on an Apple II (there is also a
.I BinSCII
decoder for UNIX called
.IR sciibin ).
.SS Options
.TP
.BI \-t " type"
Sets the ProDOS filetype stored in the
.I BinSCII
header to
.IR type .
The type may be specified as a standard 3-letter ProDOS file type
abbreviation (in lowercase), or as a decimal, octal, or hexadecimal number
in one of the following formats:
.RS
.TP "\w'0xdd\ \ 'u"
.I ddd
A decimal number
.RI ( d
is a decimal digit, in the range 0-9).
.PD 0
.TP
.BI $ dd
A hexadecimal number
.RI ( d
is a digit in the range 0-9 or a-f).  Note that you will have to quote or
escape the $ to protect it from the shell.
.TP
.BI 0x dd
A hexadecimal number
.RI ( d
is a hexedecimal digit as in the previous case).
.TP
.BI 0 dd
An octal number
.RI ( d
is a digit in the range 0-7).
.PD
.RE
.IP
If no
.B \-t
option is present, the ProDOS file type will default to 6 (BIN).
.TP
.BI \-a " auxtype"
Sets the ProDOS auxiliary filetype in the
.I BinSCII
header to
.IR auxtype .
The auxiliary type may be specified in decimal, hexadecimal, or octal,
using the same syntax as the
.B \-t
option above.  If no
.B \-a
option is present, the auxiliary type will default to 0.
.TP
.B "\-m dnbiwr"
Sets the ProDOS file access mode.  The mode may consists of one or more of
the following letters:
.RS
.TP "\w'd\ \ 'u"
.B d
File can be destroyed.
.PD 0
.TP
.B n
File can be renamed.
.TP
.B b
File needs backup.
.TP
.B i
File is invisible.
.TP
.B w
File can be opened for writing.
.TP
.B r
File can be opened for reading.
.PD
.RE
.IP
If no
.B \-m
option is specified, the access mode defaults to
.IR dnwr ,
which corresponds to an "unlocked" ProDOS file.  To create a "locked"
ProDOS file, specify a mode of
.IR r .
.TP
.BI \-n " name"
Sets the ProDOS filename stored in the
.I BinSCII
header.  If this option is omitted, the ProDOS filename will be the same as
the UNIX filename.
.TP
.BI \-s " num"
Sets the number of
.I BinSCII
segments per output file to
.IR num .
As with the
.B \-t
and
.B \-a
options, the number may be specified in decimal, hexadecimal, or octal.  If
no
.B \-s
option is present, or if
.I num
is 0, then all
.I BinSCII
segments will be written to a single output file.  To cause each segment to
go into its own output file (like the Apple II
.I BINSCII
program), set
.I num
equal to 1.  See below for an explanation of output files.
.TP
.BI \-o " outfile"
Normally, the output of
.I bsc
is stored in files whose names are derived from the name of the input file.
This option makes
.I bsc
derive its output file names from the name
.I outfile
instead.
.TP
.B \-h
Print a short summary of
.IR bsc 's
output options on the standard output.
.PP
These options, if present, may appear in any order, provided that they
appear before the filename.  Spaces may appear between an option letter
and its value, but are not necessary.
.PP
The
.I filename
is the name of the UNIX file to be BinSCII'd.  The stored
ProDOS filename will be taken from the UNIX name, or from the
.B \-n
option if
one was supplied, with lowercase letters converted to uppercase.
Additionally, characters that are not valid in ProDOS filenames will be
translated into periods (unless the invalid character is the first
character in the name, in which case it gets translated into an "X").  The
ProDOS name will be truncated to 15 characters if necessary.
.PP
The stored ProDOS creation and modification times will be taken from the
UNIX input file.
.PP
The output of bsc is a set of one or more files, each containing one or
more BinSCII segments.  By default, all BinSCII segments are written to
a single output file, which has the same name as the input file with a
".0" appended to the end.  If the
.B \-s
option is given on the command
line with a value greater than zero, then the number of segments per
output file will be limited to the specified value, and if more than one
output file is needed, the second file will have ".1" appended to the
name, the third will have ".2" appended, and so forth.  For example, if
"foo" is a large UNIX file, the command "bsc -s3 foo" will create files
"foo.0", "foo.1", "foo.2", etc., each containing 3 BinSCII segments.
.PP
If the
.B \-o
option is given on the command line, then the
.B \-o
name will be used for the output files instead of the input filename.  The
output files will still have ".0", ".1", ".2", etc., appended to their
names.
.PP
.I Bsc
will refuse to
.I BinSCII
a file larger than 16777216 bytes (16 meg),
since that is the maximum size of a ProDOS file.
.SH EXAMPLE
Suppose a UNIX file called "picture" contains a standard
Apple IIGS super-hires screen image.  The command
.IP
bsc \-tpic picture
.PP
will create the file "picture.0" in a format suitable for downloading to
an Apple II and
.RI un- BinSCII ing,
or for posting to comp.binaries.apple2.
When
.RI un- BinSCII 'd
on an Apple II, it will automatically be converted to
a PIC ($C1) file.
.SH "SEE ALSO"
.IR uuencode (1),
.IR binscii (5)
.SH BUGS
If a file with the same name as a
.I bsc
output file already exists, then the pre-existing file will be silently
overwritten by the
.I bsc
output file.  Before typing "bsc foo", it's a good idea to make sure you
don't already have an important data file called "foo.0".
.PP
If you find any bugs is
.BR bsc ,
send e-mail to one of the addresses
below.  I welcome bug reports, comments, complaints, and suggestions for
improvement.
.RI ( Please
send me your bug reports \- don't just sit on it and hope it will magically
get better.  I can't fix it if I don't know it's broken!)
.SH AUTHOR
Neil Parker
.br
(nparker@cie.uoregon.edu, parker@corona.uoregon.edu)
.PP
Thanks to Marcel J. E. Mol, whose
.I sciibin
program was a valuable source
of technical information on
.IR BinSCII .