FnSnap: Screen Processing

Buttons, messages and dialogs

FNBUTTON - Add button on the button bar

Creates a button on the button bar. Buttons are created left to right and can be removed with FNCLRBUTTON

FNBUTTON(BUTTON_TEXT$,FK;BTN)

Functions used

Variables

BUTTON_TEXT$	Text to display on button. Must be less than 10 characters
FK	Function key value to return when the button is pressed
BTN	Button number if an existing button is to be changed. If this parameter is omitted the next button position will be used.

Comments

FNCHECK - in connection with a radio dot or check box returns a 1 if checked

Used to process the elements of a radio dot list or check box is to determine wether the element has been checked (true) or not (false)

 FNCHECK(L$*100)

Functions used

Variables

L$	The label description being processed for an element of a radio list or check b ox list

Comments

This function is intended to be used by other functions see for example FNOPTIONS and FNOPTIONS$

FNCHECK$ - places or strips ^ from an element

Based on the results of FNCHECK or a default parameter this function will add or remove the ^ from a description that indicates if it has been checked

Returns the label modified to either contain or be free of a leading ^.

FNCHECK$*100(L$*100,L)

Functions used

Variables

L$	The label description to be modified if L is true
L	A flag indicating whether the ^ is to be appended to the front of a label, or stripped from it

Comments

Used as a part of FNOPTIONS and FNOPTIONS$

FNCLRBUTTON - removes a button from the button bar

Removes a button from the button bar if it was created using FNBUTTON

FNCLRBUTTON(;BTN)

Functions used |

Variables

BTN	The number of the button to be cleared. If blank the last, highest number, button will be cleared. If equal to 99 all buttons will be cleared.

Comments

Use in connection with FNBUTTON to display and remove buttons left to right on the button bar.

FNDIALOG$*40 - Display dialog box and return selected text

Displays a dialog box with up to three options and specifiable text. See also FNDLG

FNDIALOG$*40(SROW$,SCOL$,DBWIDTH,TXTSTR$*900,OPT1$*40,OPT2$*40,OPT3$*40,REMOVE,DFLTOPT,DISPANYKEY,KEYWAIT) !:

Functions used |

Variables

Comments

Text does not align very well in the box when using proportional fonts. This function can be called from FNDLG that uses an unformatted BR file to supply text and button labels. Both functions have been updated to utilize the external utility from David Blankenship.

See also FNWAITWIN for a very useful alternative.

FNDLG - Display a dialog box from data in a file

Creates a dialog box from a DAT file prepared by DIALOGMN.BR

FNDLG(DIALOG_DAT,DLNR;DISPANYKEY,KEYWAIT,SUFFIX$*300)

Functions used

FNDIALOG

Variables

DIALOG_DAT
DLNR
DISPANYKEY
KEYWAIT
SUFFIX$

Comments

This is a carry over from earlier versions and does not align proportional text very well. If possible use MSGBOX instead.

The function has been updated to use the message box utility from David Blankenship if RADIOCHK.exe is in the VOL002 directory

With version 4.2 the function FNWAITWIN and rel;ated functions FNWAITMSG and FNWAITBAR are much more flexible and provde a Windows look message box with custom buttons, a progress bar and optionsl message flashing across the wait window as processing progresses.

FNHELP - open a tip box associated with a screen using a text file

Searches a specified text file for an anchor point, then displays a record after that point specified by HFLD. Used for displaying pop up help windows based on the input field where the cursor is located

[PICT(PICS\SNAP0007.ptf)]

FNHELP(HPATH$*60,HFILE$*20,HBASE$,HFLD,HROW,HCOL;HTITLE$*80)

Functions used

Variables

HPATH$	Path where the help file is located
HFILE$	File name within HPATH$ for the help file
HFLD	Field number, usually set by CURFLD except in GRIDs it should be set by CURCOL.
HROW	Current row position of cursor, used to help in the positioning of the help window. Usually set by CURROW
HCOL	Current column of cursor, used to help in the positioning of the help window. Usually set by CURCOL
HTITLE$	An optional title to appear in the bar at the top of the help window.

