CacheProcessAddressBookTree

Cache, Process Address Book Tree

Master Business Function

Object Name: B0100050

Parent DLL: CALLBSFN

Location: Client/Server

Language: C

Business Function Specification

Source NameB0100050DesignerC. Cox
Data Structure D0100050ProgrammerT. Edwards
Function NameCache, Process Address Book TreeSystem Code01
Function Category
Function Use

Revisions Log
DateProgrammerSAR NumberDescription
03/09/98C. Cox 2050028Created.
03/27/98T. Edwards 2050028Programming Completed

1.Functional Description

1.1Purpose
This function will perform Get, Add, Update, Delete, Delete All, Get Next, Add/Update, and Terminate functions on the Address Book Tree Cache used
in the business functions B0100049.

The calling application is responsible for loading all appropriate key values to the data structure and identifying the number of keys to use in
retrieval/update processes.

1.2 Setup Notes and Prerequisites

• Cache Action Codes
• •

'1' Get - retrieve the cache element.
• '2' Add - add a cache element.
• '3' Update - update a cache element.
• '4' Delete - delete a cache element.
• '5' Delete All - delete all cache elements
• '6' Get Next - retrieve the next cache element
• '7' Add/Update - will add if element does not exist, will change if it does exist.
• '8' Terminate - terminate cache
• '9' Release Cursor - close the input cursor
• 'D' Debug Mode - Dumps the contents of the entire cache into a text file.
•

'b7'b7'b7'b7'b7'b7
• Number of Keys
• •
If the number of keys is passed as a parameter, the business function uses this value to setup
key values for a Get, Update, Delete, Get Next, and Add/Update.
• A zero may be passed to retrieve, update, or delete the first record.
•
'b7'b7'b7'b7'b7'b7
• When action code GET is used, the function saves the cache cursor pointer if the fetch is successful
and SequentialFetch = '1'.  This allows the calling application to use GET NEXT to fetch elements
from the cache sequentially.  If GET NEXT is called until the end of the keyed cache dataset is found,
the function automatically closes the open cursor.  Otherwise, the calling application is responsible
for closing the cursor using action code '9'.
• 'b7'b7'b7'b7'b7'b71.3Special Logic
This function creates a cache named "CUSTREE_" + Input Cache Name or Job Number.

2.Technical Specifications

2.1Parameters:

Data Item Data Structure DescriptionI/ORequiredNotes
INTLevelI/OYLevel of the Address book relative to the parent.
(Key 1 of  2)
AN8Address Book NumberI/OYAddress Book Number. (Key 2 of 2)
EV01Cache Action CodeIY'1' = Get cache element
'2' = Add element
'3' = Update element
'4' = Delete cache elements
'5' = Delete All cache elements
'6' = Get Next cache element '7'  = Add/Update cache element
'8' = End cache (terminate cache) '9' = Close Cursor and Free Data Ptr
'D' = Debug Mode
EV01Cache Error CodeON'0' = Success Process
'1' = Reached End of Cache(mode 6)
'2' = Invalid Input Parameter
'3' = Failed to Create Cache
'4' = Failed to Add/Update Cache
'5' = Failed to Delete Cache
'6' = Fetch Failed(mode 1)
INT01Number of KeysIYNumber of Keys to be used in the cache process.
(Max 2)
SUPPSSuppress Error MessageIN'0'=allow runtime error message handling.
'1' = Suppress runtime error message
handling.
DTAIError Message IdON"   " = Success
"032E" = Error Processing Cache
GENLNGCache Cursor PtrI/ON
EV02Sequential FetchINIf action is GET and this parm is '1', function will
pass back cursor pointer for GET NEXT operation.
JOBCache Name or Job NumberIYRequired in naming the cache.

2.2Related Tables
Table Table Description
None

2.3Related Business Functions
Source NameFunction Name
None

2.4Processing
Cache Layout:Cache includes all of the following fields; key fields are noted.

Data Item Data Structure DescriptionKey Field
AN8Address Book NumberY
INTLevelY

I.Perform setup functions
A.Initialize cache to get handle.
B.If not successful, set error "032E", set Cache Error Code = '3', and return failure.
C.Validate input parameters Number Of Keys, Action Code, and Comparison Flag.
D.If not valid, set error "032E", set Cache Error Code = '2', and return failure.
E.Set Cache Error Code = '0'
F.Set return code to success.

II.Processing Based on Mode.

A.If Cache Action Code is '1' - GET:
1.Open cursor.  If the input Cursor Pointer is not NULL, retrieve the existing cursor and reset it.
2.Retrieve the first element on the cache matching the key values passed as input.  If the input Number of Keys is zero, fetch the first
element in the cache.
3.Load the values from the retrieved element into the data structure to be passed back to the calling program.
4.If SequentialFetch = '1', return cursor pointer to calling application.  Otherwise, close the cursor.
5.If get fails set Cache Error Code = '6'.

