FIN() Function - File Information

Syntax

FIN(channelno{,ERR=lineref})

Description

For BBj-specific information, see FIN() Function - BBj.

The FIN() function returns file information associated with specified channel. The number of bytes of information returned depends on the file types. The FIN() function returns the current status and system-specific information.

See also XFIN() Function - File Information.

Parameter

Description

channelno

Valid channel number.

ERR=lineref

Branch to be taken if an error occurs during execution.

Non-device FIN() Data

The FIN() data for nondevices always contains 64 bytes of reserved space, including the following information:

Bytes

Contents

1,4

Current file length in bytes (not valid for all file types).

27,4

Date and time of the last modification of the file associated with this channel.

Under the UNIX operating system, the FIN() data for a regular file (not a directory) contains the date the file was last modified. In MS-DOS, the FIN() data contains the date the file was last written. In either the UNIX operating system or MS-DOS, the FIN() date is in MS-DOS format, starting at offset 27 of the FIN() data.

The data appears as a 16-bit date and a 16-bit time, formatted as:

yyyyyyym mmmddddd hhhhhmmm mmmsssss

Refer to Examples, for a program fragment demonstrating the use of the time and date data.

The bytes following the first 64 contain the following information for the specified file types.

SERIAL File FIN() Data

Bytes

Contents

65,4

Next available file index.

69,4

Number of bytes in file, including the header.

73,2

Number of bytes in the last record.

75,2

"s"+$01$

DIRECT or SORT File FIN() Data

Bytes

Contents

65,4

Index of the last key removed (Base 1).

69,4

Index of the lowest available key (Base 1).

73,4

Index of the lowest logical key (Base 1).

77,4

Number of active keys in the file.

81,4

Index of the highest logical key (Base 1).

MKEYED File FIN() Data

Bytes

Contents

65,12

$00$'s

77,4

Number of active keys in the file.

81,4

$00$'s

85,1

Default KNUM value.

86

Key definition data.

Key Definition Data

The key definition information is 48 8-byte entries using the following fields for each of the 48 entries:

Bytes

Contents

1,1

Key number or $FF$ for the end of definitions.

2,1

Field in record to use, or $00$ for no fielding.

3,2

Offset in field/record (0 based, 1024 maximum).

5,1

Length of this segment.

6,1

Segment modification bits:
$01$ - Descending segment
$02$ - Unique flag
$04$ - Business math flag
$08$ - Ordered numeric flag
$10$ - In BBj 12.0 and higher, case insensitive flag

7,2

$0000$

Following the last segment definition, the next key segment description key number must contain an $FF$ to indicate the end of the next segment list.

C-ISAM File FIN() Data

The FIN for C-ISAM files is identical to the FIN for MKEYED files, with the following exceptions:

The byte following the flags byte in the FIN() key data includes field type data for the C-ISAM file type. The C-ISAM file manager may use this information; PRO/5, however, ignores it. The field values and their C-ISAM names are as follows:

Field Value

C-ISAM Name

$00$

CHARTYPE

$01$

INTTYPE

$02$

LONGTYPE

$03$

DOUBLETYPE

$04$

FLOATTYPE

The file type for C-ISAM files is $07$.

There may be additional system-dependent exceptions that are beyond the scope of PRO/5. Information concerning some system-dependent exceptions can be found in the release notes (READ.ME file).

Printer and Terminal FIN() Data

The FIN for a printer or terminal contains the following information:

Bytes

Contents

1,1

Current column.

2,1

Current line.

3,1

Contains the larger of configured columns in standard or compressed print modes. For printers, current screen cols for terminators.

4,1

Contains the larger of configured lines in standard or compressed print modes; for printers, current screen rows for terminators.

5,1

Current column offset (scroll region).

6,1

Current line offset (scroll region).

7,1

Current columns (scroll region).

8,1

Current lines (scroll region).

9,2

Current screen/page number.

11,1

*reserved.*

12,1

Current mode bits.

13,2

Current color attribute.

15,1

*reserved.*

16,1

Default mode bits.

17,2

Default color attribute.

19,1

Internal - device type.

20,2

Internal - CIB flags.

22,2

Internal - device flags.

24,9

*reserved.*

33,n1

Actual device name (host name) + $00$.

33+n1,n2