Comments

Very flexible and easy to implement help system. I uses David Blankenship's HELPTIPS.exe utility.

FNHELPTIP - uses David Blankenship utility to display a help record

Displays a record from a text file in a pop up window. Used in the BR system by the ERRORS routine to display the description of an error number.

FNHELPTIP(PROGPATH$*100,TEXTFILE$*50,TITLE$*50,RECORD,HROW,HCOL;NO_WAIT)

Functions used

Variables

PROGPATH$	Path where text file is located.
TEXTFILE$	Name of text file within the specified path
TITLE$	Name to be displayed at the top of the pop up window
RECORD	The record number within the text file to display as the text of the message.
HROW	A positioning variable generally set by CURROW
HCOL	A positioning variable generally set by CURCOL
NO_WAIT	Ignored

Comments

If HROW and HCOL are zero then the window id positioned in the center of the screen.

FNOK - Pop-up "OK" question

FNOK

Description|
Displays a dialog box with OK yes or NO. If yes is returned FNOK is true else it is false

Functions used |

Variables

Comments

MSGBOX is probably a better option with current programs

FNOPTIONS - creates a radio dot selection pop up

Displays a pop up radio dot selection window. If David Blankenship's utility RADIOCHEK.exe is present that will be used. If not present then a BR generated selection window will be generated.

[PICT(PICS\SNAP0005.ptf)]

FNOPTIONS(MAT O$;DEFAULT,TITLE$*100,MESSAGE$*1000,WAITTIME,SROW,SCOL)

Functions used

FNRADIOCHK

Variables

Mat O$	Matrix containing the descriptions for each line in the list
DEFAULT	A number indicating which radio dot item should carry the dot when the box is displayed
TITLE$	A title to appear across the top of the list box.
MESSAGE$	A message to appear in a separate part of the dialog box explaining the choices if appropriate.
WAITTIME	Number of seconds that the list should be displayed before accepting whatever is checked and continuing.
SROW	Positioning parameter generally set by CURROW
SCOL	Positioning parameter generally set by CURCOL

Comments

FNOPTIONS$ - creates a check box selection pop up

Similar to FNOPTIONS, but this function displays the information in the form of a multiple selection check box list.

[PICT(PICS\SNAP0006.ptf)]

FNOPTIONS$*100(MAT O$;DEFAULT$*100,TITLE$*100,MESSAGE$*1000,WAITTIME,NONE)

Functions used

FNRADIOCHK

Variables

DEFAULT	A number indicating which radio dot item should carry the dot when the box is displayed
TITLE$	A title to appear across the top of the list box.
MESSAGE$	A message to appear in a separate part of the dialog box explaining the choices if appropriate.
WAITTIME	Number of seconds that the list should be displayed before accepting whatever is checked and continuing.
NONE	A flag that will allow no items to be selected, otherwise the check list may not be exited without at least one selection being made.Positioning parameter generally set by CURROW

Comments

FNPFKEYLINE - Creates a hot field string of function key options

See also FNWINBUTTONS for 4.17+

Prints a function key message line in an open window or child window at the row specified. Function keys displayed are hot and return the Fkey value. Fkey references can be hot text or optionally buttons.

[PICT(PICS\SNAP0009.ptf)]

FNPFKEYLINE(ROW,TXT$*80;FKWIN)

Functions used

Variables

ROW	The row number of the window on which the line should be displayed. Negative number indicate that many rows UP from the bottom of the window. Zero "0" indicates the very bottom of the window. All messages will be right justified within the window.
TXT$	Text to be displayed. Function keys should be designated with a leading carat ^ and trailing double space such as "^Esc End"
FKWIN	Window number in which the line should be displayed

Comments

Valid function keys are numbers beginning with "^F" such a ^F9, or abbreviations for keys including ^PgUp ^PgDn ^Esc and ^Enter. These are not case sensitive. See also FNWINBUTTONS for a GUI based alternative.

FNPFKEY - Prints a function key message

