BHCS File and record formats

The following are the file and record formats used by the Barr Host Communications Suite. Click the following links for descriptions of the formats.

See also:


.tnj, .bnj, .anj, .xnj, .lnj formats

These formats are used internally by Barr Systems and are subject to change without notification.

When in the Barr spooler, the Barr host formats (.tnj, .bnj, .anj, .xnj, and .lnj) have the same basic layout. The only difference is the data they contain. Text (EBCDIC) jobs are labeled .tnj, binary jobs are labeled .bnj, AFP jobs are labeled .anj, Xerox Metacode jobs are labeled .xnj, and Xerox LCDS Acronym for Line Condition Data Stream. An LCDS print job or print file is line data (text) with some text-based Xerox commands included, such as DJDE commands. jobs are labeled .lnj. The "nj" represents "NJE-wrapped," which means the individual records are formatted similar to the way records are formatted in the NJE protocol. Our records are stored in a subset of the NJE format consisting of data, logical record length (LRECL) bytes (including trailing blanks), record length (RECL) bytes, and a sub-record control byte (SRCB).

You can click in the Data Type column and change the file format.

To view the records:

  1. Add the Data Type column to the Spool Window.

  2. If the data type is .tnj or .bnj, open the file with the Viewer utility. If the data type is .anj, you must open the file using a hexadecimal editor.

  1. On the menu bar, select View | Binary | EBCDIC. Use the examples and following table to interpret the record.

Unspanned record structure:

Spanned record structure (first segment):

SEGL = amount of data bytes + 2 bytes (LRECL bytes)

For more information, see IBM's Network Job Entry Formats and Protocols manual.

Entry

Description

SRCB

Sub-record control byte. The SRCB is a bit field composed of two bits. Use the following table to interpret the bits found in the SRCB.

8x

No carriage control

9x

Machine carriage control

Ax

ASA carriage control

Bx

CPDS Acronym for Composed Page Data Stream. The carriage control typically used with AFP data stream records coming from an NJE host. page mode records

x0

Standard record (not spanned)

x8

First segment of a spanned record

x4

Middle segment of a spanned record

xC

Last segment of a spanned record

An SRCB of 90 is interpreted as follows: the 9 indicates machine carriage control, and the 0 indicates the record is not spanned.

You can also interpret the SRCB by converting it to binary and using the following guidelines.

The first set of bits indicates the carriage control type.

The second set of bits indicates if the record is spanned or unspanned. If the record is spanned, it indicates the segment of the spanned record.

An SRCB of 90 translates to 10010000. The third and fourth characters, 01, indicate machine carriage control, and the fifth and sixth characters, 00, indicate the record is not spanned.

RECL

Record length bytes. The record length specifies how many data bytes follow in the record.

LRECL

Logical record length bytes. If trailing spaces have been truncated The beginning or end of a series of characters or numbers are cut off. Unlike rounding, a number shortening process where the rightmost digit may be increased, truncation involves only eliminating numbers and characters., the logical record length indicates how large the record will be when those spaces have been added back to the end of the record. The difference between RECL and LRECL indicates how many blanks have been truncated.

SEGL

Segment length bytes.

LSEGL

Logical segment length bytes. This includes trailing blanks, but does not include the 2 LRECL length bytes.

Data

Record data. If the carriage control bits indicate that the record contains carriage control, the first data byte is the carriage control byte.

Spanned record support allows records larger than 255 bytes to be segmented into smaller records. The spanned record bits indicate whether the record is unspanned or part of a larger spanned record. The first segment of a spanned record has a slightly different format than an unspanned record. The middle and last segments have the same format as an unspanned record, except carriage control bytes are not possible. If the total length of the entire spanned record is not filled by the segments, the remaining bytes are padded with spaces.

Unspanned record example:

A0

04

06

F1

C1

C2

C3

The SRCB A0 indicates this is an unspanned record with ASA carriage control (of F1 skip to channel 1). The RECL 04 indicates the record length is 4 bytes. The LRECL 06 indicates the record length will be 6 once the trailing spaces are added back to the end of the record. (This record contains 2 trailing spaces.) The first data byte, F1, is the carriage control type followed by the data "ABC".

Spanned record example:

98

07

05

00

10

89

F1

F2

F3

F4

94

07

07

F5

F6

F7

F8

F9

F0

F1

9C

04

04

F2

F3

F4

F5

 

 

 

The first record is the first segment of a spanned record. The SRCB 98 indicates this is a spanned record with machine carriage control (of 89 skip to channel 1). The total record size is 16 bytes. The LRECL in each segment indicates the bytes contained in that segment. The LRECL in the first segment is 05, indicating it contains 5 of the 16 bytes. The LRECL in the second segment is 07, indicating it contains 7 bytes. The LRECL in the last segment is 04 indicating it contains 4 bytes. The first data byte, 89, is the carriage control type followed by the data "123456789012345". Typically, you would not span a 16-byte record across 3 records, it is shown here for simplicity.