Device type/termcap type + $00$.

33+n1,n2,n3

Modes from alias line + $00$.

Plot Device FIN() Data

The FIN() of a plot device contains the following information:

Bytes

Contents

1,2 

World min x.

3,2 

World min y.

5,2 

World max x.

7,2 

World max y.

9,2 

Viewport min x.

11,2

Viewport min y.

13,2

Viewport max x.

15,2

Viewport max y.

17,2

Device x resolution.

19,2

Device y resolution.

21,2

Current x aspect (signed binary, in 256ths).

23,1

# of colors/pens available (raster b&w = 2).

24,1

# of palettes available (0 for non-raster devices).

25,1

Plotter pen width (in device coordinates).

26,1

# of line styles available.

27,2

Plotting flags

0x8000    MS-DOS loaded driver

0x4000    MS-DOS display (shared)

0x0800    Raster plotter

0x0080    Filling enabled

0x0001    Pen down

29,2

Default x aspect (signed binary, in 256ths).

31,1

Maximum lines with readable characters.

32,1

Maximum columns with readable characters.

33,n1

Actual device name (host name) + $00$.

33+n1,n2

Device type/termcap type + $00$.

33+n1,n2,n3

Modes from alias line + $00$.

SYSGUI Channel-Specific FIN() Data

With a SYSGUI channel and an IND=0 (or without specifying any IND= parameter), the FIN() function returns the information below. The template can be obtained with TMPL(chan,IND=0) on the same channel. With the TMPL() function, the IND=0 parameter is required to get a template for the FIN(). Otherwise, a template for the record data (SYSGUI event structure) is returned. Returned templates start at position 65.

FIN(sysgui_chan,IND=0)

Value

Meaning

Current_context:u(2),

Number of the active context, same as CTRL(chan).

Available_context:u(2),

Lowest numbered empty context.

Active_context_count:u(2),

Number of contexts currently in use.

Scale_x:b,

Current x 'SCALE' multiplier.

Scale_y:b,

Current y 'SCALE' multiplier.

Units:c(1),

"P"ixels, "S"emichars or "C"hars.

Screen_width:u(2),

Pixel width of display device.

Screen_height:u(2),

Pixel height of display device.

Screen_hres:u(2),

Pixels-per-inch of display device (horizontal).

Screen_vres:u(2),

Pixels-per-inch of display device (vertical).

Display_type:u(1)

Type of display in use. One of the following:

Value Meaning

0 Monochrome

1 16 grayscale

2 256 grayscale

3 16 color

4 256 color

5 More than 256 colors

Devname:c(1*=0)

"sysgui"

Devtype:c(1*=0)

Type specified in the alias.

Devmode:c(1*=0)

Mode string used to open the device.

SYSWINDOW Device FIN() Data

When the FIN() function is used on a channel that is opened to a SYSWINDOW device (such as the graphical console terminal window), it can be invoked with an IND= parameter to retrieve special information about the terminal window.

IND=1

With a SYSWINDOW channel and IND=1, the information retrieved fits the following template. The template itself can be obtained with TMPL(chan,IND=1) on the same channel. The following is an example of a FIN() function on a SYSWINDOW channel:

FIN(syswindow_chan,IND=1)

Value

Meaning

Has_focus:u(1),

Nonzero if window has focus.

Mouse_buttons:u(1),

Bitmap of mouse button status.

Mouse_win_col:u(1), Mouse_win_row:u(1),

Column and row of mouse pointer, relative to current screen.

Mouse_term_col:u(1), Mouse_term_row:u(1),

Column and row of mouse pointer, relative to whole terminal window.

Mouse_x:u(2), Mouse_y:u(2)

Pixel location of mouse pointer, relative to whole terminal window.

IND=2

With a SYSWINDOW channel and IND=2, the following information about the current font is returned. The template itself can be obtained with TMPL(chan,IND=2) on the same channel.

FIN(syswindow_chan,IND=2)

Value

Meaning

Font_width:u(1),

Width of character cell in pixels.

Font_height:u(1)

Height of character cell in pixels.

IND=3

With a SYSWINDOW channel and IND=3, the following is returned. The template itself can be obtained with TMPL(chan,IND=3) on the same channel.

FIN(syswindow_chan,IND=3)