FNPFKEY(R,C,F$,TXT$*78) !:

Description|
Prints a function key message on window zero

Functions used

Variables

R	Row number
C	Column number
F$	Function key to be displayed
TXT$	Message to be displayed next to the function key

Comments

Displays only one function key message at the row and column of window #0 specified. FNPFKEYLINE is more flexible and recommended.

Effective with GUI mode and release 4.17 FNWINBUTTONS and FNPICBUTTONS are much better options.

FNRADIOCHK$ - display a radio/checkbox with a set of options

Used by FNOPTONS and FNOPTIONS$ and FNDLG to display radio dot list, check box list, or a dialog box. Makes use of David Blankenship's RADIOCHK.exe utility.

FNRADIOCHK$*100(CAPTION$*80,INFILE$*60,LEFT,TOP,ALLOW,DEFAULT$*100,TYPE$,LOCATE,NOCOLS,COLWIDTH,WAITTIME;TEXTSTRING$*2400)

Functions used

Variables

CAPTION$	Title for the top bar
INFILE$	File name to be processed
LEFT	Position form left of screen to display in pixels
TOP	Position from the top of the screen in pixels
ALLOW	allows no responses if true, requires at least one if false
DEFAULT$	A string of 0 and 1 where 0 is not checked and 1 is checked
TYPE$	R for Radio C for Check box
LOCATE	Record number in file to use as data for a dialog box
NOCOLS	Number of columns to display
COLWIDTH	Width of columns or buttons. If not provided the spacing will be automatic based on the length of text provided
WAITTIME$	Number of seconds to wait before returning the default answer.
TEXTSTRING$	Text to display in a dialog box if not using text from a file.

Comments

FNRADNUM - Return the option selected in a radio dot list

FNRADNUM(MAT V$)

Description|
Function determines which in a group of radio buttons was selected and returns the element number

Functions used |

Variables

Comments

FNTIMEOUT - Display timeout message

FNTIMEOUT(;SECONDS)

Description|
Displays a message that input has timed out and waits for a keystroke to reactivate the program.

Functions used |

Variables

Comments

FNWINBUTTONS - print one or more buttons on a screen in a designated window

Similar to and a replacement of FNPFKEYLINE. Prints one or more buttons, right justified in a designated window either BROWs down from the top of the window if BROPW is positive of BROWS up from the bottom of the window if BROW is zero or negative.

[PICT(PICS\SNAP0002.ptf)]

DEF LIBRARY FNWINBUTTONS(BROW,BTEXT$*100;BWIN,CENTER,FONT$)

Functions used

FNWINROWCOL

Variables

BROW	The row number within a window on which to place the buttons. If 0 or negative the row is up from the bottom of the window, positive is down from the top.
BTEXT$	The text to display within the buttons. Each button is designated with a ^followed by FX: where X is the fkey value to be returned when the button is pushed. FX can also be PGUP, PGDN or ESC. The^FX: is followed by the text to appear within each button. Al buttons are dimensioned to the longest string provided for any button.
BWIN	The window number of the window within which the buttons should appear.
CENTER	The default is zero (0) which right aligns the buttons on the right hand border of the window. To center the buttons horizontally in the window enter one (1) in this element.
FONT$	If this element is blank the default BUTTONS font will be used for the WINBUTTONS. Entering an alternative font can allow wingdings or directional arrows if the font allows it. An example would be specifying TERMINAL on a Windows machine and then usinrt chr$(16) and chr$(17) next to the word Right or Left.

Comments

Can only be used in GUI ON mode

String Manipulation

FNDECRYPT$ - Decrypt FNENCRYPT$

Undoes what FNENCRYPT$ does

FNDECRYPT$(PW$)

Functions used

Variables

PW$	The encrypted password from FNENCRYPT$. This is usually a stored value to be compared with an entered value

Comments

This is a simple encryption routine only meant to hide a value from a casual observer, not a dedicated hacker. A more robust encryption routine is available with George Tisdale's WORKMENU.br menuing system.

