# System Functions

FIN( ) | Return File Information

## Formats

1. | Return File Information: | FIN(filespec [,ERR=stmtref])
2. | Return Detailed Information: | FIN(filespec,field$ [,ERR=stmtref])

Where:

filespec | Can be a numeric expression indicating the open channel number to use or a string expression containing the pathname or table name (if string is prefixed by the keyword TABLE) of the file to use.
field$ | String expressions (case insensitive). For a list of valid keywords, see Format 2.
stmtref | Program line number or statement label to which to transfer control.

(TABLE support was added in PxPlus 2018 Update 1.)

## 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 the 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(filespec [,ERR=stmtref])

Example:

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

> IN_FILE=hfn;
> open (IN_FILE)IN_FILE$
> F$=fin(IN_FILE)
> close (IN_FILE)
> CHARS=dec(F$(1,4))
> !

## Format 2

Return Detailed Information

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

Use this format to have the FIN( ) function return details.

Example:

This returns the value of the Windows API Device handle for a communications port:

> fin(10,"DEVHANDLE")

The following table lists the valid keywords for the FIN( ) function:

FIN Field$ Value | Description
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.
AutoCompleteLimit ¹ | FIN(0,"AutoCompleteLimit") returns the current AutoComplete limit. (Default is 10.)
AutoConvertUtf8 ¹ | Returns "1" if enabled, "0" if not. When enabled in conjunction with setting the 'U8' system parameter, the system will internally convert UTF-8 data to its corresponding single byte character based on the current text plane character set to allow for its display. This conversion will be done on any standard PRINT to the text plane and on all user input of extended characters (e.g. Accented characters, high-order ASCII, etc.). Where there is no corresponding single byte character for a UTF-8 code, a ? will be output. If the 'U8' system parameter is not set, this option is ignored.
AutoSpellCheck | Returns the current setting for automatic spell checking for Multi-Line controls. Possible values are:
"YES" | (Default) Spell checking is automatically applied to Multi-Line controls that allow multiple lines of input (greater than 1.5 lines high).
"ALL" | Spell checking is automatically applied to Multi-Line controls that allow multiple lines of input, as well as all Multi-Line controls that allow for 12 or more characters of input and do not have a format mask. Controls that are marked Uppercase only or are used for Arabic (right to left) input are not spell checked.
"NO" | Spell checking is not automatically applied to Multi-Line controls. Only Multi-Line controls with the "S" option specified (see MULTI-LINE directive) will have spell checking enabled.
(added in PxPlus 2019)
BbxFIN | Returns a fully compatible BBx® style FIN for a terminal device.
BlinkTime | BLINKTIME returns the rate at which data will blink on a graphical device. The value defines the rate appears or disappears in terms of milliseconds (i.e. "500" indicated 500ms or 1/2 a second). A rate of "0" indicates blinking is disabled. The default rate is "500" milliseconds. (added in PxPlus v8.11, build 9182)
BrowserDebug | Returns "1", "Y" or "y" if the browser developer console will display in a popup window for *BROWSER controls that are created. The browser developer console makes it possible to examine the code and properties of the Web page loaded by the *BROWSER control and debug any errors. Returns "0" if the browser developer console will not display. (added in PxPlus 2021)
BrowserLang | Returns the language code that controls the embedded Chromium browser language. See Language Codes for a list of supported languages and codes. The value of BrowserLang is only read the first time per process that an embedded Chromium browser is created. This will override the BrowserLang INI setting. Defaults to user OS language unless BrowserLang was set in the INI file. See INI Contents. (added in PxPlus 2019)
Buffered | Returns "1" for output buffered, "0" for not buffered.
Buffers | Returns the number of buffers allocated specifically for the file. Returns "0" if using common buffer pool.
BytesLeft | Returns the number of bytes of text data unprinted in the last Block print to a WINPRT or PDF file.
CaptureClientOnly ¹ | Returns the settings controlling the SAVE CONTROL output. Will return "1" if only the client area (interior) of a window/control will be saved; otherwise, will return "0" indicating the border and caption for the window/control will be included in the output. (added in PxPlus v11.50)
CascadeTextFont ¹ | Returns "1" if the current text mode font will be cascaded into subordinate windows as opposed to using the default text mode font.
CB_RB_TextFont ¹ | Returns which font will be used for Radio Button and Check Box text. Returns "1" if the system is set to display text using fixed text plain font. Default is to use the graphical font ("0").
CbxImage | (Windows Only) Returns the pathname to the image used to create Check Boxes on the screen. See Customizing Radio Buttons and Check Boxes. (added in PxPlus 2017)
CbxMarkSize | (Windows Only) Width of the space (in pixels) used to draw the Check Boxes in front of or following the text. Default is based on the height of one line. See Customizing Radio Buttons and Check Boxes. (added in PxPlus 2017)
ClrSelectIgnore | Returns "1" if using the Windows default display colors (white characters on blue) for a selected line in a List box/List view. Returns "0" if using the colors specified for the List box/List view contents. (added in PxPlus 2014 - Feature Pack 1)
Colournnn ¹ | RGB value or logical name for colour number (1 - 256).
Copy_1Line_NoCR | Returns the current setting of the Copy_1Line_NoCR option that controls the appending of a line feed at the end of single line copy. (added in PxPlus 2021 Update 1)
CTLList ¹ | List of CTL values currently present on the window. (added in PxPlus v6.30)
CurColor or CurColour | Current text color that is set by the last 'COLOR' mnemonic. (added in PxPlus 2021)
CurFont | Current graphic font that is set by the last 'FONT' mnemonic. (added in PxPlus 2021)
CurKno | Returns the current KNO value.
DateFmt | Returns the current specified Date format used to return dates for an ODB, MySql, OCI, DB2 or ADO database connection. If no DateFmt was specified for the channel, this will return a null string and you will need to consult that specific database documentation to determine the format it will return (generally YYYY-MM-DD hh:mm:ss.hhh). (added in PxPlus 2023)
DevHandle | Windows API device handle for communications port.
Device | Can be used with WINPRT or WINDEV devices to return the physical device name of the printer being used. (added in PxPlus v6.30)
DisableDummyPrinters ¹ | Returns "Y" or "N" based on whether you have included the option in the system INI to ignore the NUL: print driver interface.
DiskFIN | Can be used with a *PDF* file to obtain a Disk FIN( ) format return value instead of a Device style response. (added in PxPlus v6.30)
DoubleBfr ¹ | Controls the double buffering of screen updates on Windows. If set to "1", all screen updates are first done off-screen then copied on screen in a single update, thereby reducing flickering. The default setting is Off (0). (added in PxPlus v10)
Driver | PxPlus device driver name.
DropFiles ¹ | List pathnames of files that have been dropped onto a control/window from an external application. (added in PxPlus v7.00)
Extract | Extract status of file (1 if Extract pending).
FileLength | Size of physical file. (Includes the total size of all segments in a multi-segmented VLR file as of PxPlus v11.50)
Filename | Original filename used in OPEN.
File_Create | Returns file creation command for any PxPlus-based file.
Font | Window text font.
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. (added in PxPlus v6.30)
Frame ¹ | Returns the current window frame setting. Possible values are:
"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).
(added in PxPlus v7.00, build 9163.1)
FrameDarkClr ¹ | Colour of shadow line drawn by the 'FRAME' mnemonic. (Default: Dark Gray) (added in PxPlus v11.00)
FrameLiteClr ¹ | Colour of highlight line drawn by the 'FRAME' mnemonic. (Default: Light Gray) (added in PxPlus v11.00)
FrameTextClr ¹ | Colour of text header used by the 'FRAME' mnemonic.
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). (added in PxPlus v6.30)
GraphicFont ¹ | The window default graphic font, set to the last font setting using the 'GF' mnemonic. If not set, then the StdGraphicFont is used.
Graphics ¹ | Returns a printable list of currently active graphic mnemonics for the current window.
GrayDisabledBmp | Controls the display of images on disabled buttons. Returns "0" or "N" (Off) if the images on disabled buttons display only as shadows. This means that only the shadow left by the outline of the image is seen. Returns "1" or "Y" (On) if the images on disabled buttons are converted to gray scale. The default setting is "0" or "N" (image displays as a shadow). Example: (added in PxPlus 2017)
GridAlignLines | Returns "0" or "1", depending on the current setting. When enabled ("1"), any Multi-Line text (lines separated by line feed $0a$) in a Grid Button-style cell will have each line of text individually aligned as per the 'Align$ property. When disabled ("0"), the lines will be treated as a block of text, and that full block will be aligned as per the 'Align$ property. #### Note: This option was added in PxPlus 2017 with a default setting of enabled. (added in PxPlus 2017)
GridMLVersion | Returns the setting for the GridMLVersion option, which is used to set the behavior of the Enter key and the Up/Down arrow keys when editing a Grid cell with lines of Multi-Line text. Returns "1" (default setting) when Enter or Ctrl - Enter creates a new line, and the Up/Down arrow keys are used to move up/down between the lines of text in the cell. Returns "0" when Ctrl - Enter creates a new line, the Enter key enters/exits the cell, and the Up/Down arrow keys are used to move to other cells. (added in PxPlus 2019)
Handle | Operating system file handle.
HDC | Returns handle to the device context for a *WINPRT* channel.
HeightTextUsed | Returns the number of lines of print space used in the last Block print to a WINPRT or PDF file. (added in PxPlus v7.11)
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. (added in PxPlus v8.00)
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). (added in PxPlus v7.30)
HWND ¹ | (Windows/WindX Only) Returns the handle of the current window.
ICON | Window default icon image name.
Identifier_QUO | (ODB, Oracle, DB2, and MySql Only) 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. (added in PxPlus v8.00)
IMAGELIB ¹ | Returns pathname of current extended image library. (added in PxPlus v11.00)
IMAGELIST ¹ | (Windows/WindX Only) Returns a comma-separated list of active 'IMAGE' groups followed by a colon and the number of items in each group.
Input | Returns "1" if there is input available on the device. Returns "0" if there is no input available. Generally used only with physical devices and/or TCP channels. (added in PxPlus v10)
IO_Program | Program filename of imbedded I/O.
Journalized | Returns "1" if the specified file is being journalized; otherwise "0". (Must use the channel for the file you are inquiring about.) (added in PxPlus 2016)
KeyBoard ¹ | (Windows Only) Returns a four-character hex string containing the current keyboard language. (added in PxPlus v8.11, build 9182)
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.
LCL_CTime LCL_MTime LCL_ATime | These FIN functions return the files creation, modified, and last access time as a string consisting 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. (added in PxPlus v8.11, build 9182)
LockOverDisable | Returns "Y" if Multi_Line input fields that are both locked and disabled are set to display as locked (as opposed to disabled). Returns "N" if not set. (added in PxPlus 2023 Update 1)
LogFile ¹ | Returns the currently defined system log file as defined in the INI file or through the use of the 'OPTION'( ) mnemonic. When defining the log file, you can specify the maximum file size (in megabytes) that you want the log file to grow. See PxPlus Log File. (added in PxPlus v10)
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: Clicking the mouse on a fully transparent section of the window passes the mouse click to the window below. (added in PxPlus v7.00, build 9163.1)
MaxKno | Maximum file access key number allowable for the file.
MaxRec | Same as Records_Allowed.
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. (added in PxPlus v6.30)
MouseWheelCount ¹ | Current setting for the mouse wheel in terms of the number of Up/Sown arrows to emulate when using the wheel. (added in PxPlus v6.30)
MessageBar ¹ | Returns the height of the message (status) bar region at the bottom of the screen. (added in PxPlus v7.65)
Msg_Is_Tip ¹ | Returns the setting for the "Msg_Is_Tip" option, which, if set ("1"), automatically converts all MSG= values to TIP values.
Name | Same as Pathname.
NumRec | Number of records used.
Orientation | Can be used with a WINPRT or PDF device to obtain the current printout orientation of either LANDSCAPE or PORTRAIT. (added in PxPlus v8.00)
Output | Returns "0" if the device is not ready to receive any output data. Returns "1" if the device is able to receive some data (at least 1 byte). Generally used only with physical devices and/or TCP channels. (added in PxPlus v10)
Owner | Number of the object that owns the file (i.e. the object that issued the OPEN OBJECT directive for the file). (added in PxPlus v8.00)
PasteFilter | Returns the setting for the PasteFilter property. (added in PxPlus 2020 Update 1)
Pathname | Full pathname of file.
PDFFactor ¹ | Returns 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). (added in PxPlus v9.00, build 9200)
PDFFontDir ¹ | Returns the directory the system will search for true type fonts when creating PDF files. (added in PxPlus v9.00, build 9200.1)
PDFMargin ¹ | 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). (added in PxPlus v9.00, build 9200)
Port | Can be used with a WINPRT device to obtain the physical port being used for print job. (added in PxPlus v6.30)
Printer_Status | (Obsolete -- SCO Only) Returns printer status.
RbtImage | (Windows Only) Returns the pathname to the image used to create Radio Buttons on the screen. See Customizing Radio Buttons and Check Boxes. (added in PxPlus 2017)
RbtMarkSize | (Windows Only) Width of the space (in pixels) used to draw the Radio Button in front of or following the text. Default is based on the height of one line. See Customizing Radio Buttons and Check Boxes. (added in PxPlus 2017)
Record_Size | Maximum record size.
Records_Allowed | Maximum number of records.
Records_Used | Same as NumRec.
ResourceLib | Returns the pathname to resource library/libraries. As of PxPlus v11, the resource library value may contain multiple semi-colon (or comma) separated file names up to a maximum of 10.
RMouseCopy | 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 "1", the user can use the right mouse button to copy/paste text from/to the application. It is "0" by default. Its setting is automatically cascaded to subsequent windows. (added in PxPlus v8.11, build 9182)
Rsz | Same as Record Size.
Save_Msg_Bfr ¹ | If initially set to non-blank (by the SETDEV directive or 'OPTION' mnemonic) and a SAVE command is issued, this FIN value will return a list of errors that occurred during the SAVE function.
Separator | Field separator character or "*Dynamic*" for files with dynamic field separators.
SignalCaptionChg | Returns the CTL value that is generated when the caption changes on a window/dialogue. If null ("") or "0", then no CTL is generated when window caption changes. (added in PxPlus 2017)
SortImageList | Returns the setting for the sorting of all 'IMAGE' graphics groups by name. This sort order is used by the NOMADS Panel Designer to determine the order in which the graphics are drawn on a window. When the value is "1", the 'IMAGE' groups are sorted and drawn in alphabetical order by name on the current window. When a new 'IMAGE' group is created, it is inserted into the list of 'IMAGE' groups alphabetically. When the value is "0" (Default), the 'IMAGE' groups are drawn in the order they are created with the default group first followed by all subsequent groups in the order they were created. (added in PxPlus 2014.01 Update 0005)
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. (added in PxPlus v7.11)
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. Example: "7:Sheet,259:Sheet (Borderless),4:CD/DVD," (added in PxPlus v7.11)
SnapTo ¹ | Returns the window to which the current window will "SnapTo" when moved.
StdFont ¹ | Standard window text font.
StdGraphicFont ¹ | Standard graphic font. Can be set in the PxPlus INI file using the SystemFontName and SystemFontPoints parameters. See INI Contents. If not set, then the font set for the Windows graphical user interface, SysGuiFont, is used.
StdGridHideButtons | Returns the standard/default for the 'HideButtons property used for grids. (added in PxPlus 2020)
StdGridQueryImg | Returns an image pathname or internal image (!xxxxxx), which will be used as the image to display in the query/lookup buttons of a grid only when a grid is first created. An invalid value will result in the original ellipsis (...) being used. (added in PxPlus 2021)
StdSortOrder ¹ | The value provided defines the default column sort settings used by the LIST_BOX (Report View) and GRID. Possible values are:
Null | Uses StdSortOrder setting (if StdSortOrder not set, uses raw sort).
R | Raw binary sort.
C | Case insensitive sort.
A | Sort ignores accents.
N | Null values at end of sort.
CA | Ignore case and accents.
CN | Ignore case/Null values last.
AN | Ignore accents/Null values last.
CAN | Ignore case and accents/Null values last.
(added in PxPlus v11.00 and upgraded to a string value in v11.50)
Suppress_FF | Returns the file FF suppression settings, which will be one of the following values:
"NO" | No FF suppression. (Default)
"ALL" | Suppresses any 'FF' mnemonic if it will result in a blank page being produced. This setting will not suppress a 'FF' mnemonic at the start of a report where a leading 'FF' is often used to assure output starts at the top of a page. #### Note: PDF and WINPRT output will suppress a leading 'FF', as these by definition always start a report on a new page.
"FIRST" | Suppresses an 'FF' mnemonic if it is the first output to the channel. Only the first 'FF' is suppressed.
"LAST" | Suppresses a trailing 'FF' mnemonic that applications often send to eject the paper at the end of a report. It is always enabled on output to PDF files.
"BOTH" | A combination of "FIRST" and "LAST".
(added in PxPlus v9.00, build 9200)
SysGuiFont ¹ | Standard Windows graphical user interface font for controls.
SysMenu# | Returns the value of FIN (0,"SysMenu#") when adding a menu item to the system drop-down menu. This will return the current setting or "" if not set, or "<err>" will be returned if a non-numeric value for # is supplied. (added in PxPlus 2016)
System_Jrnl | Returns the pathname to the system journal if open; otherwise "" (must use channel 0). See SYSTEM_JRNL directive. (added in PxPlus 2016)
TextUsedHeight | When used with *WINPRT* or *PDF*, returns the number of graphical units the last 'TEXT' mnemonic used when formatted. See 'TEXT' mnemonic.
TipFont ¹ | Returns the current font attributes of the floating tip windows. (added in PxPlus v9.00)
TipTimerCycles ¹ | Defines the length of time (in tenths of a second) that a tip will be displayed. (added in PxPlus v8.30)
ToolBar ¹ | Returns the height of the toolbar (region at the top on the main window above window 0). (added in PxPlus v9.00)
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. (added in PxPlus v9.00)
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.
XYClient ¹ | Returns the width and height (in pixels) of the client region for the current window. (added in PxPlus v8.30, build 9190)
XYMonitors | Returns a list of monitors on the workstation. The returned list contains a string with a line feed ($0a$) separating strings describing each monitor on the system. The monitor strings contain a series of comma-separated values consisting of the logical device name followed by the co-ordinates of the top, left, bottom and right corners of the monitor. Example: print fin(0,"XYMONITORS") \\.\DISPLAY1,0,0,1920,1080 \\.\DISPLAY2,1920,0,3840,1080 (added in PxPlus 2014)
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. (added in PxPlus v7.00, build 9163.1)
XYPos ¹ or XYPos_NoChk | Returns four comma-separated numbers containing the absolute pixel address (top, left, bottom, and right) for the current window. These numbers are relative to the desktop of the workstation or the current window's parent window. (added in PxPlus v7.00, 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 is to the left. (added in PxPlus v7.00, 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. (added in PxPlus v8.11, build 9182)
ZIPFilename | Returns the file/directory name of the next ZIP archive entry. Directory names will always end in a '/' (forward slash). (added in PxPlus 2014)
ZIPInfo | Returns all of the metadata about the next file/directory entry in a ZIP archive. (added in PxPlus 2014)
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. (added in PxPlus v8.11, build 9182)
TCP-Specific Values
IPAddr | TCP/IP address.
Secure | Indicates if the current connection is secure (uses SSL or TLS) or not. If the connection is secure, the value "1" is returned; else "0".
SSL_Protocol | Returns the version of SSL currently in use on the specified connection. (added in PxPlus v11.50)
TLS | Returns "1", "1.1", "1.2" or "1.3" if TLS is enforced on connection. (TLS added in PxPlus 2017) (TLS 1.3 support added in PxPlus 2020)
X509_Issuer | Who issued the SSL certificate.
X509_KeyType | What type of key is in the certificate.
X509_Not_After | Latest date that the certificate is valid for.
X509_Not_Before | Earliest date that the certificate is valid for.
X509_Subject | Who the certificate is issued to.
Internal Use Values
CheckNews ¹ | Returns "1" if the used has requested News to be checked; otherwise "0".
LastCheckNews ¹ | Returns the time the news was last checked.
*ProcId=xxxx ¹ | Used in a WindX session to pass the process number to the WindX workstation so it will appear in the About box. (No return value - reading the FIN value sets the process ID.)
*Watch ¹ | When read, clears the Watch list (no return value).
Item Colours and Shading ¹ The following keyword$ values return colours to specific characteristics:
BtnDownBtmClr | Colour for blend at the bottom of pushed button.
BtnDownBtmPct | Lightness applied to face at the bottom of pushed button.
BtnDownMidClr | Colour for blend at in middle of pushed button.
BtnDownMiddle | Mid-point percentage from the top of pushed button.
BtnDownMidPct | Lightness applied to face in middle of pushed button.
BtnDownTopClr | Colour for blend at the top of pushed button.
BtnDownTopPct | Lightness applied to face at the top of pushed button.
BtnFaceClr | Button face colour.
BtnFocusHilight | Focus highlight.
BtnFrameClr | Button/Check Box/Radio Button frame colour.
BtnHoverHilight | Mouse Over highlight.
BtnNormBtmClr | Colour for blend at the bottom of normal button.
BtnNormBtmPct | Lightness applied to face at the bottom of normal button.
BtnNormMidClr | Colour for blend at in middle of normal button.
BtnNormMiddle | Mid-point percentage from the top of normal button.
BtnNormMidPct | Lightness applied to face in middle of normal button.
BtnNormTopClr | Colour for blend at the top of normal button.
BtnNormTopPct | Lightness applied to face at the top of normal button.
CbxMarkClr | Check mark or 'X' in a Check Box.
ClrAutoCompBack | The background colour to be used for text in auto complete List boxes. (added in PxPlus v9.00, build 9200)
ClrAutoCompText | The text colour to be used for text in auto complete List boxes. (added in PxPlus v9.00, build 9200)
ClrDisabledBack | The background colour to be used for text in disabled List boxes, Multi-Lines, Radio-button text and Check boxes. (added in PxPlus v9.00, build 9200)
ClrDisabledText | The text colour to be used for text in disabled List boxes, Multi-Lines, Radio-button text and Check boxes. (added in PxPlus v9.00, build 9200)
ClrHighlight ClrHighlightText | The background and text colours to be used to display currently selected items from a List Box or Drop Box and display the background and text in a Multi-Line when it has focus. If focus on the Multi-Line selects all of the text or if a portion of the inputted text is selected for Copy, Cut, Delete or Paste functions, then the selected text uses the standard Windows colour for selected text. (added in PxPlus 2017)
ClrPlusZ_SB_Back | Returns the background for any 'SB' data. (Default: Light Gray button face color) (added in PxPlus 2022 Update 1)
ClrPlusZ_SF_Back | Returns the background for any 'SF' data. (Default: White) (added in PxPlus 2022 Update 1)
ClrPlusZ_Text | Returns text. (Default: Black) (added in PxPlus 2022 Update 1)
ClrToolBar | Background colour for the tool bar. (added in PxPlus v9)
DrpBtnBackClr | Returns the background color for the Drop Box button. (added in PxPlus 2024)
DrpBtnDisableBackClr | Returns the background color of the Drop Box button when the Drop Box is disabled. (added in PxPlus 2024)
DrpBtnHoverBackClr | Returns the background color for the Drop Box button while hovering over it. (added in PxPlus 2024)
DrpBtnHoverTickClr | Returns the color of the down arrow/tick on the Drop Box button while hovering over it. (added in PxPlus 2024)
DrpBtnTickClr | Returns the color of the down arrow/tick on the Drop Box button. (added in PxPlus 2024)
FrameDarkClr | Colour of shadow line drawn by 'FRAME' mnemonic. (Default: Dark Gray) (added in PxPlus v11.00)
FrameLiteClr | Colour of highlight line drawn by 'FRAME' mnemonic. (Default: Light Gray) (added in PxPlus v11.00)
FrameTextClr | Colour of text header used by the 'FRAME' mnemonic. (added in PxPlus v11.00)
RbtMarkClr | Ball within a Radio Button.
StdFocusBackClr | Returns the background colors used to display currently selected items from a List Box or Drop Box and display the background color in a Multi-Line when the control has focus. (added in PxPlus 2018)
StdFocusTextClr | Returns the text colors used to display currently selected items from a List Box or Drop Box and display the text in a Multi-Line when the control has focus. (added in PxPlus 2018)
StdGridLineClr | Returns the standard/default line color used for Grids. Default is RGB: 220,220,220. (added in PxPlus 2020)
StdLvueHotlinkClr | (Report View Only) Returns the default hotlink column color for List Views. (added in PxPlus 2018)
StdLvueHoverBackClr | (Report View Only) Returns the background hover color applied system-wide for all List Views. (added in PxPlus 2018)
StdLvueHoverTextClr | (Report View Only) Returns the text color used when the mouse is over a row in a List View. (added in PxPlus 2018)
StdLvueLineClr | (Report View Only) Returns the standard/default line color used for report style List Views. Default is RGB: 220,220,220. (added in PxPlus 2020)
StdRowHilight1 | Colour to be used as the background of alternate rows in a List Box or Grid. (added in PxPlus v11.00)
StdRowHilight2 | Colour to be used as the second background of alternate rows in a List Box or Grid. (added in PxPlus V11.00)
TipArrowColor | Color to be used by HTML tips for the tip arrowhead and the underline below the tip title. (Default: Dark Red) For information on HTML Tips, see Defining an Info Tip. (added in PxPlus 2016)
TipColor or TipColour | Color to be used for non-HTML tips. If the 'TC' system parameter is set to -3 but the TipColor (or TipColour) setting is not defined, the default Windows color will be used. (added in PxPlus 2021)
The system will return the colours using their internal names as shown below:
Black |  | White |  | DarkGray |  | LightGray |
LightRed |  | LightMagenta |  | DarkRed |  | DarkMagenta |
LightGreen |  | LightCyan |  | DarkGreen |  | DarkCyan |
LightBlue |  | LightYellow |  | DarkBlue |  | DarkYellow |
or via RGB code (i.e. "RGB: n n n" where n=0-255)