B.If Cache Action Code is '2' - ADD:
1.Insert a new cache element with values from data structure.
2.If add fails set error "032E", set Cache Error Code = '4', and return failure.

C.If Cache Action Code is '3' - UPDATE:
1.Update existing cache element with values from data structure.
2.If update fails set error "032E", set Cache Error Code = '4', and return failure.

D.If Cache Action Code is '4' - DELETE:
1.If the Number of Keys is not 0, delete all elements in the cache matching the key values passed as input.
2.If the number of keys is 0, delete the first cache element.
3.If delete fails, set Cache Error Code = '5'.

E.If Cache Action Code is '5' - DELETE ALL:
1.Delete all elements in the cache.
2.If delete fails, set Cache Error Code = '5'.

F.If Cache Action Code is '6' - GET NEXT:
1.Using the input cursor pointer from the previous GET action, retrieve the next element in the cache matching the key values passed
as input (the cursor should have been set through a previous "Get" action, i.e. action code '1'.  If the Number of Keys is zero then fetch
the next record without using any key).
2.Load the values from the retrieved element into the data structure to be passed back to the calling program.
3.If there are no more elements, close the cursor and set Cache Error Code = '1'.

G.If Cache Action Code is '7' - ADD/UPDATE:
1.Delete Record , if one exists,  that matches the full key from Input.
2.Insert a new cache element with values from data structure.
3.If add fails set error "032E", set Cache Error Code = '4', and return failure.

H.If Cache Action Code is '8' - END
1.If the input CacheCursorPtr is not zero, retrieve the pointer and close the cursor.
2.Perform cleanup functions (Terminate cache).

I.If Cache Action Code is '9' - CLOSE CURSOR:
1.Retrieve the Data Ptr (Cache Cursor Ptr must not be Zero).
2.Close cursor.
3.Free Data Ptr and Set Cache Cursor Ptr to 0.
J.

Data Structure

D0100050 - Cache, Process Address Book Tree Data Structure

^

Parameter Name Data Item Data Type Req/Opt I/O/Both

nLevel INT01 integer REQ BOTH

Number of Days in Future to Query for Responses Due.

mnAddressNumber AN8 MATH_NUMERIC REQ BOTH

A number that identifies an entry in the Address Book system, such as employee, applicant, participant, customer, supplier, tenant, or
location.

cCacheActionCode EV01 char REQ INPUT

An option that specifies the type of processing for an event.

cCacheErrorCode EV01 char OPT NONE

An option that specifies the type of processing for an event.

nNumberOfKeys INT01 integer REQ INPUT

Number of Days in Future to Query for Responses Due.

cSuppressErrorMessage SUPPS char OPT NONE

A flag indicating whether or not runtime error messaging will occur when an error message is issued from a business function.        0 = allow
runtime error message handling.        1 = suppress runtime error message handling.

szErrorMessageID DTAI char OPT NONE

A code that identifies and defines a unit of information. It is an alphanumeric code up to 8 characters long that does not allow blanks or
special characters such as %, &, or +. You create new data items using system codes 55-59. You cannot change the alias.

idCacheCursorPtr GENLNG ID OPT NONE

General purpose ID variable.

cSequentialFetch EV02 char OPT NONE

An option that specifies the type of processing for an event.

szCacheNameOrNumber JOB char REQ INPUT

Job Number

Related Functions

None

Related Tables

None

Parameter Name	Data Item	Data Type	Req/Opt	I/O/Both
nLevel	INT01	integer	REQ	BOTH
Number of Days in Future to Query for Responses Due.
mnAddressNumber	AN8	MATH_NUMERIC	REQ	BOTH
A number that identifies an entry in the Address Book system, such as employee, applicant, participant, customer, supplier, tenant, or location.
cCacheActionCode	EV01	char	REQ	INPUT
An option that specifies the type of processing for an event.
cCacheErrorCode	EV01	char	OPT	NONE
An option that specifies the type of processing for an event.
nNumberOfKeys	INT01	integer	REQ	INPUT
Number of Days in Future to Query for Responses Due.
cSuppressErrorMessage	SUPPS	char	OPT	NONE
A flag indicating whether or not runtime error messaging will occur when an error message is issued from a business function. 0 = allow runtime error message handling. 1 = suppress runtime error message handling.
szErrorMessageID	DTAI	char	OPT	NONE
A code that identifies and defines a unit of information. It is an alphanumeric code up to 8 characters long that does not allow blanks or special characters such as %, &, or +. You create new data items using system codes 55-59. You cannot change the alias.
idCacheCursorPtr	GENLNG	ID	OPT	NONE
General purpose ID variable.
cSequentialFetch	EV02	char	OPT	NONE
An option that specifies the type of processing for an event.
szCacheNameOrNumber	JOB	char	REQ	INPUT
Job Number