System Functions
FIN( ) Return File Information
   
Formats 1. Return File Information: FIN(chan[,ERR=stmtref])
2. Return Detailed Information: FIN(chan,field$[,ERR=stmtref])

Where:
chan Channel or logical file number of the file to return information about.
field$ String expressions (case insensitive). For valid keywords, refer to the description of Format 2 below.
stmtref Program line number or statement label to which to transfer control.
   
Returns String, physical information about open file.
   
Description The FIN( ) function returns a character string containing details about an existing open file. The information returned is not the same as that in the FIB( ) function. While some of the information in the FIN( ) function is common to information in the FIB( ) function, the FIN( ) function includes more detailed information about the physical file (e.g., file size in bytes, date and time of last update, etc.).
*Note* The FID( ) and FIN( ) format layouts will be changed whenever there is a change to the 'FF' system parameter.
   
Format 1 Return File Information

FIN(chan[,ERR=stmtref])

In the example below, the FIN( ) function is used to find out the number of characters in IN_FILE$ (the variable contains the name of a serial file).

0140 LET IN_FILE=HFN; OPEN (IN_FILE)IN_FILE$
0150 LET F$=FIN(IN_FILE)
0160 CLOSE (IN_FILE)
0170 LET CHARS=DEC(F$(1,4))
0180 !

   
Format 2 Return Detailed Information

FIN(chan,field$[,ERR=stmtref])

Use this format to have the FIN( ) function return details. For example, FIN(10,"DEVHANDLE") returns the value of the Windows API Device handle for a communications port.

A list of valid keywords for the FIN( ) function is provided below:

FIN field$ value Description
BUFFERED Returns 1 for output buffered, 0 for not buffered
COLOURnnn ¹ RGB value or logical name for colour number (1-256)
CURKNO Returns the current KNO value
DEVHANDLE Windows API device handle for communications port
DRIVER ProvideX device driver name
EXTRACT Extract status of file (1 if Extract pending)
FILE_CREATE Returns file creation command for any ProvideX-based file
FILELENGTH Size of physical file
FONT Window text font
FILENAME Original filename used in OPEN
GRAPHICFONT ¹ Window default graphic font
HANDLE Operating system file handle
HDC Returns handle to the device context for a *WINPRT* channel
IPADDR TCP/IP Address
ICON Window default icon image name
IO_PROGRAM Program filename of imbedded I/O
KEY_DEFINITION Human readable key definition
KEY_NAMES List of Named Keys for an open channel
KEY_OPTIONS Returns the OPT= value
KEY_SIZE External Key size of a Keyed file
KSZ Same as KEY_SIZE
MAXKNO Maximum file access key number allowable for the file
MAXREC Same of RECORDS_ALLOWED
NAME Same as PATHNAME
NUMREC Number of records used
PATHNAME Full pathname of file
RECORD_SIZE Maximum record size
RECORDS_ALLOWED Maximum # of records
RECORDS_USED Same as NUMREC
RESOURCELIB Pathname to resource library
RSZ Same as RECORD_SIZE
SEPARATOR Field separator character or “*Dynamic*” for files with dynamic field separators
STDFONT ¹ Standard window text font
STDGRAPHICFONT Standard graphic font
TIPTIMERCYCLES ¹ Defines the number of seconds that a tip will be displayed (version 8.30)
TRUE_TTY ¹ UNIX/Linux only. Returns FacetTerm TTY (Returns "JavX" when using JavX)
UTC_ATime Last accessed time, UTC in seconds since Jan 1,1970
UTC_CTime Creation/changed time, UTC in seconds since Jan 1,1970
UTC_MTime Last modified time, UTC in seconds since Jan 1,1970
WDWICON ¹ Window icon image name
X509_ISSUER Who issued SSL certificate
X509_NOT_AFTER Latest date the certificate is valid for
X509_NOT_BEFORE Earliest date certificate is valid for
X509_KEYTYPE What type of key is in certificate
X509_SUBJECT Who certificate is issued to
  The following FIN values are +PxPlus Exclusive