¹ Indicates this option can only be used with channel 0

#### Note 1:
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 2:
UTC_ATime, UTC_CTime, and UTC_MTime (Universal Coordinated Time) values returned are OS dependent. 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 a list of available keywords, see '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). See PTH( ) Return Pathname.

## FIN( ) Contents

Three formats of FIN are provided, depending on whether the file is a Disk Resident, an External Database Table, 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 | (UNIX/Linux Only) Inode number
23,2 | (UNIX/Linux Only) User ID of file owner
25,2 | (UNIX/Linux Only) Group ID of file owner
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( ) 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 PxPlus.

FIN( ) - For External Database Tables Only

Doing a FIN(chan) on an external database table that was opened using [ADO], [DB2], [MYSQL], [OCI] or [ODB] will return key information.

Bytes | Description (for External Database Tables Only)
1,85 | Unused/Undefined
85,1 | Current access key number
86,128 | Key definition data See FIB( ) Keyed Files (bytes 85, 384) or use utilities to return key information (e.g. *UFI and **KEY.INF).

Example:

> x$=fin(chan)
> kno_num=dec(x$(85,1))
> key_def$=X$(86,128)

(Support to return key information on external database tables was added in PxPlus 2022 Update 1.)

FIN( ) - For Device Files Only (also Windows Printers *PDF* and *FAX*)

Bytes | Description (for Device Files Only) (TCP files are reported as devices)
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 | (Windows Only) Operating system handle
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 Create New File from File Descriptor
'FF' File Format
'PO' Path Original

BBx® is a registered trademark of BASIS International Ltd.