Using Embedded IO

Appendix

Embedded IO

Description Embedded I/O procedures allow the developer to intercept file Input and Output operations on a ProvideX KEYED data file. A user-defined program is logically PERFORMed during any OPEN, READ, WRITE, REMOVE and CLOSE operation.

The program to be PERFORMed must be specified in the Data Dictionary maintenance function in Nomads to enable this feature.

The Embedded I/O program must exist and be accessible using the standard PREFIX search rules in order to open the data file. If the program does not exist, then an Error 121 (Invalid program format) is reported.

How it works

Whenever a keyed file is opened (VLR or EFF), its file header is checked to see if an embedded IO program in specified. If so, the system will then load and issue a PERFORM to various pre-defined entry points within the program in accordance to the file IO operation being executed. For example when a REMOVE is executed, the system will look for, and if found, issue a PERFORM to the label PRE_REMOVE.

The programmer only need to define those entry points they need to use, for example if the logic does not need to intercept the READ directive, then the PRE_READ and/or POST_READ entry points do not need to be defined.

Calling parameters

Most entry points are passed four arguments that can be accessed by an ENTER directive (no parameters are sent to OPEN/CLOSE).

LOCAL ACCESS_MODE, KEY$, INDEX, VALUE$, FLAG, KNO ^{(See note
below)}
ENTER ACCESS_MODE, KEY$, INDEX, VALUE$, FLAG, KNO

Where:

ACCESS_MODE	Type of access being performed: 0-Next, 1-KEY=, 2-IND=, 3-RNO=
KEY$	The value in KEY$ or NULL
INDEX	The IND or RNO value
VALUE$	The record contents being written or standard value from FIB/FID/FIN
FLAG	A flag word indicating which IO options were present on the directive: 0x0001 - DOM= 0x0002 - END= 0x0004 - NUL= 0x0008 - BSY= 0x0010 - Directive is a FIND as opposed to a READ 0x0020 - Directive is an EXTRACT as opposed to a READ
KNO	The KNO currently being used

In addition to the parameters passed to the embedded IO program, the program can return values to the file system to change the normal IO behaviour by altering the record contents etc.

Entry point/parameter information

The following is the table of pre-defined entry points that will be logically PERFORMed, the value passed in the fourth argument, and what return value can be sent back, if desired:

Directive	When 'Performed'	Entry point	Input VALUE$	Return value
OPEN	After file is Opened	<none>¹
CLOSE	Before file is actually closed	PRE_CLOSE
READ/FIND	Before the file is read	PRE_READ		Returned value is considered the data record and is passed back to the application. Physical read not done.
	After the file is read	POST_READ	Record as read from the file	Returned value is considered the data record and is passed back to the application.
EXTRACT	Before the file is read	PRE_EXTRACT²		Returned value is considered the data record and is passed back to the application. Physical read not done.
	After the file is read	POST_EXTRACT²	Record as read from the file	Returned value is considered the data record and is passed back to the application.
WRITE/UPDATE/INSERT	Before the file is updated	PRE_WRITE	Record as output by program and will/should be written to the file	A 'RETURN 0' will bypass the actual write to the file.
	After the file is updated	POST_WRITE	Record as it was written to the file
REMOVE	Before the file is updated	PRE_REMOVE
	After the file is updated	POST_REMOVE
LOCK	Before the file is locked	PRE_LOCK
	After the file is locked	POST_LOCK
UNLOCK	Before the file is unlocked	PRE_UNLOCK
	After the file is unlocked	POST_UNLOCK
PURGE	Before the file is purged	PRE_PURGE
	After the file is purged	POST_PURGE
Function	When 'Performed'	Entry point	Input VALUE$	Return value
FIB ( )	After result from FIB function	POST_FIB	Original FIB value	Revised FIB value
FID ( )	After result from FIB function	POST_FID	Original FID value	Revised FID value
FIN ( )	After result from FIB function	POST_FIN	Original FIN value	Revised FIN value
IND ( )	Before function called	PRE_IND		IND return value
KEC ( )	Before function called	PRE_KEC		KEC return value
KEF ( )	Before function called	PRE_KEF		KEF return value
KEL ( )	Before function called	PRE_KEL		KEL return value
KEN ( )	Before function calledN/A	PRE_KEN		KEN return value
KEY ( )	Before function calledN/A	PRE_KEY		KEY return value
RNO ( )	Before function calledN/A	PRE_RNO		RNO return value

¹ There is no line label entry point used when a file is OPENed as the program is simply PERFORMed.
² The PRE/POST extract routines are called if present otherwise an Extract will also attempt PRE/POST read

*Note* As the embedded IO program is performed, care must be taken that NO variables are changed within the code. All variables used should be declared as LOCAL or the routine can issue a CALL to insulate the mainline program from the IO routine. The advantage of the PERFORM is that other variables that may exist in the application will still be accessible to the logic. In particular, you should always LOCALize the entry parameters as shown above.

Example 0010 ! ENCRYPT - Embedded I/O Procedure to encrypt data 0100 ! ^100 0110 OPEN: 0120 LOCAL P$ 0130 IF %PASSWORD$="OK" THEN GOTO 0190 0140 PRINT 'WINDOW'(10,10,50,6,"Password?",'MODE'($000F$)+'CS'), 0150 OBTAIN (0,ERR=0160)@(0,1),"Please enter the password? ",P$ 0160 PRINT (0,ERR=*NEXT)'POP', 0170 IF UCS(P$)<>"PASSWORD" OR CTL<>0 THEN EXIT 52 0180 %PASSWORD$="OK" 0190 EXIT 0200 ! ^100 0210 POST_READ: LOCAL VALUE$,ACCESS_MODE,KEY$,INDEX,V$ 0220 ENTER ACCESS_MODE,KEY$,INDEX,V$ 0230 VALUE$=V$; GOSUB ENCRYPT_IT; RETURN VALUE$ 0240 END 0300 ! ^100 0310 PRE_WRITE: LOCAL VALUE$,ACCESS_MODE,KEY$,INDEX,V$ 0320 ENTER ACCESS_MODE,KEY$,INDEX,V$ 0330 VALUE$=V$; GOSUB ENCRYPT_IT; RETURN VALUE$ 0340 END 1000 ! ^1000 1010 ENCRYPT_IT: 1020 LOCAL ENCRYPT_STRING$ 1030 IF VALUE$="" THEN RETURN 1040 ENCRYPT_STRING$=”Use this string to randomize the data" 1050 ENCRYPT_STRING$=DIM(LEN(VALUE$),ENCRYPT_STRING$) 1060 VALUE$=XOR(VALUE$,ENCRYPT_STRING$) 1070 RETURN