4D_ML_ADJUST ¹ Override value for the height adjustment to be applied to 4D multi-lines.
ALWAYSONTOP ¹ Returns "1", if the window is locked On Top of all other windows. "0", if not
BLINKTIME The BLINKTIME returns the rate at which data will blink on a graphical device. The value defines the rate appears or disapperars in terms of milliseconds (i.e. "500" indicated 500ms or 1/2 a second). A rate of "0" indicates blinking is deisabled. The default rate is "500" milliseconds. (build 9182)
BBXFIN Returns a fully compatible BBx® style FIN for a terminal device
BYTESLEFT Returns the number of bytes of text data unprinted in the last Block print to a WINPRT or PDF file
CLRAUTOCOMPBACK ¹ The Background colour to be used for text in auto complete List boxes. (build 9200)
CLRAUTOCOMPTEXT ¹ The Text colour to be used for text in auto complete List boxes. (build 9200)
CLRDISABLEDBACK¹ The Background colour to be used for text in disabled List boxes, Multi-lines, Radio-button text and Check boxes (build 9200)
CLRDISABLEDTEXT ¹ The Text colour to be used for text in disabled List boxes, Multi-lines, Radio-button text and Check boxes (build 9200)
CTLLIST ¹ List of CTL values currently present on the window
DEVICE Can be used with WINPRT or WINDEV devices to return the physical device name of the printer being used
DISKFIN Can be used with a *PDF* file to obtain a Disk FIN ( ) format return value instead of a Device style response
DROPFILES ¹ List pathnames of files that have been dropped onto a control/window from an external application
FORMATS Returns a list of the valid record formats for the opened file. The format names will be separated by a standard field separator character (SEP). If the file does not contain multiple record formats, the function will return a null string. See Multiple/Variant record format files.
FRAME ¹ Returns the current window frame setting. Possible values are: (build 9163.1)
"NONE" The window has no border/frame
"CAPTION" The window has a border and caption line
"THICK" The window has a thick border
"THIN" The window has a thin border (usually a single pixel wide black line)
FREECTL ¹ Returns the lowest unused CTL number within the range of 5000 through 9999 for the current window. (Can only be used with file 0).
HEIGHTTEXTUSED Returns the number of lines of print space used in the last Block print to a WINPRT or PDF file
HIDETIPS ¹ This option is issued to control the display of Floating tips in the system. If set to "1" tips will not be displayed. Setting it to a null value or "0" (default setting) enables Tips.
HOVERCTL ¹ Returns the CTL value that the system will generate when the mouse hovers over the text plane in the current windows. A value of "0" indicates the option is disabled (default).
IDENTIFIER_QUO Returns the character(s) required by a SQL based database that must surround field, column, or table names that contain invalid characters such as spaces. (ODB, Oracle, DB2, and MySql only)
KEYBOARD ¹ Returns a four character hex string containing the current keyboard language.
** WINDOWS ONLY** (build 9182)
LCL_CTIME
LCL_MTIME
LCL_ATIME		 These FIN functions return the files creation, modified, and last access time as a string consiting of:

YYYY-MM-DD hh:mm:ss

