You are here: Development Standards > OSAS Standards > Coding Conventions > Data Entry

# Data Entry

Use the general input routine, GENINPUT, for all data entry. Below are the guidelines for the format of the GOSUB statement and related variable assignments.

Record Key Input

`1200 LET X0=1,X1=10,X3=0,X4=6,X9=1,WINDID$="ARACC W1",GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Customer ID"`

WINDID$ specifies that an inquiry window should be available for this field. X9=1 clears X$ and stops Y$="P" or Y$="J". GUI_ID is the control ID of the field in the BRC file for this screen.

Normal String Input

`1200 LET X0=1,X1=10,X3=0,X4=30,X$=C1$,GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Customer Name"`

C1$ is the default customer name.

Masked String Input (numeric characters only)

`1200 LET X0=1,X1=10,X3=2,X1$=M2$,X4=LEN(X1$),X$=FNS(R9$),GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Social Security Number"`

M2$ is the social security number mask and is preset to " - - ". FNS(R9$) is a programmer-defined function that formats a social security number stored in R9$.

Numeric Input

`1200 LET X0=9,X1=19,X3=1,X1$=M1$,X4=LEN(X1$),X=C3,GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Credit Limit"`

M1$ is the numeric mask and is preset to "######0" in this example.

String Input Forced to Uppercase

`1200 LET X0=10,X1=45,X3=3,X4=2,X$=S1$,GUI_ID=4050`
`1210 GOSUB GENINPUT; REM "State"`

Masked String Input (any alphanumeric characters)

`1200 LET X0=10,X1=45,X3=4,X1$=M3$,X4=LEN(X1$),X$=SN$,GUI_ID=4000`
`1210 GOSUB GENINPUT: REM "Serial Number Field"`

M3$ is an alphabetic mask and is preset to "SN - - ]" in this example.

YES/NO Toggled Input

`1200 LET X0=9,X1=19,X3=5,X4=3,X1$="",X$=YN$,GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Do You Want to..."`

M1$ is set to null to indicate a YES/NO toggle. Setting X4=3 tells GENINPUT to toggle the words YES and NO; X4=1 toggles the letters Y and N.

Other Toggled Input

`1200 LET X0=9,X1=19,X3=5,x4=5,x1$="Red WhiteBlue GreenbLack",X$=COLOR$,`
`1200:GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Color"`

M1$ is a string containing the possible toggle values. GENINPUT parses the X1$ string in increments of X4 to define the valid entries. The first capitalized character of each valid entry is the activation key for the toggle. In the example the valid entries are R, W, B, G and L (for black). If the first character of an entry is a space and no capitalized letter is included, space is a valid entry.

If capital letters cannot be used as the first letter of a word in X1$, you may set X3=15. This will cause GENINPUT to search for the first capitalized letter within each section of X1$ and use that letter for the toggle key.

Date Input

`1200 LET X0=9,X1=19,X3=6,X=N1[1],GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Invoice Date"`

N1[1] is a Julian date. GENINPUT uses the input mask " / / " and the input length of 10 automatically when X3=6.

Full Command Input

`1200 LET X0=10,X1=5,X3=-9,X$="",GUI_ID=4999`
`1210 GOSUB GENINPUT; REM "Command entry"`

GENINPUT will return these commands in Y$ in addition to the standard letter commands defined later in this section:

+ | Down Arrow
! | Return Key
< | Left Arrow
> | Right Arrow
( | Home Key
) | End Key
= | Backspace Key
^ | Insert Key
* | Local window processing
# | Local maintenance processing or Delete Key
Z | Escape Key

The programmer must interpret and respond to the command returned in Y$ in the main program.

In GUI screens, you must make sure that an invisible GRID control is placed at the end of the screen in order to the proper values for X and Y back. See the previous sections for detailed information on GUI screen standards.

String Input (with the cursor positioned at the end of the line)

1200 LET X0=9,X1=19,X3=7,X4=64,X$=FILENAME$,GUI_ID=4000
1210 GOSUB GENINPUT; REM "Output Filename"

FILENAME$ contains a default path name for the output file. GENINPUT displays the path name and positions the cursor after it for additional input.

GL Period Input

`1200 LET X0=9,X1=19,X3=10,X=N1[2],GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "GL Period"`

N1[2] is a GL period. GENINPUT automatically uses the mask "#0" and the length of 2 when X3=10. Entry is limited to periods defined in the CNVTxxx table in RM.

Year Input

`1200 LET X0=9,X1=19,X3=11,X=N1[3],GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Year"`

N1[3] is a valid year. GENINPUT uses the input mask "###0" and the input length of 4 automatically when X3=11. Entry is limited to valid years (or blank), and 2-digit years are converted to 4-digit years automatically.

Period/Year Input

`1200 LET X0=9,X1=19,X3=12,X$=STR(N1[2]:"#0")+"/"+STR(N1[3]:"0000"),GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Period/Year"`

