CDS069 - Input Routine

CDS039 & CDS069

Input Routine

CDS039 and CDS069 are routines used for data entry that:

Provide instructions to the operator for the entry to be made
Display a mask at the entry point indicating the number of characters and type of characters to by entered
Process all keystrokes
Display a list of valid options when appropriate
Validate the completed entry
Format the entered data
Display a related field when applicable
Supports "Hotkey" capability where user can temporarily run another application and return back where they were
Record keystrokes and save them for automated playback

Due to the length of this document, the Table of Contents is provided below with links to pertinent sections.

Program to Use (CDS039 vs. CDS069)
Calling Format

Data Entry Types
    Prompt Only
    String
    Masked Numeric
    Un-masked Numeric
    Dates
    Password
    Window (Notepad)
Prompt Options
    Prompt Window
    Help Text
    Prompt Examples
Validation Types
    Simple list validation
    List validation with related field
    File validation
Special Keys
    Extended Exit Option
    Prompt Key Option
    Interrupt Option

Global Variables

Program to Use (CDS039 vs. CDS069)

CDS039 and CDS069 provide the same functionality. The choice of which routine to use is dependent on what type of variable is used to store the entered data.

Program to use	Data stored in a:	Examples:
CDS039	any template field	`CM01.NAME$, IM21.QTYONHAND, SO60.SALES[12], S265.MTHL$[MONTH]`
CDS069	simple numeric variable	`QTY`
CDS069	simple string variable	`ITEMNO$`
CDS069	element in numeric array	`SALES[MONTH]`
CDS069	numeric or string stored in a sub-string	`H$(2,8)`
either	Window (Notepad) text	Notepad text is stored in a disc file by these routines, and is not returned to the calling program

Although this text includes many examples, run program CDT069 to simulate many additional examples.

User oriented help can be displayed at any entry, by touching the F3 key then selecting Data Entry Help.

Calling Formats:

CALL "CDS069"{, ERR=XXXX, MINV, MAXV, COL, ROW, PROMPT$, TYPE$, NUMV, STRV$, TIMEOUT, VAL[ALL] } CALL "CDS039", ERR=XXXX, MINV, MAXV, COL, ROW, PROMPT$, TYPE$, REC$, FLDNAM${, INDEX, TIMEOUT } CALL "CDS039", ERR=XXXX, S039$, REC$

CDS039 & CDS069

ERR=XXXX

These routines will EXIT ERR when:

TIMEOUT is passed as a non-zero number, and no entry is made within the computed number of seconds. See TIMEOUT below for additional details.

TYPE$ includes the "E" or "e" character and the operator touches the interrupt key, typically Ctrl+C on Linux/Unix/AIX servers, or Ctrl+Break when running Visual Pro5 on the local PC, or clicks the Close icon (red X on Windows, red circle with X on Mac, etc.) for BBj programs.

MINV

Minimum Value - usage varies with TYPE$.

For numeric entries, MINV is the lowest numeric value permitted.

For string variables, MINV is the minimum number of characters that may be entered.

For date entries, the minimum valid date in julian format can be used. In order to be compatible with older applications, the minimum 2, 3, or 4 digit year can also be passed which will allow dates of January 1 of the year passed or later to be entered.

Note that passing a 2 digit year implies 19xx and not 20xx. When a 3 digit year is passed, then the 1900 is added to the year. For example 100 becomes 2000, 101 becomes 2001. This enables logic that adds a value to a 2 digit year to work properly. Passing 0 allows any minimum date.

MAXV

Maximum Value - usage varies with TYPE$.

For numeric entries, MAXV is the highest numeric value permitted.

For string variables, MAXV is the maximum number of characters that may be entered.

For date entries, the maximum valid julian date can be used. In order to be compatible with older applications, a 2, 3, or 4 digit year can also be passed which allows dates of up to December 31 of the year passed to be entered.

Note that passing a 2 digit year implies 19xx and not 20xx. However, in order to prevent changes to application programs that pass 99 as the maximum year, 99 is interpreted as no limit and not 1999. 3 and 4 digit years work the same as the minimum value. If Z2 is passed as 0 then no upper limit on the date is set.

COL

Horizontal Window Position

Horizontal cursor position within current window where entry is to be made.

ROW

Vertical Window Position

Vertical cursor position within current window where entry is to be made. Note that if COL and ROW are both passed as zero, the entry position will follow the prompt at the bottom of the window.

PROMPT$

The message to the operator describing entry to be made.

The prompt is displayed in the bottom one or two lines of the window/screen. If the active window is a full screen window, then CDS069 will use the bottom two lines, otherwise, CDS069 will use the last line of the window unless the prompt is so long that it requires two lines. For this reason application programs should not use the bottom lines for any other purpose. If the bottom lines of the screen are used for other information, then use the prompt window type prefix described below. When not using the prompt window option, CDS069 assumes these line(s) are blank when called, and clear them when exiting.

The complete format of PROMPT$ is "!+prompt-+{HELPFILE,HELPID}"

Certain shorthand options are available within PROMPT$. If the first character of PROMPT$ is an exclamation point (!), then the routine will ring the bell and display the "Invalid Entry" error message before entry. This option is useful when the calling program performs additional checks outside of the scope of CDS039/69.

If the next character is a plus (+), then the word "Enter " or the word "Touch " is added to the front of PROMPT$. Enter is used in most cases, since the operator is required to use the Enter key at the end of the entry.

The user prompt will include F3=Help when there is a help text reference at the end of PROMPT$ in the format {HELPFILE,HELPID}. Refer to the Help Text section below for details.

If the trailing character of PROMPT$ (before the help text reference, if any) is "+" then 'F4=End' will be added to the prompt. Software originally written for MAI Basic Four terminals with a Motor Bar IV key, containing the phrase ' OR CTL IV' will be replaced with 'F4=End'.

If the next to the last character of PROMPT$ is "-" then 'Enter=Continue' will be added to the prompt.

For a single character entry that does not require the operator to touch the Enter key, specify MINV and MAXV as -1.

CDS039/69 will underline key names when followed by '=' including Enter=, BackSpace=, Fn=, Home=, End=, PageUp=, PageDn=, ArrowUp=, and ArrowDn=.

CDS039/69 permits the operator to exit using the ArrowUp or ArrowDn keys, even when they are not included in the prompt. The system CTL variable will be set to 3 for ArrowUp, and 2 for ArrowDn. This enables the operator to move up and down a list of fields as would be done when maintaining fields in a Standard View.

F2=Display will be added to PROMPT$ automatically for list and file verified entries. For other entries, you may include another F2= clause in the prompt which will exit to the calling routine with the system CTL variable set to 2, if the operator touches the F2 key.

The F1 function key is reserved for the HotKey and cannot be used by the application.

The F3 function key is reserved for Help, and cannot be used by the application, although special context sensitive help is enabled using braces at the end of the prompt. The format is
When the prompt includes function keys F5= through F12=, then CDS039/69 will allow entry of the function key specified and set the CTL value to 100 plus the function key value, i.e., 105 thru 112.

The prompt can also contain a ring bell ('RB') and clear input ('CI') mnemonics.

See Prompt Field Examples.

TYPE$

A complex variable that controls the type of entry to be made. There are up to three parts of TYPE$: the main type, one or more prefix codes, and suffix parameters. Each of the segments of the type are presented in table form then described below in further detail.

Click on the individual type or code in the following charts for the full definitions.

Main Type

Type	Description	Prefix Codes	Additional parameters
A/a	Alpha-numeric	yes	optional
H/h	Used automatically for "A" types that do not fit in window	yes	optional
L/l	Left justified	yes	optional
R/r	Right justified	yes	optional
*	Password	yes	optional
Mask	Numeric masked, i.e., 000, -##,###.00, $###.00CR, etc.	yes	optional
Nxx.y	Un-masked Numeric	yes	optional
D/d	Date in MM/DD/YY format	yes	optional
S/s	Date in YYMMDD format	yes	optional
J/j	Date in bbx julian format	yes	optional
M/m	Date in Microsoft julian format	yes	optional
C/X	C or X type external called routine	no	required
W	Window (Notepad) Entry	no	required

Optional Prefix Codes

Code Description

E Abort/Escape Option. Adds Ctrl+C=Abort to prompt, and takes ERR= branch if operator touches Ctrl+C

P/p

Prompt Window options

Full Size Window	No P/p used	Prompt uses bottom two display rows, and clears upon exit.
Full Size Window	P or p	Prompt uses bottom two display rows, but uses a window for the prompt so that anything displayed there will re-appear when CDS069 exits.
Smaller Window Active Example	No P/p used	If the prompt fits on a single row, the prompt uses bottom row of active window, otherwise it will use the bottom 2 rows. These rows are cleared when CDS069 exits.
	P (upper case)	The prompt will appear at the bottom of the display in a separate window, using the main window display colors.
	p (lower case)	The prompt will appear at the bottom of the display in a separate window, using the active window's display colors.