The date/time returned has be converted to local time on the system thus for files on a shared server the value may differ based on the current time zone. (build 9182)
MASKCOLOUR ¹
or
MASKCOLOR		 Returns the colour to be considered completely transparent within the current window. Returns a value of "N/A" if transparency is not available. Note that clicking the mouse on a fully transparent section of the window passes the mouse click to the window below. (build 9163.1)
ML_OVERLAP_ADJUST ¹ Returns the current setting for the automatic adjustment of the size/position of overlapping multi-line controls. When enabled (returns "1") the system will adjust multi-lines so that neither the field nor its border overlap any adjacent multi-line.
MOUSEWHEEL ¹ Current setting for the mouse wheel in terms of the number of Up/Sown arrows to emulate when using the wheel
MESSAGEBAR ¹ This option returns the height of the message (status) bar region at the bottom of the screen.
OWNER Number of the object that owns the file. (i.e. The Object that issued the OPEN OBJECT directive for the file)
ORIENTATION Can be used with a WINPRT or PDF device to obtain the current printout orientation of either LANDSCAPE or PORTRAIT.
"PDFFACTOR" ¹ This option return the multiplication factor to be used in computing the extra vertical space (height)to be allocated to PDF fonts. Applies only to PDF files when using the Haru library. (default 1.2).(build 9200)
"PDFFONTDIR" ¹ This option returns the directory the system will search for true type fonts when creating PDF files. (build 9200.1)
"PDFMARGIN" ¹ This option returns the number of thousandths of an inch currently used for setting the default PDF printer margins. These will be assigned on all edges of the printed document. Default value is 250 (1/4 of an inch).(build 9200)
PORT Can be used with a WINPRT device to obtain the physical port being used for print job.
RMOUSECOPY This option returns the setting of right mouse click Copy/Paste functionality. This functionality is primarily used when running older Text mode applications and provides the ability to copy/paste text from the screen much like a terminal emulator. When the value is "ON", the user can use the right mouse button to copy/paste text from/to the application. It is "OFF" by default. Its setting is automatcially cascaded to subsequent windows. (build 9182)
SOURCE Can be used with a WINPRT device to return the current selected source (Bin) number. Use SOURCELIST (below) to determine the possible sources and their associated numbers.
SOURCELIST Can be used with a WINPRT device to return a comma separated list of printer paper sources (bins). Each entry consists of its internal source number, a colon, and name.
(e.g. "7:Sheet,259:Sheet (Borderless),4:CD/DVD,")
SUPPRESS_FF Returns the file FF suppression settings which will be one of the following values: (build 9200)
"NO" No FF suppression (default setting)
"ALL" All FF's that occur with no intervening data will be suppressed
"FIRST" If the initial output to the file is an 'FF' is will be suppressed
"LAST" If the final output to the file is an 'FF' is will be suppressed
"BOTH" Same as "FIRST" and "LAST"
TIPFONT ¹ This option returns the current font attributes of the floating tip windows.
TOOLBAR ¹ This option returns the height of the toolbar (region at the top on the main window above window 0).
TRANSPARENCY ¹ Percentage transparent for the current window. A value of "0" indicates non-transparent, "100" would be completely transparent. Can only be applied to TOP level windows. Returns the value "N/A" if transparency is not available.
XYCLIENT ¹ Returns the width and height (in pixels) of the client region for the current window..(build 9190)
XYMOUSE ¹ Returns the X and Y position for the mouse in a Graphical environment. The values returned are absolute value relative to the desktop monitor as opposed to the current window.(build 9163.1)
XYPOS ¹ Returns four comma separated numbers containing the absolute pixel address (top, left, bottom, and right) for the current window. These numbers are relative the desktop of the workstation or the current window's parent window,(build 9163.1)
XYREGION ¹ Returns four comma separated numbers containing the dimensions (in pixels - top, left, bottom, and right) of the full desktop. These values will differ from the maximum window size returned in the MSE variable as it returns the size of the largest window workspace excluding caption and border. This value returns the usable size of the desktop. A non-zero top value indicates the tool-bar is on the top, a non-zero left value indicates the tool bar in to the left.(build 9163.1)
XYWDW ¹ Returns four comma separated numbers containing the dimensions (in pixels - top, left, bottom, and right) of the current child window. This is slightly different to XYPOS in that the information pertains to the Child windows as opposed to the outer/dialog window.(build 9182)
ZORDER¹ Returns "1" (default setting) if the current window will be brought to the top of the Z-Order when input focus switches to the window. "0" indicates that the z-order of the window will not be changed when focus switches to the window.(build 9182)