X$ is a valid period/year. GENINPUT uses the input mask " / " and the input length of 7 automatically when X3=12. Entry is limited to valid periods and years (or blank), and 2-digit years are converted to 4-digit years automatically. Input behaves in the same manner as date input (using the +, -, and D keys).

If the Period/Year the user enters needs to be validated as an unlocked period, set X3 = 16. This will perform the period lock checking in GENINPUT.PUB.

GL Account Input

`1200 LET X0=9,X1=19,X3=13,X$=G0$(2,12),GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "GL Account"`

X$ is a valid GL account. GENINPUT uses an input mask corresponding to the GL mask defined if GL is installed for the company. The mask and length of the field are assigned automatically when X3=13. Entries are zero-filled to the right.

Uppercase String input (with the cursor at the end of the line)

`1200 LET X0=9,X1=19,X3=7,X4=64,X$=FILENAME$,GUI_ID=4000`
`1210 GOSUB GENINPUT; REM "Output Filename"`

FILENAME$ contains a default path name for the output file. GENINPUT displays the path name and puts the cursor after it. The input is also forced to uppercase.

Additional GENINPUT Rules

Use the following additional style rules to create the variable assignments for the call to GENINPUT:

- Define the variables in the order listed above.
- Define the default field value as the next to last variable on the assignment line. Define GUI_ID as the last variable on the assignment line.
- You should either use line labels and remark statements before the assignment line to clarify what field will be prompted for, or put a remark at the end of GOSUB GENINPUT that contains the field name being entered.
- Define all the assignments for each input field before each GOSUB GENINPUT. The Up and Jump commands may make the program skip before variable assignments that were set at other input field areas.
- No other variable assignments should be performed on the same line of code.
- Define the numeric print mask via a variable. Define masks at the top of the first program of a task chain. This variable can then be used throughout the program.
- Use the LEN(X1$) function to define the maximum length of input variable X4. This makes the code independent of the actual value of the display mask.
- Forced fields, where X9=1, do not need to set a default value of X or X$, because the variable will be cleared.
- If the field shares a help screen with other similar fields in the application, you can set the variable FLD_HLP$ to a help screen name.

Commands Processing

The GENINPUT and GENERROR routines can return user commands in the variable Y$. The commands that most programs need to handle are summarized below.

Command | Description
D | Delete a record
J | Jump to the next data group
M | Exit to the menu
P | Proceed - save a record
S | Start over
U | Move up to the previous field
X | Abondon the current record
I | Invoke information windows
B | Programmer-defined command
C | Programmer-Defined command
G | Programmer-Defined command
K | Programmer-Defined command
N | Programmer-Defined command
Q | Programmer-Defined command
R | Programmer-Defined command

Some of the programmer-defined commands are used in some OSAS programs. For example, the B command (normally Shift+F3) is used for General Ledger drill-down, Inventory Item lookups, sales tax breakdowns and generating purchase requisitions in Sales Order.

Below are the coding conventions for the commands.

Command | Description
D - Delete | GENINPUT performs a GOSUB 9200 when the Delete command is issued (usually by pressing the F3 key). The Delete command is implemented by adding code to the 9200 code section. The routine at line 9200 looks like this when Delete is not available: `9200 REM "DELETE NOT IMPLEMENTED"` `9210 RETURN` Set YDISABLE$="D" in the program initialization when Delete is not available. The RETURN verb ensures that control is passed back to the calling field if YDISABLE$ is not set. Within an HLE program, if Delete is not available while in the scroll region, set DISABLE$=”D”. To accomplish a Delete task in a program, use code similar to this example: `9200 REM 9200 "DELETE ROUTINE"` `9210 LET O7=3; GOSUB GENERROR` `9220 IF Y$<>"D" THEN RETURN` `9230 REMOVE (FILE[3],KEY=X0$,DOM=9240)` `9240 LET Y$="X"` `9250 GOTO 8452` Always simulate the Abandon (X) command after Delete. If the Delete command is not verified, the routine will return to the data field where the first Delete command was issued.

Command | Description
J - Jump | The Jump command returns control to the main program. For the Jump command to be executed properly, you must add the following code to the beginning of each group of data fields: `1405 IF Y$="J" THEN LET Y$=""` As long as Y$ is "J", GENINPUT will simply return without performing data entry. The main program executes statements until Y$ is cleared. In this way data fields that require error checking will step through the error checking statements. When this extra processing is not desired, place the following statement in the appropriate places: `1205 IF Y$="J" THEN GOTO 1405` Statement 1405 should clear Y$ if Y$ is "J".

Command | Description
M - Exit | GENERROR (from GENINPUT) performs a GOTO 9990 when the Exit key is pressed (and verified if necessary). This is the convention for the 9990 section: `9900 REM 0 “Return to Menu”` `9991 QUIT:` `.` `.` `.` `9998 RUN O1$` `9999 END` Additional lines can be inserted at 9990 if the program has special processing to perform before exiting. Note: The Exit command takes you back one level from where you are. In most functions, this usually means going to the menu. Some screen overlay functions require a local Exit command to provide the user more control.