Upper Case - entries made in lower case will be shifted to capital letters for display and the returned entry. Useful for Alpha Sort Name fields used to sort names.

Note: this option is not required for list verified entries such as for Y or N. When the user entry is not in the list, CDS069 will automatically check if the upper-case entry is in the list, and capitalize the entry and returned field. Type AYN can be used, and UAYN is not required.

F/f/g File validation

Q Format and display data and any related fields only. No data entry.

q No display nor entry, formatted data and any related fields are returned in SMS_CDS069_DIS global for use with PRINT option of T Type External routines. Global includes positioning expressions.

Suffix Parameters

Simple string validation

Complex string validation

File validation

External call parameters

Extended exit parameters

Window parameters

The "Entry Type" field is constructed by combining: None, One, or more Prefix Codes Main Type Leading parameters { Additional parameters } Trailing parameters

In most cases, one or more of the segments of the "Entry Type" will not be used.

NUMV (CDS069 only). Value where numeric entry is returned. Also used as length of string entries, and index to element number in a numeric array.

STRV$ (CDS069 only). Value where string entry is returned.

TIMEOUT

Used to indicate that CDS039/CDS069 should EXIT and take ERR= branch when no operator entry is made after a period of time controlled by TIMEOUT. Note that if F4 is a valid entry, then CTL will equal 4 upon timeout. This may simplify programs that call CDS039/CDS069 so that the IF CTL=4 logic can be used when the entry times out.

0	Timeout option not used
1-4	Timeout in minutes
5-32,767	Timeout in seconds

VAL[ALL] (CDS069 only). Numeric array. Value entered will be stored in VAL[NUMV].

REC$ (CDS039 only). Templated data structure containing field named FLDNAM$.

FLDNAM$ (CDS039 only). The field name in REC$ for entry.

INDEX (CDS039 only). Used when FLDNAM$ is a repeating field, as in REC.SALES[MONTH]. Value will be stored in REC.FLDNAM$[INDEX] or REC.FLDNAM[INDEX].

Prompt Field Examples

CALL "CDS069",1,10,0,0,"+Data","A",0,Z$

Enter Data __________

CALL "CDS069",1,10,0,0,"+Data+","A",0,Z$

Enter Data, F4=End __________

CALL "CDS069",1,10,0,0,"Enter Data, 
		F4=Abort","A",0,Z$

Enter Data, F4=Abort __________

Example of context sensitive help option.

CALL "CDS069",1,3,0,0,"+Product 
		Class{XXSK57,PRODCLASS}","R",0,PCL$

Enter Product Class, F3=Help ___

If PROMPT$ contains 'CR' such as in the phrase HIT 'CR' TO CONTINUE, then CDS069 will replace the phrase with Enter=Continue. _____ This is because most terminals label the Carriage Return key as Enter, or with the down and left pointing arrow. Some keyboards are labeled 'Return'. It is recommended that programs be written using a format such as "Enter=Continue" or "'CR'=CONTINUE".

In addition it is recommended to use a phrase such as "'Enter'=Continue" as opposed to HIT 'CR' TO CONTINUE to be consistent with other key=meaning phrases.

The Enter key accepts the current or default entry. This presents a conflict to CDS069 whenever there is a 'CR' or Enter= option that previously returned a null string but now causes the current or default entry to be accepted. When this situation occurs, CDS069 replaces the 'CR'= or Enter= prompt with SpaceBar=.

Note that this situation only occurs when there is a default entry.

CALL "CDS069", 1, 6, 10, 5, "+Customer#, 'CR' to enter Alpha Sort+", "R", 0, A$will present a prompt: Enter Customer#, 'CR' to enter Alpha Sort, F4=End when the A$ variable is passed to CDS069 as null or all blanks. But will present a prompt:
Enter Customer#, SpaceBar=enter Alpha Sort, F4=End if A$ has any non-blank characters.

If the operator touches the SpaceBar as the first character, then A$ will be returned as null and the calling program need not be changed. The operator does not need to touch the Enter key in this case.

A phrase is added to the prompt when string or file validation options are used. This prompt is "F2=Display" and signals the operator to touch F2 to display the list of valid entries. Note that the operator may enter some data followed by F2 to begin display of file verified options at that point in the file. The F2=Display phrase is omitted when using single character string validation, such as for a Y/N entry, but the F2 key still causes the valid options to be displayed.

Another phrase is automatically added to the prompt when using the abort option described below. On Unix systems, Ctrl+C=Abort is used, on DOS systems Ctrl+Break is used.

If the amended prompt is too long to fit on one line of the window, then CDS069 will split the line at an appropriate place so that the last two lines of the window are used. The programmer need not be concerned with the length of the prompt, other than fitting somehow on two lines. Older versions of CDS069 permitted the programmer to specify the place to split the prompt by using the backslash (\) key. This option is no longer supported and the \ character will be treated as part of the prompt. Backslash characters intended for this purpose should be removed from the prompt.

If there is context sensitive help available for this entry, then you inform CDS069 by specifying the help text file, and text ID within braces at the end of the prompt. Note that the Help text braces must follow the shorthand designations - and +". CDS069 will add the phrase F3=Help to the prompt and display the help text if the operator touches the help key. F3 was selected as the help key since that is the key that WordPerfect uses for help. It seems that most PC based software has been using F1 for help. This help key may be changed using operator preferences in a future release of CDS069.

CALL "CDS069", 1, 9, 0, 0, "+ControlCode+{DSSK54,CONTROL}", "0", Xwill yield a prompt: Enter Control Code, F3=Help, F4=End

Help Text Maintenance, stored in the default file of XXSK57 is available on the FMS menu. CDS069 will substitute XX in the help text file name with the current company code if necessary.

CDS069 will display the function and editing keys underlined whenever the key is followed by an equal sign. This signals the operator not to touch the F key followed by the 4 key, but rather the F4 function key. The standard editing key labels to use are ArrowUp, ArrowDn, ArrowLf, ArrowRt, PageUp, PageDn, Insert, Delete, Home, End, and Tab. PgUp and PgDn are also valid.

CALL "CDS069", 0, 0, 0, 0, "+Control Code, ArrowUp=Previous, ArrowDn=Next+"will yield the prompt: Enter Control Code, ArrowUp=Previous, ArrowDn=Next, F4=End

If you do not want a word to follow the =, but still want the Editing Key underlined, then follow the = with a comma. CDS069 will drop the = as shown below.

CALL "CDS069", 0, 0, 0, 0, "+Control Code, ArrowUp=, ArrowDn=,+"will produce: Enter Control Code, ArrowUp, ArrowDn, F4=End

You may also imbed other attributes or color mnemonics within the prompt. CDS069 analyzes the prompt so that it will exclude these mnemonics when determining the number of characters to display per line of prompt, and the entry position.

CALL "CDS069", 0, 0, 0, 0, "C=Change, "+'red'+"D=Delete"+'blue'+"+"will produce: C=Change, D=Delete, F4=End
with the C=Change in the default color, D=Delete in red type, and F4=End in blue type.

CALL "CDS069", 0, 0, 0, 0, "'bu'+"C"+'eu'+"=Change, "+'bu'+"D"+'eu'+ "Delete+"will produce:C=Change, D=Delete, F4=End

This is often done with a defined function to simplify the code: DEF FNU$(Z$)='BU'+Z$(1,1)+'EU'+"="+Z$+", " CALL "CDS069",0,0,0,0,FNU$("Change")+FNU$("Delete")+"+" produces the same result.

Prompt Only

CDS069 can be used to prompt the operator to touch the Enter key or F4, but not capture any entered data. The fields that have special significance for 'Prompt Only' entries are listed below.

Prompt Only Arguments

MINV Pass as zero.

MAXV Pass as zero.

COL Pass as zero unless cursor should be positioned @(COL,ROW) during entry.

ROW Pass as zero unless cursor should be positioned @(COL,ROW) during entry.

PROMPT$

null or not passed	same as "-"
starts with minus ("-")	Enter=Continue
ends with plus ("+")	F4=End

TYPE$

null or not passed	same as "A"
"A"	Alpha entry, but since the MINV and MAXV are passed as zero for Prompt Only entries, no data is entered or returned to the calling program. If there is no active BBx 'window', then PROMPT$ will be displayed using the bottom two lines of the display. If there is an active BBx 'window', then PROMPT$ will be displayed using the bottom line of the active window.
"PA"	Alpha entry, using temporary BBx 'window' for PROMPT$. The Prompt Window flag indicates that CDS069 should create a temporary window at the bottom two lines of the display. This would be needed if there is something displayed on the bottom two lines that cannot be cleared during the entry, or when there is a BBx 'window' active that does not occupy the entire display, and it is desired for the prompt to be at the bottom of the display, and not the bottom of the active window.