Barr Archive format version 1

Lengths are encoded in big endian Storing numbers in such a way that the most significant byte is placed first. format.

SIGNATURE BLOCK

##BARR## Barr Data File VXX.XX ....... ##\x01a\1\1

Identifies the stream that follows as having the Barr Archive format version 1.

JOB HEADER BLOCK

4 bytes

Entire Job length (currently unsupported, set to zero)

1 byte

Version ID (in binary form)

11 bytes

Reserved (unused - reserved for future use)

4 bytes

Job Header length
Job Header data

DATA SET BLOCK

4 bytes

Data set Header length
Data set Header data

4 bytes

FCB length
FCB data

4 bytes

Overlay1 length
Overlay1 data

4 bytes

Overlay2 length
Overlay2 data

4 bytes

Miscellaneous Section A length (repeats until zero)

 

Miscellaneous Section A data
There can be any number of Miscellaneous Sections.
The end-of-Miscellaneous-Sections is indicated by a Miscellaneous Section length of zero.

4 bytes

Data set length (currently unsupported so this length is zero)

12 bytes

Reserved (unused - reserved for future use)

16 bytes

Match GUID
This is will be used as the data set terminator.

 

Data set data
Because the data set length is unknown until after the data set transmission finishes, the data set is terminated by the search GUID placed at a 1-Kb boundary.

 

Padding zeros
The data set is padded with zeros up to the next 1 Kb boundary.

16 bytes

Match GUID
A data set is terminated when the match GUID appears at a 1 Kb boundary. This is measured from the first byte of the data set data.

4 bytes

Padding length
The byte count for the previous zero padded section.
This indicates the amount of the last 1-Kb data set section that is not a part of the data set.

4 bytes

Overlay3 length
Overlay3 data

4 bytes

Overlay4 length
Overlay4 data

4 bytes

Miscellaneous Section B length (repeats until zero)

 

Miscellaneous Section B data
There can be any number of Miscellaneous Sections.
The end-of-Miscellaneous-Sections is indicated by a Miscellaneous Section length of zero.

if (next 4 byte length > 0) loopback A testing procedure in which transmitted data is returned as received data. to DATA SET BLOCK

 

If another data set follows the immediately preceding data set, this length will be greater than zero. Go to DATA SET BLOCK and process the next data set.

 

If there is NOT another data set following the immediately preceding data set, fall through to the next block and process the TRAILER BLOCK.

TRAILER BLOCK

4 bytes

Zero value
A zero here indicates there are no more DATA SET BLOCKs.

4 bytes

Job Trailer length
Job Trailer data

4 bytes

Zero value
A zero here indicates that no more sections follow.
Non-zero values are ignored.

Barr Archive format version 2

Record lengths are encoded in big endian Storing numbers in such a way that the most significant byte is placed first. format.

Record format

Each tagged record in a Barr Archive Version 2 file begins with a 4 byte tag name that identifies the record type, followed by a 4-byte record length, followed by the data associated with the record.

The OPEN, CLOS, DS_z, and OL_z record types always have a zero record length. This causes the next record to start immediately after their record length part. The Signature Record is always the first record in the file and has an assumed length of 36 bytes. There is no record length part in the Signature Record so the next record starts immediately after the last byte of the Signature Record.

The following is an alphabetical list of record name tags.

BL

Leading Banner

BT

Trailing Banner

CLOS

Close output file

DH

Data set Header

DS

Data set

DS_z

Data set End

FCB

Forms Control Buffer

JH

Job Header

JT

Job Trailer

OL1

Overlay 1

OL2

Overlay 2

OL4

Overlay 4

OL_z

Overlay End

OPEN

Open output file

##BARR## Barr Data File V02.00 ##\x1A\x01\x01	(Signature Record)

 

The 36 byte Signature Record identifies the file as originating from Barr Host Communications Suite. This Signature Record identifies the following stream as having the Barr Archive Format Version 2.

Banners

Leading Banner and Trailing Banner records are optional. Banners consist of a single record.

Data sets

Data sets can consist of multiple DS records. Each DS record is concatenated To join sequentially (for example, joining the characters in a character string). to the current data set. The end of a data set is marked by the DS_z data set End tag.

FCBs

Forms Control Buffers are optional. An FCB consists of a single record. Only data sets of the "NJE-wrapped EBCDIC text" type are compatible with FCBs. Other types of data sets will not have FCBs present in their files. Data sets of unknown type are assumed to be of the "NJE-wrapped EBCDIC text" type and therefore can include FCB records.

Overlays

Overlay records are optional. Overlays can consist of more than one record, so the first OL1 tag (or OL2 or OL4) can be followed by another OL1 tag for the same data set. Each overlay record is concatenated to the current overlay. The end of an overlay is marked by the OL_z (Overlay End) tag. The OL3 tag is currently not used.