¹ Indicates this option can only be used with channel 0
*Note* The record count returned by NUMREC / RECORDS_USED is based on the last file I/O operation performed by the current task. To obtain up-to-date values, force an I/O operation against the file prior to requesting this information, or use FIB( ) instead.
*Note* UTC_ATime, UTC_CTime, and UTC_MTime (Universal Coordinated Time) values returned are OS dependant. Exact definitions of these items may only be determined by checking the OS/file system documentation, as well as, characteristics for the stat function from where the information is queried.
  Keywords for the 'OPTION' Mnemonic

The keywords used in the 'OPTION' mnemonic can also be used by the FIN( ) function to retrieve information about environment properties with reference to channel 0. For example, FIN(0,""RESOURCELIB") returns the current resource library.

For the complete list of available keywords, refer to the 'OPTION' Mnemonic.

   
For UNIX FacetTerm Use Only The FIN( ) function reports the actual TTY on which the UNIX FacetTerm session was initiated. If the environment variable FACETTYPE is set / ON in a current FacetTerm session, recognition is automatic. FIN(0,"TRUE_TTY") will return the TRUE /dev/tty terminal or device.

The value returned on a system without FacetTerm will be the same as the value returned by PTH(0).

For more information, see PTH( ) Return Pathname.

FIN( ) Contents Two formats of FIN are provided depending on whether the file is disk resident or a device.

FIN( ) For Disk Resident Files 

Bytes Common Header for ALL Disk Resident Files (Total length=68 bytes)
1,4 Number of bytes in the file
5,4 Date/Time of last modification (Seconds since Jan. 1, 1970)
9,4 Date/Time of last access
13,4 Date/Time of file creation/change
17,2 Physical device number
19,4 Inode number (UNIX/Linux only)
23,2 UserID of file owner (UNIX/Linux only)
25,2 GroupID of file owner (UNIX/Linux only)
27,2 Status flag. Bitmapped values for OPEN clauses:

$0001$ - READ Ok
$0002$ - WRITE Ok
$0004$ - EXECUTE Ok (Windows only flag value)
$0008$ - Is a directory
$0010$ - LOCK'ed
$0020$ - OPEN INPUT
$0040$ - OPEN LOAD
$0080$ - File has been purged.

60,4 Maximum record count
64,4 Current record index
  Additional Information for KEYED files
77,4 Number of records on file
85,1 Current access key number
86,128 Key definition data. See FIB( ) and FID( ) for Keyed Files, bytes 85, 384 or use utilities to return key information (e.g., *UFI and **KEY.INF )
*Note* File times returned by the FIN( ) function on UNIX/Linux systems are reported based on the current time zone, rather than GMT. This keeps the file time reporting consistent with Windows versions of ProvideX.
   
  FIN( ) For Device Files only (also Windows printers, *PDF*, and *FAX*)
Bytes For Device Files Only. (TCP Files are Reported as Devices.) FIN( )
1,1 Current column
2,1 Current line number
3,1 Maximum column number
4,1 Maximum line number
5,1 Column offset to start of scroll region
6,1 Line offset to start of scroll region
7,1 Current width of scroll region
8,1 Current height of scroll region
9,1 Reserved (always $00$)
10,1 Current window number
11,1 Reserved (always $00$)
12,1 Current device attribute bits
13,1 Current foreground colour
14,1 Current background colour
15,1 Reserved (always $00$)
16,1 Default attributes
17,1 Default foreground colour
18,1 Default background colour
19,2 Current device mode
21,4 Current device status words 1 and 2
25,2 Auxiliary attributes
27,2 Device option flags
29,2 Operating system handle (Windows only)
31,1 Standard character width
32,1 Standard character height
33,... Pathname to device ($00$-terminated)
33+n... Device type ($00$-terminated)
   
See Also FIB( ) Return File Information Block,
FID( ) Return File Information Descriptor,
FILE Directive,
'FF'= System Parameter
'PO' System Parameter

BBx® is a registered trademark of Basis International.