NUMV Length of entered string. Always zero for Prompt Only entries, so typically not passed, or passed as 0 when passing TIMEOUT.

STRV$ String variable for entered data. Always returned as null for Prompt Only entries, so typically not passed, or passed as "".

Example

CALL "CDS069" or
CALL "CDS069",0,0,0,0,"-"

Enter=Continue

Example allowing Enter or F4. If operator touches the F4 key, then CTL=4 otherwise CTL=0.

CALL "CDS069",0,0,0,0,"-+"
		IF CTL=4 THEN GOTO EOJ

Enter=Continue, F4=End

Example with a prompt message.

CALL "CDS069",0,0,0,0,"Job Completed-"

Job Completed, Enter=Continue

Example with a custom prompt message.

CALL "CDS069",0,0,0,0,"Enter=Accept Entry, 
		F4=Abort"
		IF CTL=4 THEN BREAK

Enter=Accept Entry, F4=Abort

Example using a Prompt Window, needed when there are active window's on the screen, and the prompt is desired at the bottom of the screen instead of within the active window.

CALL "CDS069",0,0,0,0,"","PA"

Enter=Continue

Example with a 2 minute timeout. If no entry is made in two minutes, CDS069 will EXIT and take ERR= branch.

CALL "CDS069",ERR=EOJ,0,0,0,0,"","",0,"",2

Enter=Continue

Example with a 10 minute (600 seconds) timeout. If no entry is made in ten minutes, CDS069 will EXIT and take ERR= branch.

CALL "CDS069",ERR=EOJ,0,0,0,0,"","",0,"",600

Enter=Continue

String Variables

String Examples

Example where a single keystroke is used, i.e., the operator does not need to touch the Enter key. Note the list validation limits the entries to C or D.

CALL "CDS069",-1,-1,0,0,"+C=Change, D=Delete+","ACD",0,Z$

Touch C=Change, D=Delete, F4=End

Masked Numeric Variables

UnMasked Numeric Variables

Main Type

A/a

The "A" and "a" types indicate a normal string variable type of entry. The minimum and maximum number of non-blank characters permitted described by the MINV and MAXV variables. If the result is to be stored in a simple string variable, then the length of the string will be the same as the number of characters entered by the operator. In this case the numeric variable NUMV will contain the number of characters entered. The lower case "a" type is similar to the upper case "A", except that a null entry is permitted, even if MINV is not zero. For example, if MINV=4, and MAXV=6, and TYPE$="a", the entry must be 0, 4, 5 or 6 characters long.

L/l

The "L" and lower case "l" types are similar to the "A" type except that the data is left justified, i.e., it is padded with spaces (to the right) up to the maximum number of characters (MAXV). This option is useful for item numbers or other codes that become keys to a file. The lower case "l" permits a null entry, in addition to one that is MINV to MAXV characters long.

R/r

The "R" and "r" types cause the data to be right justified by padding with spaces to the left.

The lower case type indicates that a zero length entry is also permitted. For example: CALL "CDS069",2,3,0,0,"+code+","a",0,Z$ would require a two or three character entry, or a null entry. When using types "l" and "r", if the operator does not make an entry, the string variable returned is null and is not padded to the maximum length.

Numeric mask

If the main type is a valid bbx numeric mask such as "0000", "###,###.00CR", "-###", "BB###0", or "$$$,$$$.00-" then CDS069 will be used to enter a number between MINV and MAXV inclusive. CDS069 will automatically imply the decimal position if a decimal is not entered by the operator. This means that an entry with a mask of ###.00 will return an entry of 1.23 if the operator enters 123. To get 123.00 the operator would have to enter "123." or "12300" or even "123.00". Note that the mask may be followed by any of the Additional Parameters for file or string validation described below.

Also note that the operator may touch the negative indicator before or after the digits. This is a convenience to operators that are used to an adding machine where the negative indicator is touched after the digits are entered. The operator may also touch the "+" or "-" key to terminate the entry, as opposed to the Enter key.

CDS069 will insure that no more decimal positions are entered than are present in the mask. For example if the operator enters 1.234 to a mask of "##.00-" CDS069 will display an error message and not accept the entry.

If a decimal point is present in the mask, the operator will be signaled to the maximum number of decimal points allowed by positioning a decimal point within the entry mask.

Mask	Entry Mask
###,###.00CR	_ _ _ _ _ _ _ . _ _
-###.0	_ _ _ _ . _
###,###.00	_ _ _ _ _ _ _ . _ _

After the operator enters the number, the masked version of the number is displayed, i.e., CDS069 displays STR(NUMV:MASK$). The masked value is also returned in STRV$.

If the starting character of the mask is "<", then the data is displayed flush left. This is useful when headings appear to the left of the entry, and you do not want spaces between the heading and the displayed entry.

If you zero values to display as blanks instead of zero as in .00, then use a mask that ends in .## instead of .00. This requires setting the BBx Option using Dynamo Configuration Maintenance (SMC) titled: "Fill trailing mask # symbols with zeros" to Y. This will cause numbers like .5 to display as .50 even with .## as the mask.

Floating decimal

If the main type begins with the letter N then a numeric entry with a floating decimal point is assumed. This is useful for numbers that may have fractional positions, but don't normally. They require the operator to enter a decimal point if desired. No automatic shifting of the decimal is done for this type of entry unlike the masked numeric type described above. The N must be followed by two numbers separated by a decimal point, i.e., "N7.2". The first number indicates the maximum number of positions on the screen to be used for the entry. The second number indicates the maximum number of digits to the right of the decimal point to allow. No commas or other masking characters are inserted. The entry will be right justified in the output string with leading blanks.

For example: CALL "CDS069",1,9999.999,60,L,"+quantity","N10.3",Z will occupy 10 positions and permit up to three decimal positions.

For masked numeric, floating decimal, and date type entries, CDS069 will substitute certain invalid characters with its probable replacement.

Entry	Replaced with
Letter Oh "O"	Number 0
Letter Ell "l"	Number 1

Date entries

Regardless of the variable type code (D/d/S/s/J/j) the operator will always enter the date in MM/DD/YY format. The leading 0 for the month is not required. The leading zero is not required for the day if the operator enters the /. The slashes need not be entered. The output of CDS069 for dates is treated as a string variable with the following format:

Type Format ____ ______ D MM/DD/YY S YYMMDD J JJJJJJJ (seven character julian format)

The lower case (d, s and j) formats indicate to CDS069 that no entry is required, i.e., the operator may touch the enter key and the output will be null or blank depending on the location where the output data is to be stored (see below).

If an entry is made, then CDS069 will validate that the month is 1 thru 12, and that the day exists for the month and year entered.

There are certain shortcut keys permitted when entering dates. The letter T will provide today's actual date (as taken from the DAY variable). When there is a default date, touching only the + and - keys will increment or decrement the date by one day.

Although the current version of CDS069 still supports "DO" and "O" as equivalent types to "d", these type codes will be eliminated in a future release of CDS069 and currently are supported for compatibility with older software.

For J/j type dates, the first two digits of the year is currently assumed by CDS069 as 19 for years of 50 thru 99, and 20 for years 00 thru 49. This permits CDS069 to use J type entries from 1950 thru 2049. Later versions of CDS069 will permit the operator to enter all four digits of the year.

C/X

Sometimes CDS069 cannot perform all of the validation required. A telephone number is an example. A telphone number may be 7 digits, 8 digits (if the first digit is a 1), or 10 digits. It is normally displayed in a format xxx-xxx-xxxx. The C and X type can be used when CDS069 is to call another routine to perform the entry and validation. In most cases, this other routine will also call CDS069. If you were writing the code, you probably could call the other routine directly, and bypass the original call to CDS069 altogether. However, this option exists for the benefit of File Maintenance, Driver selection, and other routines that access the Variable Data Dictionary. These routines can always call CDS069 even for externally written routines.

The C and X types are both use external routines. The X type is normally used, but the C type provides compatibility with routines written on MAI Basic Four computers or previous versions of Dynamo Tools.

The C type routine must have an ENTER list that is almost the same as CDS069. ENTER Z1,Z2,Z5,Z6,Z0$,Z,Z$,Y,Z8$ Note however, it lacks a type field, and has two additional paramters. Y is to be set by the external routine to the CTL variable. CDS069 cannot use the CTL variable itself, since that may have been changed by a disc read performed by the external routine. The variable Z8$ is passed to the external routine.

When called from file maintenance, Z8$ is either NEW or CG which indicates that a new record is being created, or an existing record is being maintained. When called by the Driver Z8$ is set to DRV. There are some circumstances when the external routine needs this data to function properly.

