CA Dataquery supports a User-Defined Functions (UDF) Exit for DQL Mode which allows you to provide CA Dataquery users with special mathematical functions, such as exponentiation or extraction of roots. See DQOPTLST Parameters for details about the UDFMOD= parameter of the System Option Table.
Operation
CA Dataquery gives the User-Defined Functions Exit control when it recognizes the UDF identifier during SET statement processing. (The UDF identifier is UDF and is located in a SET statement, such as, SET A =UDF(7,X,Y).)
Procedure
This exit must be coded in Assembler language and should be reentrant or reusable. This exit cannot issue monitor calls and I/O requests. When you write this exit, make certain it contains processing routines for every mathematical function you anticipate needing. A maximum of 255 are allowed.
Following the UDF identifier is a parameter list, enclosed within parentheses, that provides details about the function wanted and the operands to use.
Upon entry to the User-Defined Functions Exit the following is provided to the exit:
Points to a seven-word parameter list consisting of the following entries (in order from the beginning of the list):
Address of a 1-byte binary function code indicating the function requested.
A 1-byte binary count of the input arguments specified by the UDF function list in the SET statement, followed by a 3-byte address of a list of the argument values. The argument values are each 9-bytes long and consist of a high-order byte containing a binary count of the number of decimal places contained in the value and an 8-byte packed decimal field containing the argument. If a query has multiple SET statements, a maximum of eight input arguments can be passed to the exit. Up to twelve parameters can be passed when only one SET statement is specified.
Address of an area where the result of the function is to be stored. This area consists of a 1-byte binary count of the number of decimal places in the result followed by a packed decimal field containing the result.
Address of a 172-byte area (doubleword aligned) to be used as needed by the exit. The area is not initialized on entry. The high-order byte of this word contains the length of this area in binary.
Note: The following three parameters have been added to support numbers having more than 15 decimal digits. Version 8.0 and above supports up to 18 digits, while prior version supported only fifteen. These new parameters need only be used when arguments or results might exceed 15 digits. Otherwise, UDF exits coded to use the four-word parameter list (previous versions) will continue to function as always.
A 4-byte address of a list of the argument values. The argument values are each 17 bytes long and consist of a high-order byte containing a binary count of the number of decimal places contained in the value and a 16-byte packed decimal field containing the argument. The high-order byte of this parameter does not contain the argument count.
A 4-byte address of a 1-byte overflow indicator. This indicator is set to a character Y if any of the arguments contains more than 15 decimal digits. In this case, the exit should use the argument list containing 16-byte packed decimal values, provide a 16-byte packed decimal result, and set the result length to '16.' Otherwise error 18 results when the value is formatted in a report, for example, ***E18***.
A 4-byte address of a 2-character result length indicator. This indicator is preset to 08 and must be changed to 16 by the exit when a 16-byte result is returned. A 16-byte result is always permitted. It is necessary to avoid the error 18 on the report when any of the arguments has more than 15 digits. When the length indicator is not changed to 16, the packed result field addressed by PARM word 3 is expected to be 8 bytes long, as was assumed in prior versions of CA Dataquery. This allows UDF exits coded before 18-digit support was implemented to continue functioning unchanged.
Contains the address of a register SAVE area which you must use to save and restore CA Dataquery's registers according to standard linkage conventions.
Contains the return address within CA Dataquery.
Contains the address of the entry point of the exit.
Prior to returning control to CA Dataquery, the exit must place one of the following return codes in register 15:
Signifies a normal return. No errors were found. The result has been stored in the area pointed at by word three of the parameter list.
If your exit has detected any type of error while performing a function on the data, an error code can be returned to CA Dataquery. Register 15 should contain a binary error number within the range of 80—99 (decimal). CA Dataquery will place a special error flag in the pertinent column of the output report in the following form, where nn indicates the error code:
**Enn**
Implementation
To implement the User-Defined Functions Exit:
For samples, see the CA Datacom website.
|
Copyright © 2014 CA.
All rights reserved.
|
|