6 Define Custom Retrieval Codes

This chapter contains the following topics:

Section 6.1, "Defining Custom Retrieval Codes"

6.1 Defining Custom Retrieval Codes

Contract Billing

Navigation

From Contract Billing Processing (G52), choose 29

From Contract Billing System Setup (G5241), choose Retrieval Code Definition (P4857)

Service Billing

Navigation

From Word Order/Service Billing Processing (G48), choose 29

From Word Order/Service Billing Setup (G4841), choose Retrieval Code Definition (P4857)

The predefined retrieval codes included in the Contract Billing and Service Billing systems represent the most commonly used tables and information you use to print variable information on a customer's invoice. If you need to print special variable information that is stored in an additional system table, such an employee's social security number from the Employee Master table, you must define a custom retrieval code.

Custom retrieval codes can retrieve text or a value or perform special calculations. To define custom retrieval codes, you can:

Locate the data items that you want to use by defining unique parameters
Create a custom retrieval program
Enter narrative text to describe the code
Associate the new code with the File Field Description window

Caution: Do not delete any of the standard codes listed on the Retrieval Code Definition form. Deleting these codes causes unpredictable results.

To define custom retrieval codes

On Retrieval Code Definition

Figure 6-1 Retrieval Code Definition screen

Description of "Figure 6-1 Retrieval Code Definition screen"

Complete the following fields:
- Retrieval Code
- Description
- Parameter 1 Data Item
- Retrieval Program Name
Complete the following optional fields:
- Parameter 2 Data Item - Parameter 5 Data Item
- Send Record (Y/N)
- Repeat Until

Field	Explanation
Parameter 1 Data Item (P1DI)	You must specify a Data Item name if the parameter is used by the specified retrieval code. The Data Item controls the glossary and editing for the parameter at the time the Retrieval Code is being referenced.
Send Record (Y/N)	A Retrieval Code is generally processed in conjunction with an individual Billing Workfile record. Specific Retrieval Codes can require access to all of the information contained on the workfile record. You can use the Send Record code to instruct the system to include the entire workfile record, in one data structure, as one of the parameters passed to the Retrieval Program. You can use this field to determine which parameters from the Billing Workfile (F4812) will be passed to the Retrieval Program. The values are: Y – Yes, send the entire Billing Workfile. N – No, send only the specified parameters.
Retrieval Program Name	The Retrieval Program is the name of the program that will be executed to extract the desired data and return a value. The Retrieval Program must exist as a valid program in the user's library list by the time it is called. The program must conform to the common interface standards used by the system and must accept the correct number and type of parameters.
Repeat Until	You can use this code to control information that the system retrieves in a repetitive manner, such as lines of text within a text file. The Invoice Print program continues to use the same Retrieval Code in the same position until the specified condition is achieved. The following values are valid: blank – No repetition. Stop after the first line of text. C – Conflict. Repeat the Retrieval Code in the same position on subsequent lines until a line is reached that contains information in the same positions that the Retrieval Code would use or until the end of the format is reached. You might use this code if you were using a pre-printed form with a restricted number of lines for the information. D – Done. Repeat the Retrieval Code and the associated format line until the Retrieval Program returns an "end of file" value. Note: You must assign the same number of characters per line to the retrieval reference code as the retrieved information requires. The text will not wrap. Each line will be truncated when the characters per line is reached.

6.1.1 What You Should Know About

Topic	Description
Adding text to a custom retrieval code	You can attach descriptive text to a custom retrieval code. For example, you might want to add text to explain the specific purpose of the code or to include calculations or other descriptive information. To add text, locate the code you want and choose the View/Update Text function (F6). The system displays a text entry form. After you add text to a retrieval code, you can display the text for the code or change it at any time. The text you enter is informational only. You cannot print the text you associate with a retrieval code on a printed invoice.
Locating text for a retrieval code	You can locate text for a retrieval code from the Retrieval Code Definition form or the Retrieval Code Selection window on the Format Definition form.
Retrieving programs for a custom retrieval code	You must write a custom program to use custom retrieval codes. Use the name of the custom program in the Retrieval Program Name field when you define a custom retrieval code.

Topic

Description

Adding text to a custom retrieval code

You can attach descriptive text to a custom retrieval code. For example, you might want to add text to explain the specific purpose of the code or to include calculations or other descriptive information.

To add text, locate the code you want and choose the View/Update Text function (F6). The system displays a text entry form.

After you add text to a retrieval code, you can display the text for the code or change it at any time. The text you enter is informational only. You cannot print the text you associate with a retrieval code on a printed invoice.

Locating text for a retrieval code

You can locate text for a retrieval code from the Retrieval Code Definition form or the Retrieval Code Selection window on the Format Definition form.

Retrieving programs for a custom retrieval code

You must write a custom program to use custom retrieval codes. Use the name of the custom program in the Retrieval Program Name field when you define a custom retrieval code.