The fourth byte of an Overlay tag name can be A, B, N, or T. These letters indicate the type of the original overlay, as in the following table:

A

.asc - ASCII

B

.bin - Binary

N

.bnj - NJE-wrapped Binary

T

.tnj - NJE-wrapped EBCDIC text

An overlay tag with the value OL1T indicates that Overlay 1 is NJE-wrapped EBCDIC text. When the fourth character of an overlay tag is the space character, the Overlay is of an unknown type.

Sequenced list of records. A file created with the Archive Version 2 format will have sections in the following order:

##BARR## Barr Data File V02.00 ##\x1A\x01\x01 (This is the signature.)

JH

Job Header

DH

1st Data set Header

FCB

1st Forms Control Buffer

OPEN

Open output file

OL1

Overlay 1

OL_z

Overlay 1 end tag

BL

Leading Banner

OL2

Overlay 2

OL_z

Overlay 2 end tag

DS

1st Data set

DS_z

1st Data set End

DH

2nd Data set Header

FCB

2nd Forms Control Buffer

DS

2nd Data set (part 1)

DS

2nd Data set (part 2)

.

(parts for the 2nd data set continue to appear until the data set is complete)

.

 

.

 

DS

2nd Data set (part K)

DS

2nd Data set End

DH

3rd Data set Header

FCB

3rd Forms Control Buffer

DS

3rd Data set

DS

3rd Data set End

.

(DH, FCB, DS, and DS_z sections appear for each data set in the Job)

.

 

.

 

.

 

DH

Nth Data set Header

FCB

Nth Forms Control Buffer

DS

Nth Data set

DS_z

Nth Data set End

BT

Trailing Banner

OL4

Overlay 4 (part 1)

OL4

Overlay 4 (part 2)

.

(parts for the 4th Overlay continue to appear until the Overlay is complete)

.

 

.

 

OL4

(Lth part for the 4th Overlay)

OL_z

Overlay 4 end tag

JT

Job Trailer

CLOS

Close output file

VBM format

VBM is a block variable format similar to the mainframe format RECFM=VBM. The blocks and records must adhere to a specific structure.

Block structure � A data block can contain one or more records. The block begins with a two-byte count of the bytes in the block, with the most significant byte (MSB) value listed first followed by the least significant byte (LSB). Two null bytes follow the count bytes. The block size includes the block length bytes, null bytes, and sum of all the record lengths.

Block length byte (MSB)

Block length byte (LSB)

00

00

Records

Note that as long as the record structure is correct (see below), it is not necessary to block the records (that is, the block structure can be omitted). The Barr Host Communications Suite will automatically detect when the block structure is included. When the block structure is used, the format is referred to as BDW Block Descriptor Words. When the block structure is not used, the format is referred to as RDW Record Descriptor Words.

Record structure � Each record begins with a two-byte count of the bytes in the record and two null bytes, followed by a carriage control byte. The record size includes five bytes of format information (the length bytes, null bytes, and carriage control byte) and all the data bytes. Carriage control bytes must be expressed as machine carriage control.

Record length byte (MSB)

Record length byte (LSB)

00

00

Machine carriage control byte

Data bytes

S/370 format

Files in S/370 format must have a four-byte format header at the beginning of the file. The format header bytes must have specific hexadecimal values. Data records follow the file format header and are usually in EBCDIC because most channel printers require EBCDIC data. Records must contain count bytes indicating the record length and channel command characters. Additionally, most records contain print data. Follow the guidelines below when you create data records.

Include a record length count at the beginning and end of the record. Both length counts must have the same value and must include the number of data bytes plus one byte for carriage control.

Include only one channel command byte per record. Use machine channel commands.

Format header

76 1A FF FF

Records

Beginning length byte

2 bytes (LSB MSB)

Channel command

1 byte (machine carriage control)

Print data

0 - n bytes

Ending length byte

2 bytes*

*The beginning and ending length bytes have the same values.

For S/370 record format, you must give the record length counts in INTEL format, where the most significant byte (MSB) follows the least significant byte (LSB). For example, you would represent the length value 0150 as 50 01.

In this example, the file contains a header and three records. Two of the records contain print text.

76 1A FF FF 01 00 8B 01 00 04 00 09 C8 C9 5A 04 00 05 00 89 C4 D6 D5 C5 05 00

 

Header

76 1A FF FF

 

 

 

 

Record 1

01 00

Beginning length bytes (record contains one byte)

 

8B

Channel command (Skip to Channel 1)

 

01 00

Ending length bytes

 

 

 

Record 2

04 00

Beginning length bytes (record contains four bytes)

 

09

Channel command (Write and Space 1 Line)

 

C8 C9 5A

Data (HI!)

 

04 00

Ending length bytes

 

 

 

Record 3

05 00

Beginning length bytes (five bytes of information)

 

89

Channel command (Write and Skip to Channel 1)

 

C4 D6 D5 C5

Data (DONE)

 

05 00

Ending length bytes