The C type routine is only used to enter string type data. File Maintenance will display the number of characters specified by the maximum value in the Variable Data Dictionary. See CDX030 for an example of a C type external called routine.

When special formatting is required to display the data, use the X type. The X type is similar to the C type except the the external routine is more complex. It is also called by File Maintenance to display the data, or to format the data when printing a terminal image. The X type entry may occupy more than one line on the screen.

The enter list is almost the same as for the C type variable ENTER Z1,Z2,Z5,Z6,Z0$,Z,Z$,Y,Z8$,FMT$[ALL]

Z8$ is passed to the external routine as DIS during the display of a record within file maintenance. The external routine should format then display the data, passed to the routine in Z$ at the cursor position @(Z5,Z6).

Z8$ is passed to the external routine as FMT during the print terminal image option within file maintenance. In this case, the called routine must format the data, and return the formatted data in the FMT$[ALL] array. FMT$[0] should contain the data normally displayed on the first line for the variable, FMT$[1] the 2nd line, etc. If there is only one display line for the variable, then use FMT$[0].

Like the C type external routine, Z8$ will also be passed as DRV, NEW, and CG as described above.

See CDX040 for an example of an X type external called routine.

Prefix Codes

Note that each prefix code described below is not applicable to every Main Type. Refer to the table above. Recall that the Prefix Codes precede the Main Type, so the Entry Type of EA indicates prefix code E with main type A.

This indicates that the prompt should be modified to include Ctrl+C=Abort or Ctrl+Break=Abort. If present CDS069 will exit with an error 99 if the operator aborts the entry. Note that you must specify ERR=line on the call to CDS069 when using the E option. See Interrupt Option.

F/f/g

These prefix codes indicate file validation. The data entered will be validated against a data file, and a field from the data file may be displayed if desired. Even though an entry may be of the proper length and not contain any invalid characters, additional validation may be required.

F indicates normal file validation with an F2 option to display valid entries.

f indicates that ArrowUp and ArrowDn keys may be used (instead of using F2) to simply scroll forward or backward through the file. CDS069 will modify the prompt to indicate when these options are valid.

g works much like f except when there is a multi-segment key and the entry is not for the last segment of the key. With f, the ArrowDn and ArrowUp keys will return data from the very next and previous keys in the file, even if they are the same. With g, the arrow keys will skip forward or backward to yield different keys as you would see in the F2 display.

example

Consider the simple example of a two segment key with each segment being one character. The following keys are in the file: A1 A2 A3 B1 B2 B3 C1 C2 and C3. If the entry being made is for the first segment only, then the F2 option will display only A B and C. Assume the last record read was B2 and the next record to be read is B3.

The default value will be B (from the record last read). With the f option, the ArrowDn key will return B (the B of B3) and ArrowUp key will also return B (the B of B1). With the g option, the ArrowDn key will return C since it will not return the same value for Enter as it will for ArrowDn. Similarly, ArrowUp will return A.

New parameters for string validation added 11/04/2000

