CDX100 - T-Type external routines

CDX100

T-Type External Routines

When special processing is required to enter, display, or validate a field, an external template based callable routine (T- type external routine) can be written. When interfaced to the Dynamo Data Dictionary, these routines will be called to display, enter, and print records when using the View Manager CDS550, or HTML View Manager CDW550. File Maintenance and other application programs call CDS550 to display and manage standard views. CDS555 can also call T-Type routines to perform custom data validation.

The T-type external routine is recommended over the deprecated C-type and X-type routines. The primary advantage of the T-type routine, is that the entire record template is passed to the external routine. The routine can access and even change other fields in the record.

There is an example program named CDX100 included with Dynamo Tools that can be copied and used as a template when writing T-Type routines.

Calling Format:

CALL "CDX100", S039$, REC$, X100$

CDX100 Arguments

Field Passed To/From Description

S039$ To All parameters for entry and display. See CDS039.

REC$ To/From The templated record containing the field to be displayed, entered or printed. The primary data element used is FIELD(REC$,S039.FLDNAM$,S039.INDEX) or NFIELD(REC$,S039.FLDNAM$,S039.INDEX).

X100$

To/From

T-type external routine parameters

Field Passed To/From Description

ACTION$

To/From

Code to control action that external routine will take.

Value	Description
B	The external routine is called with `X100.ACTION$="B"` when building the display background. If the routine requires more than one display row, or requires additional text to display on the screen background, then the routine should populate `X100.ROWS` and `X100.BKGFLD$`, otherwise the external routine can simply `EXIT`.
blank	Routine should perform any data entry. Note that some T Type routines are used for display only and not used for data entry.
Q	Routine should display data
P	Routine should return data in `X100.OUT$` for printing and should include the cursor positioning expression `@(S039.COL,s039.ROW)`.
W	Routine should return data in `X100.OUT$` for display on a web page which cannot include any cursor positioning expression.
H	Routine should return HTML in `X100.OUT$` that can be used for data entry on a web page. Typically this would include <input> or <select> tag or possibly even check boxes, radio buttons, or drop down lists.
V	Routine should validate data and return any error message in `X100.OUT$`. No need to `EXIT [ERR]`. The routine can also modify the data. See CDS555.
R	Set by the external routine when it changes other fields in the view to signal view manager CDS550 to re-display the view.

ROWS From In most cases you do not need to set X100.ROWS. It can be set to the number of display rows required by this T-type routine, when the number of rows cannot be determined by counting the pipe symbols contained in X100.OUT$ when X100.ACTION$ is passed as B.

OUT$

From

`X100.ACTION$`	T-Type routine should set `X100.OUT$` to
B	Background text that the view must display in addition to the Description field specified in the Data Dictionary. Note that if the Description field is null, then the Title field is used. This field can contain mnemonics such a `'BU'` and `'EU'` as well as cursor positioning expressions `@(col,row)`.
P	Text that can be printed to a printer or other output device. This field can contain mnemonics such a `'BU'` and `'EU'` as well as cursor positioning expressions `@(col,row)`.
W	HTML when displaying a view on a web page. Can include any valid html tags to set text and background colors, include hyperlinks, etc
H	HTML when entering this field within an html form
V	Validation error message

The lines in yellow are intended to be modified or removed

0100 REM "CDX100 - 05/03/14 Template for T-type external routine

0110 SETESC 8000; SETERR 8000

0120 ENTER S039$,REC$,X100$

0130 ON POS(X100.ACTION$="BQPWHV") GOSUB ENTRY,BKG,DISPLAY,PRINT,WEB,WEBINPUT,VALIDATE

0140 EXIT

1000 ENTRY:

1010 LET S039.TYPE$="A"

1020 CALL "CDS039",S039$,REC$

1090 RETURN

1100 BKG:

1110 IF MULTIPLE_ROWS THEN LET X100.ROWS=6

1120 IF ROW_TEXT THEN LET X100.OUT$="| 2nd field row| 3rd field row"

1190 RETURN

1200 DISPLAY:

1210 GOSUB PRINT

1220 PRINT X100.OUT$,

1290 RETURN

1300 PRINT:

1310 LET X100.OUT$=@(S039.COL,S039.ROW)+FIELD(REC$,S039.FLDNAM$,S039.INDEX)

1390 RETURN

1400 WEB:

1410 GOSUB WEBTXT

1420 IF WHITE_ON_RED THEN LET TXT$="<div style='color:white;background-color:red'>"+TXT$+"</div>"

1430 LET X100.OUT$=TXT$

1490 RETURN

1500 WEBINPUT:

1510 GOSUB WEBTXT

1520 LET X100.OUT$="<input type='text' name='"+S039.FLDNAM$+"' value='"+TXT$+"'>"

1590 RETURN

1600 WEBTXT:

1610 LET TXT$=FIELD(REC$,S039.FLDNAM$,S039.INDEX)

1620 CALL "SW002::XML",TXT$

1630 RETURN

1700 VALIDATE:

1710 IF DATA_IS_INVALID THEN LET X100.OUT$="Data is not valid"

1790 RETURN

8000 REM "Call Error/Escape Routine

8010 CALL "CDS063",STR(TCB(5)),Y$,PGM(-2)

8020 ON Y.ERRSTS GOTO 8030,8040,8050,8060

8030 SETERR 0

8040 RETRY

8050 RETURN

8060 RETRY

9000 EOJ:

9010 IF TCB(13) THEN EXIT

9020 RUN "CDS001"

This example is taken from Dynamo where a piece of rental machinery may have a fuel tank. If a fuel tank capacity is entered, then the operator should also be prompted for the fuel type. This is an example where two data fields are entered within a single T-type called routine.

0100 REM "IM003 - 04/16/08 Fuel Capacity & Type (T)

0110 SETESC 8000; SETERR 8000

0120 ENTER S039$,IM01$,X100$

0130 ON POS(X100.ACTION$="BQP") GOSUB ENTRY,BKG,DISPLAY,PRINT