There are twelve subroutine calls available to control the PCEBBC. All are called as functions with one or more arguments and return an integer status code indicating whether the operation was successful. The first argument to each call is a pointer to a File Control Block (FCB), a data structure used to pass setup information to the I/O routines and status information back to the user. The FCB structure is described in SECTION 3; C Language definitions for the FCB and error codes returned by the various routines are found in the header file HSDIO.H.

These routines assume Large or Huge memory model; all calls are far calls and all addresses passed as parameters are assumed to be far pointers (segment:offset) form. Calling sequences, arguments and error returns are discussed in the following sections. Up to four PCEBBC's may be controlled by these subroutines, provided the user maintains a unique File Control Block (FCB) for each device. The user must not alter those portions of the FCB used by the I/O routines while the device is open.

NOTE: These routines use the "C" language calling conventions. If calling these routines from FORTRAN or other high level language, the appropriate high level language facility (e.g. the INTERFACE statement in FORTRAN) should be used.

All calls except BBCOPEN, BBCCLOS, BBCRESET, BBCSTS and BBCOSF may be performed in No-Wait mode. In No-Wait mode the operation is initiated and control is returned to the caller with a status of 0 (success), unless an error is found in the call arguments. The caller is then responsible for testing the FCB busy bit (bit FCB_BUSY in FCB field fcbsts) or calling BBCTEST to determine when the operation has completed.

The BBCOPEN routine must be called first to install the driver in the MS-DOS interrupt structure, to initialize some necessary data structures, and to set the PCEBBC On-Line. The user passes a File Control Block (FCB) address to the subroutine. The user must have filled in the slot field in the FCB with the PCEBBC's EISA slot number.

Calling Sequence:

status = BBCOPEN(&fcb_blk);

fcb_blk is a File Control Block structure which contains status, and set-up information.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Open completed successfully.

1 (E_INVAL) Invalid slot number specified.

2 (E_OPEN) FCB already open.

3 (E_CNFG) Unable to locate PCEBBC in EISA system configuration.

4 (E_MANY) Attempt to open too many PCEBBC's.

5 (E_BADDEV) Device not present or initial PCEBBC status is bad.

If E_CNFG or E_BADDEV is returned, the extended status field (xsts) of the FCB will contain an additional status code (see SECTION 4.1).

The BBCCLOS routine should be called last to reset the PCEBBC and disconnect the driver from the MS-DOS interrupt structure. The user passes a File Control Block (FCB) address to the subroutine.

Calling Sequence:

status = BBCCLOS(&fcb_blk);

fcb_blk is a File Control Block structure which contains status and set-up information.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Close completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

The BBCRESET routine is used to terminate any BBC transfer in progress and reset the PCEBBC. The PCEBBC status before and after the reset operation will be stored in the FCB. This operation is always performed in WAIT mode.

Calling Sequence:

status = BBCRESET(&fcb_blk, type);

fcb_blk is a File Control Block structure.

type is an integer reset type code which may be one or more of the following values or-ed together (symbols are defined in BBCDEV.H):

1 (O_R_DMC) Device Master Clear

2 (O_R_PROC) Processor master reset

4 (O_R_SEQ) BBC Sequencer reset

8 (O_R_FIFO) BBC FIFO reset

If Device Master Clear (O_R_DMC) is selected the unit field of the FCB defines the device to which the master clear is sent. The Master Clear signal will remain asserted until another BBCRESET call is made without O_R_DMC set.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

1 (E_INVAL) Bad reset type argument.

7 (E_NOTOP) FCB not previously opened.

10 (E_TIMO) Timed out waiting for reset to complete.

The BBCSTS routine is used to read the status of the PCEBBC. A call parameter selects whether the board configuration status, the operational status or the firmware revision status is read. This operation is always performed in WAIT mode.

Calling Sequence:

status = BBCSTS(&fcb_blk, type, &stswd);

fcb_blk is a File Control Block structure.

type is an integer status type code which may be one of the following values (symbols are defined in BBCDEV.H):

0 Return PCEBBC operational status

1216 (O_STS) Return PCEBBC operational status

1016 (O_FSTS) Return PCEBBC Firmware Revision status

1116 (O_CSTS) Return PCEBBC Configuration status

stswd is a longword to receive the board status.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

10 (E_TIMO) Timed out waiting for status request to complete.

The BBCOCW routine is used to output a command word to a device attached to the PCEBBC. The unit field of the FCB defines the device to which the command is sent.

Calling Sequence:

status = BBCOCW(&fcb_blk, ctlwd);

fcb_blk is a File Control Block structure.

ctlwd is a longword containing the device command to be sent. Only bits 0-21 of this word are sent to the device. Bits 22 and 23 are used by the PCEBBC to control DMA operations and must be set to zero for this routine; bits 24-31 are ignored.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

1 (E_INVAL) Bad device command (bits 22, 23 not zero).

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

9 (E_IOER) I/O Error on operation.

10 (E_TIMO) Timed out waiting for reset to complete.

The BBCOSF routine is used to send a special function word to the PCEBBC to control its operation. The special function word is remembered and re-sent to the board following any call to BBCRESET, which specifies a processor master reset (O_R_PROC), as this reset operation clears all special function selections. This operation is always performed in WAIT mode.