{slot, (EA) Additional Parameters: {1,2,3,4,5,6,7,8,9,10,11}

1. Channel#(:knum) or filename

2. Field# or template expression (DISP$, see CDS037)

3. Position

4. Length

5. Column or (R for right, B for below)

6. Row (not required if R or B option used for Column)

7. Prefix

8. Options: Y=F2

9. Head column

10. Head Window

11. Hex Prefix(?) for non-printables

Dates

The fields that have special significance for date entries are described below.

Date Entries

MINVAL

Minimum Date allowed
Value	Description
0	no minimum date restriction
-1899 to -1	days prior to today's date
1 to 1899	days after today's date
1900 to 2999	minimum date is Jan 1 in year specified in `MINVAL`
any valid julian date	date specified

MAXVAL

Maximum Date allowed
Value	Description
0	no maximum date restriction
99	no maximum date restriction (only if `TYPE$` is D, d, S, s, M, or m). Deprecated option that exists to support very old existing code that passed `MAXVAL` as 99 to indicate no maximum date
-1899 to -1	days prior to today's date
1 to 1899	days after today's date
1900 to 2999	maximum date is Dec 31 in year specified in `MINVAL`
any valid julian date	date specified

TYPE$

Describes the format of STRV$ that the date will be stored in. Note that the date is always displayed and entered in MM/DD/YY format.

Value	Description
J	Julian format (preferred format for storing dates) used with native BBx DATE() and JUL() functions.
j	Same as J, but the date is not required and will be returned as null.
D	MM/DD/YY format
d	Same as D, but the date is not required and will be returned as null.
S	YYMMDD format
s	Same as S, but the date is not required and will be returned as null.
M	Microsoft version of a Julian date where the epoch is 1/1/1900. This format returns a 6 character string and can be used in place of the S format in keys where you may want to keep the keysize the same when adding Y2K support.
m	Same as M, but the date is not required and will be returned as null.

NUMV For all but sub-string entries, NUMV will be returned as the julian date, regardless of TYPE$. For substring entries, NUMV represents the position in STRV$ where the date will be stored. Note that NUMV is not used as the default date for input.

STRV$ Contains the default value of the date, and will contain the entered date in the format specified by TYPE$.

VAL[ALL] Only used when numeric entries. Since a date is treated as a string field, even when using numeric types such as J and M, the VAL[ALL] array does not apply to dates.

FLDNAM$ The field name contained within REC$ where the date is stored. Note, even though dates are treated as a string variable, when using CDS039, the FLDNAM$ can refer to a numeric field such as U(3), I(3), or N(7) for J type, N(6) for S and M types, and C(8) for D types.

Prompt Window

These programs display instructions to the operator based on information included in PROMPT$. If the active window is the full size of the display, then the operator prompt will clear and use the last two lines of the display. If the active window is less than the full size of the display, then the operator prompt will clear and use the last line of the active window for the operator prompt. The operator prompt is not optional.

The Prompt Window option can be used to override this behavior. The Prompt Window option is enabled by including the letter P before the TYPE$ field. It does not apply to Window Text entries. When this option is used, a temporary two line window will be used at the bottom of the display for the prompt. This might be desired when there is a small active window and it would be more desirable for the prompt to appear at the bottom of the display, instead of the bottom line of the active window. It might also be needed when there is information displayed on the bottom two lines of the display that should not be cleared.

Prompt Window Examples

Example of display with active window, prompt located on bottom line of active window.

Example using the prompt window option. Prompt is located on bottom two lines of physical display.

Help Text

Help Text related to the current entry can be offered by using braces at the end of PROMPT$. CDS069 will modify the prompt to include the phrase F3=Help to inform the operator that help text is available. If the user touches F3 and selects the 'Item Specific Help' option, then CDS069 will either display the traditional help text, or launch a browser with the html help page (requires compatible terminal emulator such as FacetWin or PowerTerm), or inform the operator to point their browser to the specified help text page.

Help text is maintained using Documentation & Help Text Maintenance (FMS). PROMPT$ should contain the help text file name followed by a comma, then the help text ID, i.e., "+Customer#, Name, Phone#, Zip Code, #+InvoiceNo+{DYSK57,CUSTNO}". The traditional Notepad style help text file is named XXSK57 where XX is the company code. The help text ID will be padded to 10 characters long. The help text is stored in as Window/Notepad text with 78 characters wide with an unlimited number of rows. The help text can contain any of the attributes that can be saved with notepad text such as bold, underlined, reverse video, blinking text, and line graphics.

HTML based help text can be maintained using your favorite word processor, text or html editor. The Documentation & Help Text Maintenance (FMS) program can also be used to define the help text document based on a template, and to launch an html editor to edit the document. A web server such as a apache is required to host HTML based help text. The text between the braces is in the format {SiteName,htmlpage}. The SiteName is optional. See examples below.

Site Name	Description
dt	Used for all Dynamo Tools help text
dy	Used for all Dynamo help text
xx	Used when user help text using Help Text URL in Dynamo Configuration Maintenance is used
other value	URL to help text site
not specified	The same as 'xx' if Help Text URL is specified in Dynamo Configuration Maintenance, or same as 'dy' if not.

Help Text Examples (`PROMPT$` shown)
`"+Customer#+"`	No Help Text offered
`"+Customer#+{DYSK57,CUSTNO}"`	Traditional Notepad style help text found in file DYSK57, maintained using Help Text Maintenance (FMS)
`"+Printer ID+{dt,PrinterIDEntry.htm}"`	HTML Help at www.excellware.com/docs/tools/help/PrinterIDEntry.htm will be displayed
`"+Customer#+{dy,CustNoEntry.htm}"`	HTML Help at www.excellware.com/docs/dynamo/help/CustNoEntry.htm will be displayed
`"+Trailer#{xx,TrailerEntry.htm}"`	Assuming that the Help Text URL in Dynamo Configuration Maintenance is set to www.customerdomain.com/help, then HTML Help at www.customerdomain.com/help/TrailerEntry.htm will be displayed
`"+Store#{www.myco.com/help,StoreEntry.html}"`	Displays help page www.myco.com/help/StoreEntry.html
`"+Trailer#{TrailerEntry.htm}"`	Assuming that the Help Text URL in Dynamo Configuration Maintenance is set to www.customerdomain.com/help, then HTML Help at www.customerdomain.com/help/TrailerEntry.htm will be displayed
`"+Customer#+{CustNoEntry.htm}"`	HTML Help at www.excellware.com/docs/dynamo/help/CustNoEntry.htm will be displayed assuming that there is no Help Text URL in Dynamo Configuration Maintenance

Simple List Validation

Simple List Validation is used for string validation such as for a Y or N entry. The list of valid options are listed in the preferred order of display following the entry type. Each entry in the list must be the same length.

Simple List Validation example, for a Y or N entry
The operator can enter an upper case, or lower case Y or N. YN$ will be converted to upper case if necessary because the Validation List is upper case. YN$ will only contain Y or N.

CALL "CDS069",1,1,0,0,"Are all entries correct (Y/N)","AYN",0,YN$

Simple List Validation example using a two character state code

CALL "CDS069",2,2,0,0,"+State Code","APAOHINNY",0,STATE$

The operator may enter one of the valid codes, or touch F2 to select from the list

There are situations where a Simple List Validation is used, but the user is permitted to make an entry not in the list. For example, the most popular responses could be included in the list, but other entries are permitted. CDS039/CDS069 also support this option.

Simple List Validation but allow entries not in list
`xxxx{SlotLen,-}ValList`
`xxxx`	Field `TYPE$` such as A, L, R, J, a numeric mask such as ###0, N5.4, etc. For best results use L or R for list verified character field types, and not the variable length field type of A which would require keys of variable length in the data file which is not recommended. You may use type A if the minimum and maximum length of the entered field are the same. In some cases, a null entry should not require validation. Validation is bypassed when the field type is lower case (a, l, r, etc.), and a null (0 length) entry is made. Note that if the entry has a default value, the operator needs to clear out the default characters using the Delete Key or Ctrl+G in order to create a null entry.
`SlotLen`	This is the length of each entry in the Validation List (ValList). If you pass a numeric SlotLen, then each slot must be the same length. It is easier to let CDS069 determine the SlotLen by separating entries in the ValList with some character not contained withing the ValList such as the pipe symbol (\|). See Examples.
`-`	The "-" indicates that entries not in the list are permitted
`ValList`	Validation List containing values permitted. Each entry in the list must be the padded to the maximum length. See examples.

Examples of Simple List Validation that allow entries not in the list
Status codes include D, M, L, and any other character
`CALL "CDS069",1,1,0,0,"+status code","A{1,-}DML",0,STATUS$`
Status codes include A, BB, DX, and any other one or two character code. Note that the status codes listed must be padded to the maximum length of 2 characters. Note also that since the field type is A, STATUS$ will be one character long if the user selects status A from the F2 display list, or if they enter a single character.
`CALL "CDS069",1,2,0,0,"+status code","A{2,-}A BBDX",0,STATUS$`
Status codes include A, A1, A10, B, B1, B10, and any other status code. This example will pad out the status code to 3 characters.
`CALL "CDS069",1,3,0,0,"+status code","L{3,-}A A1 A10B B1 B10",0,STATUS$`

List Validation with Related Field

List Validation with Related Field, allows the user to enter data contained within a list, and display a related field. For example, if the user is presented with a list of option numbers, the description of the option would be the related field, or if presented with a list of payment method codes, the description of the payment method would be the related field.

List Validation with Related Field Parameters

xxxx{SlotLen,RfPosn,RfLen,RfCol,RfRow,Options,ColHead,WTitle,WCol,WRow}ValList

xxxx

Field TYPE$ such as A, L, R, J, a numeric mask such as ###0, N5.4, etc.

For best results use L or R for list verified character field types, and not the variable length field type of A which would require keys of variable length in the data file which is not recommended. You may use type A if the minimum and maximum length of the entered field are the same.

In some cases, a null entry should not require validation. Validation is bypassed when the field type is lower case (a, l, r, etc.), and a null (0 length) entry is made. Note that if the entry has a default value, the operator needs to clear out the default characters using the Delete Key or Ctrl+G in order to create a null entry.

SlotLen This is the length of each entry in the Validation List (ValList). If you pass a numeric SlotLen, then each slot must be the same length. It is easier to let CDS069 determine the SlotLen by separating entries in the ValList with some character not contained within the ValList such as the pipe symbol (|). See examples below.

RfPosn This is the starting position of the Related Field in the Slot. The term Slot refers to one entry in the ValList. Each Slot consists of the value, the related field, and may include other text that is not part of the value nor the related field. Typically the Related Field begins immediately after the entry field. Include a "-" before RfPosn to allow an entry that is not in the list. Example RfPosn: 2, -2, 3, -3, 10, -10. See example below.

RfLen The length of the Related Field. Typically set to the pipe (|) character to let CDS069 determine the length of the Related Field.

RfCol

If present, this signals the input routine to display the Related Field

R	Display Related Field to Right of entered data
B	Display Related Field Below entered data
n	Display Related Field at Column n where n is a bbx column number within the active window as in `@(RfCol,RfRow)`.

RfRow Used when RfCol is passed as a numeric to indicate the bbx row number.

Options

This parameter includes several options that are sub-strings.

sub-string	Usage
(1,1)	Pass as Y to enable Forced Window Mode, which basically means that the list of valid entries are displayed immediately, without requiring the user to touch the F2 key.
(2,3)	The following 3 segments are used to override the default colors used on the window that displays the list of records for the user. Note that all three color number segments must be passed to be used. This segment represents the color number for Widow Border. The color numbers range from 001 to 128 and can best be viewed using Operator Preference Maintenance (SMS) and then Color Preferences.
(5,3)	Color number for non-highlighted row
(8,3)	Color number for highlighted row

ColHead

Used to set or override the column titles for the fields to be displayed.

Program and Field type used	Column Titles
CDS039 using Field Name(s)	All column titles are derived from Data Dictionary/Template. If `ColHead` is used, then it will override all column titles.
CDS069 using Field Name(s)	The column title for the field being entered is taken from this `ColHead` parameter, and the column titles for the Field Names will be taken from the Template.
Field Number	All column titles are derived from the `ColHead` parameter.

WTitle Used to set a title for the window that appears in the window border

WCol

Pass this parameter when you want to override the default position of the window containing the list of options.

Column of window containing list of options
0 or not passed	Left Justified
C	Centered
R	Right Justified
numeric	Window will be displayed at column `WCol`

WRow

Pass this parameter when you want the window containing the list of options to stay low on the display so that information above the window remains visible.

Minimum Row of window containing list of options
null or not passed	Row will be 2 or higher
numeric	Window will be displayed at specified `WRow` or higher

ValList Validation List containing values permitted and the Related Fields. ValList typically contains multiple 'slots' of entry and related fields separated by the pipe (|) character, depending on the values of SlotLen, RfPosn, and RfLen.

The examples of List Validation with a Related Field are based on the following Payment Method Codes and Descriptions.

Payment Method Code	Description
C	Check
T	Funds Transfer
W	Automated Withdrawl

List Validation with Related Field Examples

CALL "CDS069",1,1,COL,ROW,"+Payment Method Code","A{|,2,|}CCheck|TFunds Transfer|WAutomated Withdrawl",0,PMTMETH$

The operator will initially be presented with the prompt:


		Enter Payment Method Code, F2=Display _

If they touch F2, or enter an invalid Payment Method Code, they will presented with the list:

This example shows the data entry at column COL and row 2 and displays the Related Field to the right of the Payment Method Code.

0110 PRINT 'CS',
		0120 CALL "CDS276","Payment Method",COL
		0130 CALL "CDS069",1,1,COL,2,"+Payment Method Code","A{|,2,|,R}CCheck|TFunds 
		T
		0130:ransfer|WAutomated Withdrawl",0,PMTMETH$

Payment Method.: T Funds Transfer

Example using the ColHead & WTitle parameters

0110 PRINT 'CS',
		0120 CALL "CDS276","Payment Method",COL
		0130 CALL "CDS069",1,1,COL,2,"+Payment Method Code","A{|,2,|,R,,,Code 
		Description,
		Payment Method Selection}CCheck|TFunds Transfer|WAutomated Withdrawl",0,
		PMTMETH$

Example using program specified colors for F2 Window

0100 REM "List - 10/09/07 Validation with Related Field 
		Example
		0110 PRINT 'CS',
		0120 CALL "CDS276","Payment Method",COL
		0130 CALL "CDS069",1,1,COL,2,"+Payment Method Code","A{|,2,|,R,,N007013077,
		Code Description,Payment Method Selection}CCheck|TFunds
		Transfer|WAutomated Withdrawl",0,PMTMETH$

