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