ProvideX. Embedded IO Procedures

Transcription

1 ProvideX Embedded IO Procedures Introduction 1 Implementation 1 Pre-Defined Entry Points 2 Execution Environment 3 Changing Return Values 4 Possible Applications 5 Sample Code 5

2 ProvideX is a trademark of Sage Software Canada Ltd. All other products referred to in this document are trademarks or registered trademarks of their respective trademark holders Sage Software Canada Ltd. Printed in Canada 50 Burnhamthorpe Rd. W., Suite 700 Mississaugua, ON L5B 2C2 All rights reserved. Reproduction in whole or in part without permission is prohibited. The capabilities, system requirements and/or compatibility with third-party products described herein are subject to change without notice. Refer to the Sage ProvideX website for current information. Publication Release: V9

3 Embedded Input/Output (IO) procedures provide the ability to intercept and control all file IO directives and functions using a user-defined program. The program is called when the file is accessed by an OPEN, READ, FIND, EXTRACT, WRITE, REMOVE, PURGE, LOCK, UNLOCK, CLOSE, and all KEY( ), IND( ), RNO( ) and FIB( )/FID( )/FIN( ) functions. The program name can be specified using Data Dictionary Maintenance, which writes it to the internal data dictionary structure of the file, or it can be specified using the SETDEV directive on an already open channel. Both Pre and Post operations are provided for most directives while functions have either a Pre or a Post operation. Int roduction Implementation Embedded IO procedures allow the developer to intercept file input and output operations on a ProvideX KEYED data file, or on any channel using the SETDEV directive. A user-defined program is logically invoked using the PERFORM directive during use of any of the above-mentioned IO directives. In order for the program to be invoked on an OPEN of the file, the name of the program must be written to the file's internal data dictionary. This is only available for KEYED files, and is done using the ProvideX Data Dictionary Maintenance function in NOMADS, or through a custom program using the DICTIONARY WRITE directive. The embedded IO program must exist and be accessible using the standard PREFIX search rules in order to open the data file. If the program cannot be located, then an Error #121: Invalid program format is reported and the OPEN will fail. To use an IO procedure on any other type of file, a SETDEV directive must be executed after the channel has been opened. ProvideX V9 Back 1

4 The syntax for the SETDEV directive appears as follows: SETDEV(channel) PROGRAM "IOProc" Where: channel Channel number to which the IO procedure program is assigned. IOProc User-defined program to PERFORM. Example: 10 OPEN(1)FID(0) 20 SETDEV (1) PROGRAM "ioproc.tst" Note: If the specified program is not accessible, an Error #121 is not generated on execution of the SETDEV directive. To verify the program can be located, OPEN or ADDR the program prior to issuing the SETDEV directive to ensure that ProvideX can access it. Another option is to reference the currently executing program; e.g., SETDEV(1) PROGRAM PGN. Pre-Defined Entry Points When file input/output is performed, the user-defined program will be logically invoked using a PERFORM at the following pre-defined entry points: Directives PRE_READ PRE_EXTRACT PRE_WRITE PRE_REMOVE PRE_PURGE PRE_LOCK PRE_UNLOCK PRE_CLOSE POST_READ POST_EXTRACT POST_WRITE POST_REMOVE POST_PURGE POST_LOCK POST_UNLOCK POST_PASSWORD Functions PRE_KEY PRE_KEL PRE_KEC PRE_IND POST_FIB POST_FID PRE_KEF PRE_KEP PRE_KEN PRE_RNO POST_FIN ProvideX V9 Back 2

5 Execution Environment Additional Notes: There is no line label entry point used when a file is opened, as the program is simply invoked. The CLOSE directive only supports the PRE_CLOSE entry point. If the entry point for a particular function does not exist, no error will be reported. All entry point labels are optional, and ProvideX will only PERFORM the routines that exist within the program The program is invoked logically using the PERFORM directive, therefore it is recommended that all variables within the IO procedure be declared LOCAL. This will prevent variables referenced in the IO procedure from conflicting with any program accessing the file. Command mode processing is not recommended within an IO procedure. Although it may be possible to add an ESCAPE to the IO procedure to have it drop to console mode, doing so will produce undesirable results and will most likely terminate the ProvideX session. The IO procedure can generate an error which in turn will be returned to the function or directive being executed. Errors may be generated by the IO procedure as follows: EXIT error Where: error Error number to report back to the directive or function accessing the channel. Additional Notes: Any error reported by the IO program is reported as an IO error on the file. While the IO procedure is executing, any subsequent file access to the same file is not passed to the file IO procedure. A normal ProvideX PERFORM does not allow an ENTER statement; however, there is a special ENTER provided for IO procedures. The following arguments are passed to the IO procedure: ENTER access_mode, key$, index, value$, access_options, keynumber Where access_mode key$ 0-Next, 1-Key, 2-IND=, 3-RNO=. Value in key$ or null. ProvideX V9 Back 3

6 index value$ access_options keynumber Value in IND=, RNO=, or KNO= (if KEY= specified). Record contents for READ/WRITE. Bit-masked type value indicating the following: 1 - DOM= specified 2 - END= specified 4 - NUL= specified 8 - BSY= specified 16 - FIND directive 32 - EXTRACT directive Value of KNO=. Changing Return Values All parameters are read-only, and are not supplied for OPEN and CLOSE operations. Note: The POST_READ and POST_EXTRACT logic is performed prior to the variables in the IOList being populated with data. This allows the data in the record to be modified before it is available for use by the program accessing the file. If a TIM= clause was specified on the File IO directive, then the value is reported in TCB(92). The I/O program can alter the return value using: RETURN xxx$ -or- RETURN xxx A RETURN string/numeric in Pre logic will result in the Post logic not being executed, with the following exception: If the Pre write returns a string value, that value is used to update the record and the Post write routine will still be executed. If the Pre write returns a numeric then the write is skipped as is the Post write logic. ProvideX V9 Back 4

7 Possible Applications Sample Code Security and data encryption - Apply passwords and/or encrypt the data. Data integrity. Data replication. Prevent a customer from being deleted when there is an outstanding balance. Remove cross-reference information from all files before deleting a customer. Normalizing data files -Re-direct alternate records types to normal files. Circular file journalizing -Maintain a queue of the last nnn # of transactions. 0010! ENCRYPT - Embedded I/O Procedure to encrypt data 0100! ^ OPEN:! This label is for informational purposed only, the program 0111! " execution started at line 10 when the open was performed 0120 LOCAL P$ 0130 IF %PASSWORD$="OK" THEN GOTO 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', 0165! Next line is an example of forcing an error to be returned using 0166! the EXIT err 0170 IF UCS(P$)<>"PASSWORD" OR CTL<>0 THEN EXIT %PASSWORD$="OK" 0190 EXIT! end of open routine 0200! ^100 " Start of POST_READ routine 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! End of POST_READ routine 0300! ^ 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! ^ 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 ProvideX V9 Back 5

8 ProvideX V9 Back 6