Example of a status code that has valid entries for D, M, and L, but any other non-blank value may also be entered.

CALL "CDS069",1,1,0,0,"+status","A{|,-2,|}DDiscontinued|MDiscontinued 
		by Manufacturer|LLabor Item",0,S$

Same as above example, but a null entry is also permitted.

CALL "CDS069",0,1,0,0,"+status","A{|,-2,|}DDiscontinued|MDiscontinued 
		by Manufacturer|LLabor Item",0,S$

Same as above example, but a null entry will be returned as a blank character as opposed to a zero length (null) string.

CALL "CDS069",0,1,0,0,"+status","L{|,-2,|}DDiscontinued|MDiscontinued 
		by Manufacturer|LLabor Item",0,S$

This example requires either 2 non-blank characters, or two blanks, but not values with only one blank.

CALL "CDS069",2,2,0,0,"+status","a{|,-3,|}DWDiscontinued 
		by Wholesaler|DMDiscontinued by 
		Manufacturer|DDDiscontinued by 
		Distributor",0,S$

File Validation

File validation can be used to verify that data entered exists in a keyed file on disc. File Validation is enabled using a TYPE$ modifier of F, f, G, or g. Additional file validation parameters follow the TYPE$ and are contained within braces {}. You do not need to specify the complete list of parameters. Parameters are separated using commas.

File Validation Parameters

Fxxxx{FileChan,Field,StartPos,Length,Col,Row,Prefix,Options,Colhead,Wtitle,Prf}

F

Type modifier indicating file validation is to be used

Modifier	Usage
F	Normal File Validation
f	Provides same features as Normal File Validation, but includes in the prompt ArrowDn and ArrowUp options to advance to the next/prior record in the file. Note that this option requires that FileChan be passed as the channel number of the opened file, and not the file name.
g	Similar to f, but is used when the field being entered is not the final segment of the key, and pressing the ArrowDn/Up key should return the next value that differs from the previous record.

xxxx

Field TYPE$ such as A, L, R, J, a numeric mask such as ###0, N5.4, etc.

For best results use L or R for file verified character field types, and not the variable length field type of A which would require keys of variable length in the data file which is not recommended.

In some cases, a null entry should not require validation. File validation is bypassed when the field type is lower case (a, l, r, etc.), and a null (0 length) entry is made. Note that if the entry has a default value, the operator needs to clear out the default characters using the Delete Key or Ctrl+G in order to create a null entry.

FileChan Typically passed as a file name but can also be passed as a numeric channel of a data file already opened. When using a KNUM of other than zero for MKY files, specify the KNUM to use by following the FileChan parameter with a colon and then KNUM, as in XXCM01:3.

Field

Typically passed as a pipe separated list of template field names which are displayed for the operator when selecting a record from the data file. The field name can also be preceded by a different file name or program name. Example: FIELDNAME|FILENAME.FIELDNAME|PROGRAM.FIELDNAME|REPEATINGFIELD[2]. Use [n] for repeating fields. See example.

The best practice is to store column titles and numeric masks in the Data Dictionary, which are stored as user defined fields in the template. However, when necessary, you can override the template values by specifying the column title and/or numeric mask following each field name separated with a backslash as in FIELDNAME1\ColTitle2\Mask1|FIELDNAME2\ColTitle2\Mask2, i.e.,

Older programs that do not use templates, can specify a field number, and the following two parameters (StartPos & Length) to indicate what information to display to assist the user in selecting the desired record.

In some cases, you may want the convenience of file validation, yet allow the user to enter data that is not on file. You can enable this option by placing a minus immediately before the Field parameter as in -FIELDNAME or -2. To use this option when no Field parameter is used, a minus without a field name or number can be used.

StartPos When the Field parameter is passed as a numeric field number, then the StartPos is required to indicate that the related field to be displayed for the user begins with the StartPos character within the field, typically 1.

Length When the Field parameter is passed as a numeric field number, then the Length is required to indicate the number of characters in field# Field, to be displayed. Note that this is a maximum number of characters to display. Fields shorter than the Length specified will not cause an error.

Col

If present, this signals the input routine to display the Field described above

R	Display Field to Right of entered data
B	Display Field Below entered data
n	Display Field at Column n where n is a bbx column number within the active window as in `@(Col,Row)`.

Row Used when Col is passed as a numeric to indicate the bbx row number. The Row is computed automatically when the Col parameter is R or B.

Prefix This parameter is used to specify the characters of the key that precedes the segment being entered. Note that the Prefix parameter cannot contain a comma or any binary data such as a U(3) date. If there is a chance that the Prefix parameter might include a comma or other binary data, then set the Prefix using hexadecimal format by including a leading "$" before and after the Prefix such as "$"+HTA(KEYPREFIX$)+"$".

Options

This parameter includes several options that are sub-strings.

sub-string	Usage
(1,1)	Pass as Y to enable Forced Window Mode, which basically means that the list of valid entries are displayed immediately, without requiring the user to touch the F2 key.
(2,3)	The following 3 segments are used to override the default colors used on the window that displays the list of records for the user. Note that all three color number segments must be passed to be used. To use the default colors, yet still pass the Skip Duplicates parameter described below, then pass these color numbers as all zero's. This segment represents the color number for Widow Border. The color numbers range from 001 to 128 and can best be viewed using Operator Preference Maintenance (SMS) and then Color Preferences.
(5,3)	Color number for non-highlighted row
(8,3)	Color number for highlighted row
(11,1)	Skip Duplicates - When the segment of the key being entered, is not the last segment of the key, there may be multiple records that have the same value for the data being entered. The default behavior is to display each record as the related data might vary. You can cause the input routine to display only one record in this case by passing the Skip Duplicates parameter to Y.

ColHead

Used to set or override the column titles for the fields to be displayed.

Program and Field type used	Column Titles
CDS039 using Field Name(s)	All column titles are derived from Data Dictionary/Template. If `ColHead` is used, then it will override all column titles.
CDS069 using Field Name(s)	The column title for the field being entered is taken from this `ColHead` parameter, and the column titles for the Field Names will be taken from the Template.
Field Number	All column titles are derived from the `ColHead` parameter.

WTitle Used to set a title for the window that appears in the window border

Prf This field can be used as an alternative to the Prefix parameter when the Prefix contained a comma. However, to support commas and any other binary data, you can now set either the Prefix or Prf parameter to hexadecimal format with a leading and trailing "$" character, as in "$"+HTA(KEYPREFIX)+"$".

Example of a simple file validation with no related field

CALL "CDS069",1,3,0,0,"+Product Class","FR{XXUM27}",0,PCL$

Initially the prompt will simply read:


		Enter Product Class, F2=Display ___

If the user touches the F2 key, then the Product Class for all records in the XXUM27 Product Class file will be displayed, allowing the user to select from the list. The cursor movement keys, ArrowUp, ArrowDn, ArrowLf, ArrowRt, PageUp, PageDn, Home, and End can be used to highlight the desired product class.

Adding the related field of the Product Class Description with a template field name of DESC.

Add a PCL column heading.

Use field number, starting position, and length, instead of field name. Note that you lose all column titles when using a field# instead of the field name.

But you can add column titles manually.

But if you use CDS039, the column titles are determined automatically, and not required in the parameters. Note that the title for the entered field comes from the template of the variable passed to CDS039, not the template used for file validation. The field titles would typically be the same, especially if using the 'Link To' option in the Data Dictionary where PCL is only defined once, and all other references link to the original field definition.

When using field names, you can display multiple fields from the related file.

Once the file verified entry has been made, fields from the related file are typically displayed to the right of the entered field. The Col and Row parameters are used to indicate the screen position where to display this information. Specify R in the Col parameter (the Row parameter will be ignored) to display the related file fields to the right of the entered field.

Consider a group file named MEUM12, with a 2 character GROUP_CODE and DESCRIPTION, and a customer file MECM01 with KNUM 6 of GROUP_CODE+CUSTNO. The application needs to prompt the user for a GROUP_CODE. One option is to include all groups on the Group File. If the operator touches F2, then all GROUP_CODES in the Group File will be displayed. The Group DESCRIPTION will be displayed to the right of the GROUP_CODE. The GROUP_CODE entered (or selected from the list) will be stored in REC.GROUP_CODE.

CALL "CDS039",1,2,0,0,"+group code","FR{MEUM12,DESCRIPTION,,,R}",REC$,"GROUP_CODE"

Another option would be to only display the GROUP_CODES that have a customer assigned to them, i.e., those with a record in the MECM01 file. We still want to display the Group DESCRIPTION from the MEUM12 file to the right of the entered data.