FNENCRYPT$ - Simple encryption

FNENCRYPT$(PW$) !:

Description|
Simple encryption routine to ward off SNOOPS, NOT serious hackers

Functions used |

Variables

Comments

This is a simple encryption routine only meant to hide a value from a casual observer, not a dedicated hacker.

FNFKEY - Converts an FKEY value greater than 1000

Returns a function key value. If the value would be greater than 1000 then only the right tree places are used to determine the number. Useful in converting button FKEYs to hot text fkeys

FNFKEY(AKEY)

Functions used

Variables

AKEY	An FKEY value to be reduced by 1000 and returned as the value of FKEY. If AKEY is less than 1000 the value of AKEY will be returned

Comments

Use in conjunction with FNPFKEYLINE

FNNUM$ - Convert number to string

FNNUM$(NAMT,DCML,LNGTH) !:

Description|
Converts a number to a character string with fixed decimal places. CNVRT$ is a better option.

Functions used |

Variables

Comments

FNPHONE$ - Convert number to (###) ###-####

Formats a 10 digit number into a telephone number formatted string

FNPHONE$(X)

Functions used |

Variables

X	Numeric telephone number including a leading "1"

Comments

FNPROPER$*60 - Convert to Proper Case

Converts a string into an initial capital title or name case

FNPROPER$*60(A_IN$*60) !:

Functions used |

Variables

A_IN$

String that is to be converted to initial capitals

Comments

The function uses a lot of SREP$ statements, consequently the string passed should be short enough to not cause a string overflow. About 500 characters is a reasonable limit.

Other

FNAUTO - 1 if last field exit was automatic

Returns a 1 (true) if the last field was exited with an automatic exit Attribute E or X LASTFIELD is the field # that was current

FNAUTO(LASTFLD) !:

Functions used |

Variables

NONE

Comments

FNCLKBUF - Clear keyboard buffer

Clears the keyboard buffer

FNCLKBUF ! Clear the keyboard buffer

Functions used

None

Variables

None

Comments

FNERRTRAP - Trapped Error Processing

Red Screen error trapping routine. Displays error, program line and number to call. Also logs the error to a log file by workstation and creates an email message

FNERRTRAP(EPROG$*50,ELINE,EERR,ECOUNT,EVARIABLE$,&ECURFLD,EMENU$)

Functions used |

Variables

EPROG$	Program name where the error was generated
ELINE	Line number where the error occurred
EERR	Error number that occurred
ECOUNT	Variable count if appropriate to the error
EVARIABLE$	Name of the variable, if appropriate where the error occurred
ECURFLD	Current field where the error occurred if in full screen processing
EMENU$	The menu to which the program should return if the error can not be resolved
EMENUSEQ$	The menu Sequence to which the program should return if the error can not be resolved.

Comments

Requires FNEMAILFILE and EmailBlaster or EmailMonitor

FNINIT - Initialize variables in FNSNAP Library

Initiates the variables for the FNSNAP library. Be careful not to use more than once in a program

FNINIT(;SYSDIR$,SYS$)

Functions used

Variables

NONE

Comments

Initializes variables for the older FNSNAP tools. If run in the middle of a program the variables will be reset to the initial values and may cause problems. Most new functions being written should NOT use this function.

FNPRINTSCREEN - stuff the keyboard to generate a print screen

Programmatically controls the keyboard to do the equivalent of Ctrl-P to issue a print screen

FNPRINTSCREEN

Functions used

Variables

None

Comments

FNZERO - set to number if zero

FNZERO(V,DV) ! SET Variable equal to the Default Variable if zero !:

Description|

Screen input and display

FNMOD - returns the column number of a cell in a grid

Replaced by CURCOL in 4.17. Returns the column number of the current cell

FNMOD(CEL,COLS)

Functions used

Variables

CEL	The cell number where the cursor is located
COLS	The number of columns in the grid

Comments

FNPARSERES - returns screen resolution and BR window size for a session

Converts

FNPARSERES(W$,MAT SCRNRES,MAT WINRES,MAT CONRES)

Functions used

Variables

W$	The workstation ID being queried
MAT SCRNRES	Two element array of current terminal rows and columns in pixels
MAT WINRES	Five element matrix 1 0 is maximized ("M-") 1 is windowed ("A-")2 rows in pixels of window 3 columns in pixels of window 4 row position of upper left corner in pixels of window 5 columns position of upper left corner in pixels of window
MAT CONRES	Five element matrix 1 0 is maximized ("M-") 1 is windowed ("A-")2 rows in pixels of window3 columns in pixels of window 4 row position of upper left corner in pixels of window5 columns position of upper left corner in pixels of window

Comments

Uses Steve Koger's RESOLUTION.exe utility

FNPROGRESS - Progress bar

FNPROGRESS(&PCT_WINDEV,PCT_TOTAL,PCT_DONE;SR$,CAPTION$*55)

Description|
Displays a progress bar that expands based on numbers passed to the function

Functions used |

Variables

Comments

FNSCREEN - 24 x 80 screen display for screen painter

FNSCREEN(SCRNO;SCREENFILE,MAT SCRATR$,MAT SCREEN$,MAT INWRK$,MAT INFLDA$,MAT INWRKH$,NOPAINT) ! Retrieve and display screen

Description|
Displays a generated screen in the full screen window 0. Screen was created using SCREENMN in a 23x80 format.

This function has been significantly changed by NEWSCREEN.dll

Functions used |

Variables

Comments

FNTEXTBOX - creates a text box with word wrap

Displays and allows input from a windows text box with text

FNTEXTBOX$*4000(&TEXTWIN,SROW,SCOL,ROWS,COLS,TLEN,PARENT,TEXT$*4000;BORDER,TKEY$)

Functions used

Variables

TEXTWIN
SROW	Starting row within the parent window where the upper left corner should appear
SCOL	Starting column number within the parent window where the upper left corner should appear
ROWS	Number of rows the text box should cover
COLS	Number of Columns the text box should cover
TLEN	Allowable length of the text
PARENT	Parent window number
TEXT$	Text to display. Modified text will be returned as the value of the function
BORDER	Zero for no border or any other number to create a single line border
TKEY$	Function key to return if the window is to be marked as hot

Comments

FNWINSCRN - paints a screen in a window

FNWINSCRN(SFIL,SCRNO,WINNO,WINLIN,WINLEN,MAT SINFLDA$,MATSHELP$;DISPLAY) !:

Description|
Displays a generated screen in an open child window of specified size. The generated screen was created using SCREENMN

This function has been significantly changed by NEWSCRN.DLL

Functions used |

Variables

Comments

FNWINROWCOL - in GUI mode returns rows and columns of a window

Must be in GUI ON mode to use this function. Returns the number of rows and number of columns in the specified window. the values returned are actually one shorter than the actual size of the window.

FNWINROWCOL(WINNO,&WROWS,&WCOLS)

Functions used

FNWINSIZE

Variables

WINNO	Window number for which information is requested
WROWS	Number of rows less one of the requested window
WCOLS	Number of columns less on of the requested window

Comments

FNWINSIZE - in GUI mode creates arrays holding all window sizes

Returns arrays carrying dimensions for all open windows

FNWINSIZE(MAT S_WINNO,MAT S_SROW,MAT S_SCOL,MAT S_EROW,MAT S_ECOL,MAT S_ROWS,MAT S_COLS,MAT S_PARENT)

Functions used

Variables

MAT S_WINNO	Array is dynamically populated with window number information
MAT S_SROW	Array is dynamically populated with starting row number
MAT S_SCOL	Array is dynamically populated with starting column number
MAT S_EROW	Array is dynamically populated with ending row number
MAT S_ECOL	Array is dynamically populated with ending column number
MAT S_ROWS	Array is dynamically populated with the number of rows in the window
MAT S_COLS	Array is dynamically populated with the number of columns in the window
MAT S_PARENT	Array is dynamically populated with the number of the parent window

Comments

this is the working function for FNWINROWCOL