BITSPOOL(5)

NAME
bitspool - format of funetnje(8) spool files

SYNOPSIS
  ASCII-header records with last being "END:"
  Binary body containing records of format:
	<16 bit length> <length worth of bytes>

AVAILABILITY

Systems running funetnje(8) sofware.

DESCRIPTION
Bitspool format consists of an ASCII header, and a binary body containing length-tagged "records". The length-tag is `network byte order' -ordered 16 bit short integer. This is to facilitate transfer of spool files in between systems, and to make it simpler to use non-homogenous hardware in clusters which share the same BITNET node..

Known ASCII headers are:

FRM:  USERNAME@HOSTNAME
    Mandatory (fall-back default: "***@****"). Uppercase-only data in fixed 17 chars wide field, left justified.

TOA:  USERNAME@HOSTNAME
    Mandatory (fall-back default: "POSTMAST@<localname>"). Uppercase-only data in fixed 17 chars wide field, left justified.

FNM:  FILENAME
    Optional, default value: "UNKNOWN". Mixed-case alphanumeric data in fixed 12 chars wide field, left justified.

EXT:  FILEEXTN
    Optional, default value: "DATA". Mixed-case alphanumeric data in fixed 12 chars wide field, left justified.

TYP:  type
    Optional, defaults to "PUNCH". Controls physical device attribute on the outgoing NJE headers. When sending PRINT files, use "TYP: PRINT". When you want to send SYSIN jobs, use "TYP: JOB", and if it is just a PUNCH something, use "TYP: PUNCH". Recognized obsolete keywords: MAIL, BSMTP, FILE, and FASA, which are in reality synonyms for PUNCH, and PASA, which is synonym for PRINT.

CLS:  class
    Optional, defaulted by the TYP: if not defined. This is one (1) uppercase alpha in range A-Z.
    Customary values are: MAIL, BSMTP files: M, NETDATA containing binary data: N, console printouts: O, all others: A.

FOR:  FILEFORM
    Optional, recommended. If you don't want to see file-traversal notes from the network, BITNET style is to start the form name with two characters: "QU". That matches at "QUIET", "QUMAIL", ... System wide default is taken from /etc/funetnje.cf DEFFORM entry, and it often has value STANDARD.

FMT:  spool-format
    Mandatory (fall-back default: BINARY ).
    BINARY for all locally generated files, and for cases where the ASCII headers have been mungled after the file was received from the network.
    EBCDIC denotes spool file which has been received from the network, and contains all possible data blocks in it. (Users will ignore all, but PUNCH, and PRINT records..)

FID:  9900
    Mandatory, sender original spoolid; A number between 1, and 9900. File submitter should put "0000" in there, and delivery facility will do something about it.. When system picks up this field, it will assign there next spoolid from file sender's store, however network delivery uses "OID:", which it assigns..

OID: 0000
    Mandatory, for spool-id allocation at the first time it is queued for delivery to somewhere remote.

TAG:  RSCS-TAG-STRING
    Optional. The IBM NJE TAG string of 136 characters.

DIS:  RSCS-DIST
    Optional. Fixed width, left justified 8 characters field of RSCS DIST information. Default: SYSTEM.

REC:   nnnn
    Highly preferred (almoast mandatory!) Tells the number of records of data; necessary to get job-header right on file transmission, altough not really mandatory for successfull file sending. As the count of records isn't known before all are written (in the usual case), this entry is written at first to reserve space for later seek, and rewite with correct information.

JNM: JOBNAME
    Optional. Contains NJE job name (8 characters).

PRT:  prtfiles@tonode
    Optional. For SYSIN jobs this defines alternate address for sending the job PRINT outputs to. Default is taken from "FRM:".

PUN:  punfiles@tonode
    Optional. For SYSIN jobs this defines alternate address for sending the job PUNCH outputs to. Default is taken from "FRM:".

END:
    Mandatory. Ends the ASCII portion of the headers. Terminating newline must be immediately after the colon character.

With all (except END:) above header tags there must be exactly one space (ascii 32) after the colon, and before data. With the END: there must not be any extra blanks after the colon, and before terminating newline.

Order of the ASCII format headers is not fixed, except that END: must be last.

Binary format data follows syntax:

    <16-bit length> <length number of bytes>

where the <16-bit length> is encoded as network-byte-order short integer. This is to facilitate easy copying of funetnje(8) spool files from one machine to another. This also makes it possible to share common BITNET spool between several machines independent of their native byte order.

Sample data formats:

PUNCH (any content, like plain text, and NETDATA)

 0x80, 80,                          0x80 = PUNCH, 80=content length
 <80 bytes of EBCDIC/whatever>      The PUNCH content, 80 bytes

PRINT Machine Carriage Control:

 0x90, 132, MCCbyte,                0x90 = PRINT MCC, 132=content length
 <132 bytes of EBCDIC/whatever>     The PRINT content, 132 bytes

PRINT ASA Carriage Control:

 0xA0, 132, ASAbyte,                0xA0 = PRINT ASA, 132=content length
 <132 bytes of EBCDIC/whatever>     The PRINT content, 132 bytes

PRINT CPDS Carriage Control:

 0xB0, 132, CPDSbyte,               0xB0 = PRINT CPDS, 132=content length
 <132 bytes of EBCDIC/whatever>     The PRINT content, 132 bytes

Trailing EBCDIC spaces can be suppressed in the spool files, thus above are given ranges of lengths. If the record content is shorter than its defined size, receiver must pad it with EBCDIC spaces. (Of course, this way spool-size of a megabyte of spaces will be 13108 records of (2+)2 bytes + header, which makes circa 53kB. When received, it will expand by a fractionally filled last record.) The length-byte at each record must be of its nominal value, record truncation is coded with the 16-bit-length value.

The MCCbyte, and ASAbyte are two kinds of carriage control mechanisms. The CPDSbyte is third kind, however documenting it is left for further study.

IBM printers are fixed 132 characters wide, and on overall those systems function on records, and a write in this respect means write of whole line. On overall the IO-operations on IBM mainframe happen on records, or preferrably chains of records on which single start-IO instruction can be used to start the IO-channel.

Carriage-control mechanisms contain two kinds of controls, both pre-write, and post-write controls exist in MCC mode. In ASA-mode only pre-writes are defined. Pre-write controls happen before the printout line is written, for example `jump to nearest VFU channel 1 forward' (in plain english: Form-Feed..)

Jump to next page
    ASA: `1', Pre-MCC: X'8B'

Overwrite
    Defined only in pre-write. ASA: `+', MCC: X'01'

Write and advance one line
    ASA: Space, Pre-MCC: X'0B', Post-MCC: X'09'

Write and advance two lines
    ASA: `0', Pre-MCC: X'13', Post-MCC: X'11'

Write and advance three lines
    ASA: `-', Pre-MCC: X'1B', Post-MCC: X'19'

SEE ALSO
bitsend(1), bmail(8), funetnje(8), qrdr(8), receive(1), sendfile(1)

NOTES

Other formats, than 0x80, 0x90, 0xA0, 0xB0 of binary portion records should be ignored. (Received network transport layer headers are there, etc.)

AUTHORS

Yehavi Bourvine, Hebrew University of Yerusalem, Israel <yehavi@hujivms.bitnet>.

Matti Aarnio, Finnish University and Research Network - FUNET <mea@nic.funet.fi> <mea@finfiles.bitnet>.

Original (VMS oriented package) software by Yehavi Bourvine, UNIX features including spool mechanism, plenty of other modifications, man-pages by Matti Aarnio.