Value

Meaning

Term_x:u(2)

Pixel location of upper left corner of the inside of the terminal window, relative to the screen.

Term_y:u(2)

Pixel location of upper left corner of the inside of the terminal window, relative to the screen.

SYSPRINT Device FIN() Data

IND=1

FIN(chan,IND=1) on a SYSPRINT channel returns the physical pixel counts on the device for the offset to printing area, printer physical pixel width and height, font width and height, the printing area width and height, and the current selected font face name. The template for this data is returned in TMPL(chan,IND=1), and uses the following format:

xres:u(2),yres:u(2),xppi:u(2),yppi:u(2),xoffset:u(2),yoffset:u(2),pwidth:u(2),pheight:u(2),char_width:u(2),char_height:u(2),pagepos:u(2),tmargin:u(2),lmargin:u(2),rmargin:u(2),bmargin:u(2),font:c(48*=10)

Note: BBj returns values in points instead of pixels. A point is 1/72". The xppi and yppi values both return 72. For example, if the top margin is set to 1/4", the tmargin value returns 18.

 

Parameter

Description

xres

The number of printable pixels (or dots) available horizontally on the print page. This value is smaller than yres if the page is portrait, and larger if the page is landscape. The value does not include unprintable areas defined by the printer/print driver and is in printer units.

yres

The number of printable pixels available vertically on the page. This value does not include unprintable areas defined by the printer/print driver and is in printer units.

xppi

The number of pixels per horizontal inch, as defined by the printer.

yppi

The number of pixels per vertical inch, as defined by the printer.

xoffset

The value returned by the print driver for the unprintable area on the left side of the page.

yoffset

The value returned by the print driver for the unprintable area at the top of the page.

pwidth, pheight

Similar to xres and yres, pwidth and pheight include the unprintable areas of the page. To compute the dimensions of the page in inches, divide these values by xppi and yppi, respectively.

char_width, char_height

The current values being used by the interpreter for computing character and line spacing. These values are based on either the last font selected using the 'FONT' mnemonic or on the values of COLS and ROWS/LINES, given in the alias line. If COLS and ROWS/LINES are used with CPLINES rather than with SPCOLS, SPLINES, EPCOLS, EPLINES, and CPCOLS, the char_width and char_height are computed based on the fonts selected for these modes. The reported values depend on the mode selected by the software before retrieving the FIN() information.

pagepos

The current line position on the page that will be used for the next printed output. This is a zero-based value, where zero is the top margin of the page.

tmargin, lmargin, rmargin, bmargin

Specifies the top, left, right and bottom margins. If no margins are specified, they default to the unprintable area reported by the Windows printer driver. These values are in device coordinates.

font

The current font for printing.

IND=2

FIN(chan,IND=2) on a SYSPRINT channel returns the available fonts.

Examples

>FIN$=FIN(CHANNEL)
1000 FIN$=FIN(1,ERR=9500)

The following program fragment illustrates the use of time and date information in the FIN data.

0010 BEGIN
0020 OPEN (1)"filename"
0030 LET F$=FIN(1)
0040 PRINT FNFILEDATE$(F$(27,4),"%Ms %D, %Y %Hz:%mz:%sz")
0050 ESCAPE
1000 DEF FNFILEDATE$(DATE$,FORMAT$)
1010 LET TIME$=DATE$(3,2),DATE$=DATE$(1,2)
1020 LET DATE_Y=DEC($00$+AND(DATE$,$FE00$))/512+1980
1030 LET DATE_M=DEC($00$+AND(DATE$,$01E0$))/32
1040 LET DATE_D=DEC($00$+AND(DATE$,$001F$))
1050 LET TIME_H=DEC($00$+AND(TIME$,$F800$))/2048
1060 LET TIME_M=DEC($00$+AND(TIME$,$07E0$))/32
1070 LET TIME_S=DEC($00$+AND(TIME$,$001f$))*2
1080 LET TEMP$="",TEMP$=DATE(JUL(DATE_Y,DATE_M,DATE_D),
1080:(TIME_H+TIME_M/60+TIME_S/3600):FORMAT$,ERR=1090)
1090 RETURN TEMP$
1100 FNEND

See Also

Functions - Alphabetical Listing



______________________________________________________________________________________

Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.