Command | Description
P - Proceed | The Proceed (PgDn) command returns control to the main program. As with the Jump command, GENINPUT does not perform data entry while Y$ is "P". If necessary, code can be skipped by placing the following line in the appropriate location(s): `1205 IF Y$="P" THEN GOTO 2000` Some fields may require user interaction. You can use `1205 IF Y$="P" THEN LET Y$=" "` to stop execution and force the user to enter a required field. After all data fields have been entered, the following code should be executed before the record is written: `2000 REM "Save the record"` `2005 PROCEED:` `2010 LET O7=2; GOSUB CLEAR_GLOBAL; GOSUB GENERROR` `2020 IF Y$="U" THEN GOTO LAST` `2030 IF Y$<>"P" THEN GOTO PROCEED` This code forces the user to press the Proceed key before the record is written if the option in Workstation Defaults for verification is set to ON.

Command | Description
S - Start Over | The Start Over command performs a GOTO 8480. A RESET is also performed to clear GOSUB/FOR information if it exists. The function of Start Over is to move the cursor to the first nonkey field on the screen without erasing the displayed data. A program should have a line labelled PAGEUP: and the appropriate GOTO statement at line 8480, such as: `8480 GOTO PAGEUP` The above code assumes that the Start Over key cannot be pressed at the key field(s). This is accomplished by setting YDISABLE$ to "S" at the key field(s), and then clearing YDISABLE$ at the first nonkey field. If YDISABLE$ isn’t used, the 8480 line needs additional logic for the GOTO statement when key fields are involved. If the screen contains simple X8$ help messages, add X8$=" "; GOSUB GENERROR here to clear them.

Command | Description
U - Up | The Up command is always available in programs that have the GENINPUT routine. To implement it, place the code immediately after GOSUB GENINPUT. It should look like this: `1402 IF Y$="U" THEN GOTO PREVIOUS` Without this additional code, the program will move down one field instead of up one field when the user uses the Up command. A program should allow the Up command to move only from a key field to the previous key field or from a nonkey field to the previous nonkey field. The Up command at the first key or nonkey field should stay at that field.

Command | Description
X - Abandon | The Abandon command (verified if necessary) performs a GOTO 8470. A RESET is also performed to clear GOSUB/FOR stack information if it exists. The function of the Abandon command is to clear the data on the screen without saving it and move to the first key field. A program should have a line labelled ABANDON: and have statements at line 8470 similar to this: `8470 READ (FILE[1],ERR=8475); REM "Remove Lock"` `8475 GOTO ABANDON` The READ statement at line 8470 ensures that no record is left locked after the Abandon command. Abandon should clear the data that is displayed, go to the key field, and start the screen over in record maintenance tasks. In addition, it can exit back one level in subwindows where discarding and starting over is meaningless.

Command | Description
I - Information | The GENINPUT.PUB program traps Information commands and passes them back to the calling program. The GENINPUT routine merged into that program performs a GOSUB INFO. The standard GENINPUT routine contains a generic "do-nothing" INFO section. If 6200 INFO: has been replaced with a functional routine, it will CALL GENINFO.PUB. That public program prompts for a selection from a menu of predefined auxiliary information display tasks. The menu to use is found in the xxMN file with a record key equal to xxINFO.

Command | Description
B, C, G, K, N, Q, Y - Programmer - Defined Commands | The GENINPUT.PUB program can also trap these other commands (on Windows machines in text mode these commands are returned by the Shift+F3 through Shift+F9 keys). Programs using these commands must contain code to trap these commands and to perform the intended task. Some of these commands are used in certain OSAS programs.

Single-Character Commands

GENINPUT has the ability to process additional commands. Set X3=9, X4=1, and X$=" ". GENINPUT.PUB will not print the default data at entry or exit of the public program and will allow for single-character input that will be returned in X$. Y$ will be “E”, which will make processing continue after the GOSUB GENINPUT entry of data fields. This eliminates the necessity of pressing Enter to enter the command.

This design requires that a command entry position be defined on the screen. The best way to implement this when in character mode is to use X8$="message" first, PRINT @(65,22), and then clear X8$ from line 22 with X8$=" "; GOSUB GENERROR. While in GUI mode, you would not want to print the X8$ message because there will be command buttons available, but you will still need an X3=9 input to trap these events.

The ASCII value of the commands returned in Y$ from GENINPUT.PUB are always inside the range 1–95. Characters above 95 are translated into uppercase characters by using the CVS() function. Data returned in X$ is untouched.

To make the same screen work in Graphical mode, you must add an invisible GRID control to the .BRC file that contains the screen on which you are working. Use the control ID 4999. Then in your program where you prompt for the keystroke, set GUI_ID to 4999 as well.