CALL "CDS039",1,2,0,0,"+group 
		code","FR{MECM01:6,MEUM12.DESCRIPTION,,,R},REC$,"GROUP_CODE"

This example uses an external program to perform a calculation with the result displayed in the F2 window. Data file XXPO50 contains Purchase Order Receipt heading information. It's primary key is a numeric RCPTNO and includes data fields DATERCVD and BY. Program PO134 receives as input a PO50$ record and calculates the value of the receipt. PO134 has a template in the Data Dictionary with a field name of VALUE. The PO134 program has an ENTER list of Y$,PO50$,PO134$. For more information about using external programs refer to the documentation for CDS037 and CDS038.

0100 CALL "CDS095",PO50,"XXPO50","",PO50$
		0110 CALL 
		"CDS039",0,0,0,10,"+receipt#","FN8{XXPO50,DATERCVD|BY|PO134.VALUE,,,R}" 
		,PO50$,"RCPTNO"

File validation example using lower case 'f' to enable ArrowDn/Up options to advance through the records in the file. Line 100 is used to obtain template SO40$ for file XXSO40. Line 101 opens data file XXUK50. The lower case 'f' option requires the channel number be passed, not the file name.

Window/Notepad Text

CDS039 and CDS069 can also be used for a two dimensional entry field. In this case, the entered data is not returned to the calling program but is actually stored in a data file.

Window/Notepad text can contain both dim and bold text, underlined text, reverse video text, blinking text, line drawing characters, and any combination of these attributes.

The width of the Notepad Text must fit within the logical display window, but can have virtually an unlimited number of rows. The number of rows of notepad text that exist above and below the active window are displayed on the right side of the window border.

The following Dynamo Tools are used with Window/Notepad Text:

Program Name	Description
CDS054	Window Text - Copy/Append/Delete
CDS257	Read / Print / Convert Window Text (primarily used to print window/notepad text to printer) This document also contains information on types of data files supported.
CDS261	Return Window Text Information (returns all text, first part of text, or text converted to HTML format)

CALL "CDS069", WinCols, WinRows, Col, Row, Desc$, Type$

WinCols Number of display columns for notepad text, excluding the window border. WinCols can be passed as zero to use the default of 78, which will take up the full display width on a typical display with 80 columns. If text was stored using a larger WinCols, then passed to CDS039/CDS069, then the larger WinCols value will be used.

WinRows Number of display rows for notepad text, excluding the window border. WinRows can be passed as zero to use the default which will maximize the notepad window based on the Row parameter.

Col Column number for left side of the window border. Normally passed as zero so the window border is at the left edge of the physical display.

Row Row number for the top edge of the window border. Pass as zero to use the default value of 2 which allow the top two lines of the display to remain present during the entry of the window text.

Desc$ This is the notepad description that will appear in the border of the window and in the prompt at the bottom of the page. If passed as null, then 'text' will be used.

Type$

This string begins with W indicating Window/Notepad text, followed by comma separated parameters surrounded by braces.
W{NotePadFileName,NotePadID,MorD,BorderAttr,TextAttr}
Only the first two parameters are required, so a valid Type$ would be:
W{XXCM06,ABCDEF}

NotePadFileName required You can pass either the Notepad File Name or the numeric channel number of the Notepad File previously opened. A template is not required for the Notepad File. Refer to the documentation for CDS257 for more information about the file characteristics for window/notepad files. Note that the Notepad file name must contain at least one alpha character and cannot contain a comma.

NotePadID required The NotePadID is the identification for the notepad text. It must be non-blank, and can be any length up to one character less than the key size of the notepad data file. For example, if the key size is 7, then the NotePadID can be 1 to 6 characters long. The NotePadID cannot be a binary field, nor can it contain a comma. Use the HTA() function to convert a binary data element into a valid NotePadID.

MorD

optional

M	Display & Maintain notepad
D	Display notepad, prompt user if notepad text does not exist
d	Display notepad, do not prompt user if notepad text does not exist
any other value	Display & Maintain notepad

BorderAttr

optional

Mnemonics used to print the notepad window border. Defaults to a white border in the current intensity on the current background color. For example, 'SF'+'RED' will make the border bold red using the current cell background color. To make the border bold red on a black background pass BorderAttr as 'BACKGR'+'BLACK'+'RED'.

Any valid bbx mnemonics can be used including 'SF', 'SB', 'RGB'(), 'BACKGR', and all color mnemonics. Remember that bbx treats mnemonics like string variables, so use the + symbol to imbed BorderAttr in the parameter string as shown in this example:
CALL "CDS069",0,0,0,0,"Notepad Text", "W{XXCM06,123346A,M,"+'SF'+'RED'+"}"

TextAttr optional Mnemonics used for the notepad text. Defaults to the current color settings if not passed. For example, to have white text on a black background, pass TextAttr as 'BACKGR'+'BLACK'+'WHITE'.

Simple example with minimum parameters

CALL "CDS069",0,0,0,0,"","W{XXCM06,123456A}"

Example with columns, rows, and title specified

CALL "CDS069",42,10,0,0,"Notepad Text","W{XXCM06,123456B}"

Example with columns and window position column and row specified

CALL "CDS069",42,0,18,10,"Notepad Text","W{XXCM06,123456B}"

Example using border and text attributes, and text that exceeds window height.

CALL "CDS069",0,0,0,0,"Notepad Text", "W{XXCM06,123456A,M,"+'BACKGR'+'BLACK'+'GREEN'+","+'BACKGR'+'BLACK'+'WHITE'+"}"

Special Keys

The Dynamo Tools input routines support use of cursor movement keys, including the 4 arrow keys, home, end, page up, and page down keys, as well as un-shifted and shifted function keys. Some of these keys have specific values, that cannot be changed. Other keys can be selectively enabled to allow the user to touch a key and return a specific CTL value to the calling program.

Reserved Keys

Key

Usage

Used as the hotkey which when touched, will display a hotkey menu list, which will launch a new instance of bbx to run the selected hotkey application, and return to the input routine upon completion or return to the menu.

Used to list the valid options when using simple list validation, list validation with a related field, and file validation. The input routines will include "F2=Display" in the prompt whenever validation is used. When validation is not applicable, then the F2 key can still be used with or without the Extended Exit options described below. When there is no Extended Exit option, then the F2 key will act like the Enter key, but will set CTL=2. Note that in this case, the entry must still meet the minimum size or value requirement.

Used as the Help key. Touching this key will present the user with a brief menu of Help topics including a Help topic related to the active Dynamo Menu, the active program, any Help text referenced in PROMPT$, a Help topic for rules for entering dates, general data entry Help, and display of Dynamo Release Notes. On most workstations, selecting a help topic launches a browser window with the selected Help topic.

Used to exit, quit, get out, etc. Enabled by including the "+" key at the end of PROMPT$ which will cause the prompt to include "F4=End". You can also include other text with the F4 key, such as passing PROMPT$ as: "Enter fax number, F4=Abort fax option". For compatibility with very old applications written for Basic Four terminals that have the roman numeral 'motor bar' keys I, II, III, and IV, the clause "OR CTL IV" will be replaced with "F4=End" which is more accurate for most workstations today.

End

Unlike the original keyboards that had the motorbar IV key to the right of the keypad, the F4 key on the current PC keyboard is at the top and further to the left. To accommodate right-handed users that would like an F4 key at the right side of the keyboard, the End key emulates the F4 key depending on the situation as described below.

End Key Usage
1	Window/Notepad entry	Toggles the cursor position between the end of the window and to the space to the right of the last non-blank character in the row.
2	List with highlighted record	Highlights the last entry in the list.
3	Normal field with non-blank characters	Moves cursor to space after last non-blank character in field
4	Normal field all blank	Emulates F4 to 'End', 'Exit', etc.

PageDn

The Page Down key can also act like the F4 key as described below.

PageDn Key Usage
1	Window/Notepad entry	Moves the cursor to the last row of the window, or the last row of the next page, or to the last non-blank row.
2	List with highlighted record	Moves the highlight bar down to the last row of the current page, or the last row of the next page, or to the last row in the list.
3	Normal field with non-blank characters	Emulates F4 to 'End', 'Exit', etc.
4	Normal field all blank	Emulates F4 to 'End', 'Exit', etc.

Enter

The Enter key can also act like the F4 key as described below.

Enter Key Usage
1	Window/Notepad entry	Moves the cursor down one row to the first column
2	List with highlighted record	Selects the highlighted record
3	Normal field with non-blank characters	Accepts the entered or default data
4	Normal field with zero length - zero length field is valid	Accepts the entered or default data
5	Normal field with zero length - zero length field is invalid	Emulates F4 to 'End', 'Exit', etc.

ArrowUp

Typically used to allow the user to 'move up' to the previous field, especially in file maintenance applications. CTL will be 3 when the user touches the ArrowUp key.