NOTE: BBCOPEN sends the board a special function word with the Online bit (OSF_ONL) set.

Refer to SECTION 3.5.3.1 of the PCEBBC Technical Manual for more information on Special Function Words.

Calling Sequence:

status = BBCOSF(&fcb_blk, sfuncwd);

fcb_blk is a File Control Block structure.

sfuncwd is a longword containing the special function word to be sent to the PCEBBC. Only bits 0-23 are used; bits 24-31 are ignored. The following bits are allowed (symbols are defined in BBCDEV.H):

OSF_DDC Bit 6: Send DCC signal on Data Chain Complete instead of on Word Count Complete

OSF_ONL Bit 4: Set PCEBBC on line

OSF_LNK Bit 2: Enable native PCEBBC ICF (Link) mode

OSF_PAR Bit 1: Enable odd parity check and generation

OSF_HLNK Bit 0: Make Link mode operations Harris compatible

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

9 (E_IOER) I/O Error on operation.

10 (E_TIMO) Timed out waiting for operation to complete.

The BBCODW routine is used to output a single 24-bit data word via the PCEBBC.

Calling Sequence:

status = BBCODW(&fcb_blk, &datawd);

fcb_blk is a File Control Block structure.

datawd is a longword containing the 24-bit data word to be written. Bits 24-31 of this word are ignored.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H).

0 Operation completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

10 (E_TIMO) Timed out waiting for operation to complete in WAIT mode.

The BBCIDW routine is used to read a single 24-bit word via the PCEBBC. Note, that if this call is made in NOWAIT mode, the contents of the datawd argument will be invalid while the FCB_BUSY bit is set in the FCB field fcbsts.

Calling Sequence:

status = BBCIDW(&fcb_blk, &datawd);

fcb_blk is a File Control Block structure.

datawd is a longword into which the 24-bit word will be stored. Bits 24-31 of this word are undefined.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

10 (E_TIMO) Timed out waiting for operation to complete in WAIT mode.

The BBCWT routine is used to write a block of data via the PCEBBC using DMA transfer.

Calling Sequence:

status = BBCWT(&fcb_blk, &bfr, count, devcmd);

fcb_blk is a File Control Block structure.

bfr is the buffer of data to be written.

count is the number of 24-bit words to transfer.

devcmd is a longword containing an optional command, to be issued to the device attached to the PCEBBC. Only bits 0-21 of this word are used; the other bits are ignored.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

1 (E_INVAL) Bad conversion type, or invalid transfer count. (See SECTION 3.3.1)

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

9 (E_IOER) I/O Error on operation.

10 (E_TIMO) Timed out waiting for data transfer to complete in WAIT mode.

The BBCRD routine is used to read a block of data via the PCEBBC using DMA transfer.

Calling Sequence:

status = BBCRD(&fcb_blk, &bfr, count, devcmd);

fcb_blk is a File Control Block structure.

bfr is the buffer of data to be written.

count is the number of 24-bit words to transfer.

devcmd is a longword containing an optional command, to be issued to the device attached to the PCEBBC. Only bits 0-21 of this word are used; the other bits are ignored.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

1 (E_INVAL) Bad conversion type, or invalid transfer count. (See SECTION 3.3.1)

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

9 (E_IOER) I/O Error on operation.

10 (E_TIMO) Timed out waiting for data transfer to complete in WAIT mode.

The BBCTEST routine may be used to wait for completion of a PCEBBC operation being executed in NOWAIT mode. If the timeout field of the FCB is non-zero at the time the operation is started, the specified time interval will be established. Subsequent calls to BBCTEST will test the FCB completion/error status and check that the timeout has not expired. An incomplete data transfer (non-zero residual word count) is not considered an error condition and must be tested separately.

Calling Sequence:

status = BBCTEST(&fcb_blk);

fcb_blk is a File Control Block structure.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Operation still in progress.

9 (E_IOER) Operation completed with error.

10 (E_TIMO) Timeout before operation complete.

The BBCCTL routine is used to perform certain functions which are unavailable through the other I/O routines. These functions are included primarily for diagnostic and test purposes.

Calling Sequence:

status = BBCCTL(&fcb_blk, func, arg);

fcb_blk is a File Control Block structure.

func is an integer code for the function to be performed. The following functions are valid (symbols are defined in BBCDEV.H):

BBC_DIAG Get PCEBBC diagnostic information: update the oldsts, bdsts, bstate, and bbccmd fields in the FCB; return the contents of the four PCEBBC DCB words to the caller's buffer.

arg is a longword or a far (segment:offset) pointer whose interpretation is dependent on the function requested.

BBC_DIAG Arg is a far pointer to a four-longword area to receive the current contents of the four PCEBBC DCB registers.

status is the returned integer value which may be one of the following (symbols are defined in BBCIO.H):

0 Operation completed successfully.

1 (E_INVAL) Bad function code argument.

7 (E_NOTOP) FCB not previously opened.

8 (E_BUSY) Prior operation still in progress.

9 (E_IOER) I/O Error on operation.

10 (E_TIMO) Timed out waiting for operation to complete.