The B correlative allows mvBASIC subroutines to process data from within an Attribute Definition item.
Two forms of the B correlative are supported. The first form passes data to the subroutine, and receives data from the subroutine a single value at a time. The B correlative may appear on line 7 or 8 of the Attribute Definition item; it may be included with A or F correlatives, and within a series of multiple conversion codes.
Format
B;[file.name] sub.name |
Parameter(s)
file.name |
Specifies the file in which the subroutine resides. |
sub.name |
Specifies the name of the subroutine. |
Description
The second form of the B correlative may be used when multiple values are to be processed as a set rather than a single value at a time. The entire attribute, including all MultiValues and multisubvalues, are passed to the specified subroutine. The subroutine may return a result with MultiValues or multisubvalues. When the second form of the B correlative is used, it must be specified on line 8 of the Attribute Definition item. The B correlative may not be included with the A or F correlatives, or within a series of multiple conversion codes.
Format
B:[file.name] sub.name |
Parameter(s)
file.name |
Specifies the file in which the subroutine resides. |
sub.name |
Specifies the name of the subroutine. |
Description
When using either form of the B correlative, if file name is specified, the file’s dictionary must contain the compiled object code for the specified subroutine. If file name is not specified, the specified subroutine must be cataloged.
Example
The next example creates an index for a report that is to be generated. The Attribute Definition item for REGION.INDEX and the subroutine shown below create an index file which may be sorted after the report has been generated.
0001 A 0002 12 0003 0004 0005 0006 0007 0008 B;BP INX 0009 L 0010 10 |
The mvBASIC subroutine INX is:
0001 SUBROUTINE INX 0002 $INCLUDE BASICLIB ACCESS.COMMON 0003 IF NOT (FIRST.TIME) THEN 0004 OPEN ‘INDEX.FILE’ TO INDEX ELSE STOP 201, ‘INDEX.FILE’ 0005 FIRST.TIME = 1 0006 END 0007 IF NB$ > 1 THEN 0008 PAGE.NO = SYSTEM(5); * CURRENT PAGE NUMBER 0009 WRITE PAGE.NO ON INDEX, CURRENT$; * WRITE TO FILE 0010 END 0011 RETURN CURRENT$; * RETURN VALUE UNCHANGED |
Subroutines used in B correlatives must conform to the following rules:
The INFO/ACCESS common block, defined by the item ACCESS.COMMON in the BASICLIB file, should be included in the subroutine referenced in the B correlative. The INFO/ACCESS common block contains the following variables:
DICT$ |
Variable assigned to the dictionary of the file being referenced in the subroutine. |
FILE$ |
Variable assigned to the file being referenced in the subroutine. |
FILENAME$ |
Variable containing the name of the file being referenced in the subroutine. |
CURRENT$ |
Variable containing the current value being passed to the subroutine. |
ID$ |
Variable containing the item-id of the current item being processed. |
ITEM$ |
Variable containing the item body of the current item being processed. |
NI$ |
Variable containing the current item count. |
ND$ |
Variable containing the current detail count. As with A and F correlatives, the value is normally 1. |
NB$ |
Variable containing the current break level. |
NA$ |
Variable containing the current attribute number. |
NV$ |
Variable containing the current value number. |
NS$ |
Variable containing the current subvalue number. |
MAX$ |
Variable containing the current column width as defined in the Attribute Definition item. |
The subroutine must begin with a SUBROUTINE statement, without arguments.
The subroutine should not contain any unnamed COMMON statements except the one defined in the INFO/ACCESS common block. Named COMMON statements may be used if additional COMMON statements are needed.
A RETURN statement, followed by a valid expression containing the result to be passed back to the INFO/ACCESS processor, must be included in the subroutine.
Although most statements may be used by the subroutine, operations such as the following should be avoided: updating a file which INFO/ACCESS is processing, performing backup medium operations such as READT, WRITET, during a T-DUMP or T-LOAD, and chaining to other programs.
See Also