ArrowDn

Typically used to allow the user to 'move down' to the next field, especially in file maintenance applications. CTL will be 2 when the user touches the ArrowDn key.

Other

The Tab, ArrowLeft, ArrowRight, Insert, Delete, Home, End, PageUp, and PageDown keys have specific meaning depending on the type of entry. However, some of these keys can be customized by the application. See the Extended Exit and Prompt Key options below.

Extended Exit Option

This option can be used to permit the user to touch a special key which will set the system CTL variable to a value that can be tested by the calling routine. Extended Exit Options are still supported, but in most cases the Prompt Key Option is used instead.

This option is enabled by including any of the following two character codes inside braces following the entry type. Note that the Extended Exit option cannot be used when any other validation option such as list validation, list with related field, or file validation, is used. Multiple Codes can be used. CTL will be set to 5 plus the code within the list, i.e., the first code in the list will return CTL=6, the second will return CTL=7, then third CTL=8, etc. See example below.

Note that the minimum value and size requirement is not enforced when the user touches one of the Extended Exit keys.

Code	Key
F2	F2 function key
HO	Home key
EN	End key
TR	Tab key (tab right)
TL	Shifted Tab key (tab left) - not supported by many terminal emulators
PD	Page Down key
PU	Page Up key

Example: Return CTL=6 if user touches F2 key, CTL=2 if user touches ArrowDn key. Note that the user will be permitted to touch the F2 key even when the length of VAL$ is zero, i.e., less than the MINLEN argument of 1. But if the user touches the ArrowDn key, then the entry must meet the MINLEN requirement.

CALL "CDS069",1,3,0,0,"+value","A{F2}",0,VAL$

Example: Return CTL=6 if user touches PageDn key, CTL=7 if user touches PageUp key.

CALL "CDS069",1,3,0,0,"+value","A{PDPU}",0,VAL$

Prompt Key Option

This option is the preferred method to advise the user that a special key can be touched. Like the Extended Exit Option, it will pass the system CTL variable to the calling application to determine what action to take based on the key touched.

The Prompt Key Option is enabled by including the clause in the format "Key=Action," in PROMPT$. The valid Keys are listed in the table below. Note that 'Action' can be null, as in "Key=," which will appear as just "Key" in the prompt. See example below.

Note that the Prompt Key Option temporarily overrides any function key mapping assigned using Terminal Function

Prompt includes	CTL	Key
F2=	2	Function key F2. Note that in order to provide compatibility with older programs, the F2= clause is not required in `PROMPT$`.
f2=	102	Function key F2. Note that it must be a lower case f2 in the prompt, but is displayed as upper case to the user. This is another method to make the F2 key set CTL to a different value than the ArrowDn key. This is done so that the ArrowDn key can be used so the application can advance the the next field down, yet the F2 key can be used for file lookup or other application specific need. See example below.
F5=	105	Function key F5
F6=	106	Function key F6
F7=	107	Function key F7
F8=	108	Function key F8
F9=	109	Function key F9
F10=	110	Function key F10
F11=	111	Function key F11
F12=	112	Function key F12
F13=	113	Function key F13 (Although most PC keyboards do not include function keys F13 through F16 keys, there are keyboards for workstations that have 16 or more function keys. Dynamo Tools supports up to 16 function keys).
F14=	114	Function key F14
F15=	115	Function key F15
F16=	116	Function key F16
Shift+F1=	117	Shifted Function key F1
Shift+F2=	118	Shifted Function key F2
Shift+F3=	119	Shifted Function key F3
Shift+F4=	120	Shifted Function key F4
Shift+F5=	121	Shifted Function key F5
Shift+F6=	122	Shifted Function key F6
Shift+F7=	123	Shifted Function key F7
Shift+F8=	124	Shifted Function key F8
Shift+F9=	125	Shifted Function key F9
Shift+F10=	126	Shifted Function key F10
Shift+F11=	127	Shifted Function key F11
Shift+F12=	128	Shifted Function key F12
Shift+F13=	129	Shifted Function key F13
Shift+F14=	130	Shifted Function key F14
Shift+F15=	131	Shifted Function key F15
Shift+F16=	132	Shifted Function key F16
ArrowRt=	200	Right Arrow key
ArrowLf=	201	Left Arrow key
PageUp=	204	Page Up key
PageDn=	205	Page Down key
Home=	206	Home key
End=	207	End key
Insert=	208	Insert key
Delete=	209	Delete key

Example: Cause the F2 key to return a different CTL value than the ArrowDn key.

CALL "CDS069",1,20,0,0,"+serial#, f2=new 
		serialized+","A",0,SN$

User will see:

Enter serial#, F2=Lookup, F4=End 
		____________________

If they touch the ArrowDn key, then CTL will be 2, but if they touch the F2 key, CTL will be 102.

Example: Inform the user that the F5 key can be touched to create a new serialized record.

CALL "CDS069",1,20,0,0,"+serial#, F5=new 
		serialized+","A",0,SN$

User will see:

Enter serial#, F5=new serialized, F4=End 
		____________________

If they touch the F5 key, then CTL will be 105.

Example: Inform the user that the Shift+F12 key can be used to perform a special Lookup function.

CALL "CDS069",1,20,0,0,"+serial#, Shift+F12=Lookup+","A",0,SN$

User will see:

Enter serial#, Shift+F12=Lookup, F4=End 
		____________________

If they touch the Shift+F12 key, then CTL will be 128.

Example: Inform the user that the End key can be touched to Abort, and the F4 key can be used to 'End'.

CALL "CDS069",0,20,0,0,"+serial#, End=Abort+","A",0,SN$

User will see:

Enter serial#, End=Abort, F4=End 
		____________________

If they touch the End key, then CTL will be 207.

Example: Inform the user that the PageUp and PageDn keys can be touched, but without any specific action.

CALL "CDS069",0,20,0,0,"+serial#, PageUp=, 
		PageDn=,+","A",0,SN$

User will see:

Enter serial#, PageUp, PageDn, F4=End 
		____________________

If they touch the PageUp key, then CTL will be 204. If they touch the PageDn key, then CTL will be 205.

Interrupt Option

Holding down the Ctrl key and touching the "C" key, is typically configured to be the 'interrupt' key on Linux/Unix/AIX systems. You can also interrupt bbj applications by clicking the Close icon (red X on Windows, red circle with X on Mac's). By including the "E" (for Escape) prefix in the TYPE$ parameter, the prompt will include "Ctrl+C=Abort" in the prompt, and will take the ERR= option on the CALL to CDS039/CDS069 should the operator touch Ctrl+C. This option should only be used when the F4 option cannot be used.

By including the "e" prefix in TYPE$, an interrupted program will still take the ERR= option, but not include "Ctrl+C=Abort" in the prompt.

Example: Illustrating the Interrupt option.

5020 CALL "CDS069",ERR=5090,1,20,0,0,"+serial#+","EA",0,SN$

User will see:

Enter serial#, Ctrl+C=Abort, F4=End 
		____________________

If they touch Ctrl+C, then the ERR= branch will be taken, and the ERR system variable will be 99.

Global Variables

SMS_CDS069_DIS Set to related field(s), string or file verified so this information can be accessed by application. When "q" Prefix is used, the global will include cursor positioning expressions, formatted data, and related field(s) for use with the PRINT option of T type routines.

SMS_CDS069_POSN Set to the character position within the field upon exit. For example if a string variable contains ABCDEF and the cursor is on the D when the operator touched Enter, then this global with be 4, i.e., the 4th character in the variable.

SMS_CDS069_EC

Set to the exit code used by the operator to exit the field.

Keystroke used	Exit Code
ArrowDn	AD
ArrowUp	AU
Enter	CR
Function 2 Key	F2
Function 4 Key	F4

SMS_CDS069_TXT Set to the formatted text displayed. For dates this would be the formatted date, not the value of the date variable.

SMS_CDS069_DELBUF Set to the characters deleted (cut) and used when un-deleting (paste) to enable cutting text in one field and pasting the cut text in another.

SMS_CDS069.LASTPROMPT Set to the PROMPT passed to CDS069 by a background task. Used by the Dynamo Tools error routine in order to show the prompt in the heading section of the error report.

Prompt Window Example

0010 BEGIN
0020 PRINT 'CS',"Text in main window",
0030 PRINT 'WINDOW'(0,5,60,10,"Heading",'YELLOW'),
0040 PRINT 'CS','GREEN',"Text in inner window",
0050 CALL "CDS069",0,0,0,0,"No prompt window option-"
0060 CALL "CDS069",0,0,0,0,"Using 'P' prompt window option-","PA"
0070 CALL "CDS069",0,0,0,0,"Using 'p' prompt window option-","pA"
0080 PRINT 'POP',

Output