27 Functional Servers

This chapter contains these topics:

• Section 27.1, "About Functional Servers"

• Section 27.2, "What Are Functional Servers?"

• Section 27.3, "What Are the Advantages of Using a Functional Server?"

• Section 27.4, "What Are the Disadvantages of Using a Functional Server?"

• Section 27.5, "Setting Up Business Rules for an Entry Program"

• Section 27.6, "How Does a Functional Server Function?"

• Section 27.8, "The Call Parameters for the Functional Server"

• Section 27.9, "Control Fields within the User Space"

• Section 27.10, "Error Message Index Line (C00RIX)"

• Section 27.11, "Example - Functional Server Program Sections"

• Section 27.12, "Available Functional Servers"

27.1 About Functional Servers

A functional server allows you to enhance the processing and maintenance of your application programs. Functional servers provide a central location for standard business rules about entering documents, such as vouchers, invoices, and journal entries. These business rules establish the following:

• Data Dictionary default values

• Field edits and valid values

• Error processing

• Relationships between fields or applications

27.2 What Are Functional Servers?

A functional server is a program that performs all transaction validation and database updates.

The functional server removes from the application program the burden of performing edit and update operations. Rather, this functionality is placed within the server.

A functional server is a called program. The application program calling the server must tell the server what action to perform for every transaction. In turn, the functional server will record error flags and update flags and return error messages to the application program for use when determining the result of a call to a server.

Functional servers have the following naming convention:

XT (file name) (server version)

For example: The functional server for file F0411 would appear as XT0411Z1.

The following diagram depicts the flow of a typical program using a functional server:

Figure 27-1 Program Flow Using a Functional Server

Description of "Figure 27-1 Program Flow Using a Functional Server"

27.3 What Are the Advantages of Using a Functional Server?

Advantages of using a functional server include:

• Minimized maintenance and versioning of your software.

• Ability to isolate data editing routines and file updates.

• Increased flexibility because multiple programs can use the same functional server.

• Smoother transition from an old database to a new database. Instead of modifying all programs, you will only have to apply a new set of functional servers.

• Ability to implement one functional server at a time without affecting your entire system.

27.4 What Are the Disadvantages of Using a Functional Server?

Disadvantages of functional servers include:

• A functional server is minutely slower because you are performing an external call to the server from your program.

• Functional server programs tend to be large.

27.5 Setting Up Business Rules for an Entry Program

To set up business rules for an entry program

You can have all your entry programs use the same DREAM Writer version (and thus, use the same rules) or you can set up different DREAM Writer versions. JD Edwards World provides DREAM Writer version ZJDE0001 as the default functional server version for your entry programs.

1. Create a DREAM Writer version for a specific functional server program (for example, XT0411Z1 for voucher entry).

2. Set the processing options within the version according to your company requirements.

3. Specify the version you want the entry program to use in the processing options for that entry program.

Caution:

Only the person responsible for system-wide setup should make changes to the functional server version. For more information about how to set up DREAM Writer versions, see the JD Edwards World Technical Foundation Guide.

27.6 How Does a Functional Server Function?

When a functional server is called, an entire transaction is processed.

• Generally, once a functional server is called, it receives the data that the user entered and loads it into a user space.

• It performs its functionality on the data.

• Finally, it returns the requested data back to the calling program using the user space. If any errors occur, the system loads them into a user index.

The system uses the following interfaces to communicate with the functional server:

• The call parameters

• The control fields within each user space line

• The error index

27.7 Functional Server Highlights

Functional servers are usefully for many things, highlights include:

• Provides all editing for a transaction

• Provides field default values

• Provides all database updates

• Performs inquiry for an entire transaction

• Runs interactively or in batch

• Supports a multitude of user interfaces

27.7.1 Basic Accounting Transactions

In the Financial System there are five basic transactions:

• Journal Entries

• A/P Voucher Entry

• A/P Checks

• A/R Invoice Entry

• A/R Cash Receipts

Figure 27-2 Basic Accounting Transactions

Description of "Figure 27-2 Basic Accounting Transactions"

JD Edwards World uses one program for each part or transaction of the system.

27.7.2 Example: Voucher Processing Functional Server

The following graphic shows the programs that use the voucher processing functional server. JD Edwards World provides two demo versions of the functional server, ZJDE0001 and ZJDE0002.

Figure 27-3 Programs That Use the Voucher Processing Functional Server

Description of "Figure 27-3 Programs That Use the Voucher Processing Functional Server"

27.7.3 Program Example - Traditional Architecture

Figure 27-4 Program Example - Traditional Architecture

Description of "Figure 27-4 Program Example - Traditional Architecture"

Each program contains both the User Interface Logic and the Data Integrity Logic. You would access this one program to interface with the database.

27.7.4 User Interface Logic

Aspects of the user interface logic include:

• Screen format

• Field formatting

• Help functions

• Error message display

• Touch and feel

27.7.5 Data Integrity Logic

Aspects of the data integrity logic include:

• Field editing

• Multi-field editing

• Transaction editing

• Default logic

• Error message selection

• Tax processing

• Currency processing

• Database update

27.7.6 Example - Traditional Architecture - Alternative Method of Entry

Figure 27-5 Traditional Architecture - Alternative Method of Entry

Description of "Figure 27-5 Traditional Architecture - Alternative Method of Entry"

If a user wanted the screen to look different, the User Interface Logic would have to change. The Data Integrity Logic would be duplicated.

27.7.7 Example - Traditional Architecture - Various Entry Methods

Figure 27-6 Traditional Architecture - Various Entry Methods

Description of "Figure 27-6 Traditional Architecture - Various Entry Methods"

Several users each wanted their own User Integrity logic. The Data Integrity Logic remained the same and was duplicated numerous times.

27.7.8 Example - JD Edwards World Open Application Architecture - Various Entry Methods

Figure 27-7 Open Application Architecture Concept

Description of "Figure 27-7 Open Application Architecture Concept"

The creation of a Functional Server allows you to maintain the Data Integrity Logic in one common program. The Functional Server becomes separated from each User Integrity Logic program. All of the User Integrity Logic programs access one Functional Server to interface with the database. This concept is called an Open Application Architecture.

27.7.9 Open Application Architecture

In the Open Application Architecture, the database is separated from each User Integrity Logic program by the Functional Server. Advantages of the Open Application Architecture include:

• Automatic consistency

• Reduced maintenance burden

• Stability of custom code

• Separation of development efforts

• Performance enhancements

Figure 27-8 Open Application Architecture

Description of "Figure 27-8 Open Application Architecture"

27.7.10 Functional Server Interface

A functional server must handle two basic components:

• Data

• Error messages

Figure 27-9 Functional Server Components

Description of "Figure 27-9 Functional Server Components"

27.7.11 Functional Server Transaction Data

Arithmetic:

1. Full transaction passed to server at one time.

2. A single transaction can have more than 1,000 lines.

3. Each line from 500 to 1,000 characters long.

= A lot of space

Story Problem:

How can program A pass program B a one-thousand line transaction without using a 1-meg parameter?

27.7.12 Functional Server Error Messages

Arithmetic:

1. Each field can have an error.

2. Each line can have 150 or more fields.

3. Each transaction can have hundreds of lines.

= A lot of space

Story Problem:

How can program A pass program B a one-thousand line transaction without using a 1-meg parameter?

27.7.13 Answers

#1. User Space

#2. User Index

27.7.14 Functional Server Interface

A Functional Server can interact with a User Space and a User Index by passing and receiving parameters.

27.7.15 Functional Server Parameters

Single data structure defined in /COPY module.

Parameters that are fixed and application specific.

• Fixed parameters

  • Action code (edit, update, inquire)

  • Number of lines in transactions

  • DREAM Writer version of Functional Server

• Application specific parameters

  • Contains header information for a transaction

  • Document number of transaction

  • Total amount of transaction

  • Batch number of transaction

27.7.16 Functional Server User Space

Single data structure defined in /COPY module.

• One big data area

• Maximum of 16 meg

• Beginning 100 bytes of user space reserved

• Data portion of user space contains formatted lines

  • User space lines defined by /COPY module

  • Each line contains three sections

    1) Control section

    2) Application specific section

    3) Record format section

27.7.17 Functional Server User Index

Single data structure defined in /COPY module.

• One big keyed data area

• Used to pass error messages back to application

• User index entry defined using a /COPY module

• Each user index entry contains two sections

  • 1) Key

    Application ID

    Line number (assigned by application program)

    Data item in error

    Error code

• 2) Data - value of erroneous data

27.7.18 Functional Server /COPY Modules

Repository for all user space and user index formats.

• All User Space and User Index formats contained in /COPY modules

• All database record formats contained in /COPY modules

• /COPY module I00FS@@ contains generic data structures and constants

• Each Functional Server has its own I00FSxx /COPY module to define application specific data structures

27.7.19 Creating User Space and User Index

When you create user space and user index formats, use the following tools:

• OS/400 APIs

• X00991

  • Called once for each Functional Server the application program intends to use

  • Creates user space and user index for each Functional Server

  • Returns name and library where user space exists

  • Returns the length each user space line should be

27.7.20 Accessing the User Space

• Writing to the user space X98CHGUS.

  • .JD Edwards World version of QUSCHGUS API

  • Updates a user space beginning at offset x for length

  • Similar to CHGDTAARA command

• Reading from the user space QUSRTVUS.

  • API

  • Retrieves data from a user space beginning at offset x for length

  • Similar to RTVDTAARA command

• Application responsibilities

  • Remember number of lines written to user space

  • Increment user space offset

27.7.21 Accessing the User Index

• User Index written to by Functional Server.

• Reading from the User Index.

  • C00RIX/COPY module reads the User Index

  • C00RIX returns formatted error message defined by /COPY module

  • First execution of C00RIX reads first entry in User Index

  • Subsequent executions of C00RIX do read nexts

  • Uses X00IDX under the covers

• Application responsibilities.

  • Remember the value of your Application ID (typically program name)

  • Set flag for initial read of User Index by C00RIX

  • Use the data item name and line number in error to set ON screen indicators

27.7.22 Interactive Program Cycle Using a Functional Server

• Mainline - no change

• S001 - no change

• S003

  • No change for add, change, or delete

  • Call Functional Server to perform an inquiry

• S004 - Retrieve records from User Space for display on screen

• S005

  • Application program performs "scrubs" only

  • Write data records to User Space

  • Call Functional Server to perform edits

  • Read each line from User Space to redisplay defaulted information

  • Execute C00RIX to determine each data item in error so that screen error indicators may be set ON

• S010 - call Functional Server to perform an update

27.8 The Call Parameters for the Functional Server

The call parameters provide commands to the functional server which applies to all transaction lines in the input user space.

The first parameter is a Data Structure. The following fields are from the #PPARM Data Structure defined in the I00FS@@ copy module.

PARM (Length)	Description
#PFUNC (1)	Specifies a function code. The valid values are: 0 – Edit and Update 1 – Edit only 2 – Update only I – Inquire
#PVERS (10) (3 before A6)	The DREAM Writer version number you are executing. This parameter uses the version number to retrieve processing options for the server. The default version number will be ZJDE0001. This allows global processing options to be set at the server level, instead of for each program.
#PSPCN (20)	The name of the user space which the program has used. The user space contains the modified database records. Characters 1-10 contain the space name, and characters 11-20 contain the library name.
#PSPCB (9,0)	The byte position within the user space where the application data begins. Characters in the space prior to this position contain header information used by the functional server.
#PNBRL (5,0)	The number of lines in the input user space which the application program has loaded. When inquiring, this contains the number of lines output to the user space.
#PWARN (1)	This parameter contains a code explaining how you want warnings to be handled. The valid values are: 0 – Normal warning processing 1 – Treat warnings as errors 2 – Ignore warnings
#PCYCL (1)	This parameter is only used if the #PWARN parameter specifies normal warning processing. The valid values are: 0 – No cycle, all cycle processing ignored 1 – First cycle, all warning messages are sent to the program 2 – Second cycle, only warning messages not previously sent are sent to the program
#PDFTC (1)	Specifies how you want field values to be defaulted. 0 will default field values for add lines only and 1 will default field values for change or add lines.
#PXATP (3)	The application specific transaction type.
#PLVL (1)	The transaction level. 0 implies that each detail record to be updated or added has been sent in the input user space. 1 applies only to changes or deletions because only one record is sent in the input user space and the server will change or delete all other records for that transaction.
#PPROG (10)	The name of the calling program. This is used by the server to update the program name field in the updated database records.
#PAPPL (10)	The application ID value used for writing entries to the error index. Generally, this may be the same value as the calling program.
#PFLDS (4,0)	The number of fields which have been loaded to the Field Names Array parameter.
#PFMT (10)	The record format identifier the application program has used. This is used for versioning, allowing the database to change without the need for recompiling the application program.
#PEDIT (1)	Indicates the overall result of edits performed against all transaction lines. 0 implies that the edits went OK, 1 means there were some warnings, 2 is errors occurred.
#PUPDT (5,0)	The number of database updates which occurred. This will allow the program to know whether any updates actually occurred.
#PERR (4)	Specifies any errors that occurred within the server. A non-blank value indicates a fatal error occurred.
#PFERR (4)	Contains the first error message found during editing.
#PFDTA (4)	Contains the data item of the first field which had an error during editing.
#P#MDE (1)	For currency translations, this contains the mode of entry. If this value is passed as blank, the server will output the default mode of entry.
#PCRCD (3)	For currency translations, this contains the currency code of entry. If this value is passed as blank, the server will output the default currency code.
#PCRR (15,7)	For currency translations, this contains the currency exchange rate of entry. If this value is passed as zero, the server will output the default currency rate.
#PIDXN (20)	The name of the user index which the functional server will use to return error messages to the program. Characters 1-10 contain the index name, and characters 11-20 contain the library name.
#PSPCL (5,0)	The total length of each user space record. This includes both the user space control fields and the database record format.
#PSPEC (250)	This is a data structure which is redefined by each server. Generally, this will contain the application key fields which a specific server uses.

The second parameter will be an array.

PARM (Length)	Description
Variable Array	An array of field names which the program has used. Only fields in this array will be updated in the database. If the first element contains *ALL, then all fields will be used. The number of field names parameter should contain the number of entries loaded into this array.

27.9 Control Fields within the User Space

The input user space can contain multiple lines for each control field. The following fields are defined in the #SSPCR Data Structure in the I00FS@@ copy module.

PARM (Length)	Description
#SPCAC (1)	The line action code. The valid values are: A – Add the record D – Delete the record C – Change the record U – Change the record if it already exists, otherwise add the record V – Void the record
#SPCID (15,0)	Used by the program to uniquely identify each line in the user space. (optional)
#SPCER (1)	The line error code. X = the line is OK 1 = some warnings 2 = errors.
#SPCUP (1)	The line update code. 0 = the line was not updated 1 = updated
#SPCRR (9,0)	Contains the database relative record number which corresponds to this user space record. For adds, this is only loaded following an update operation. For changes and deletes, this is updated following an edit operation.
#SPCMN (2,0)	Contains the database physical file member number which corresponds to this user space record. For adds, this is only loaded following an update operation. For changes and deletes, this is updated following an edit operation.
#SPCPG (12)	Allows the program to store up to 12 bytes of information with each user space record.
#SPCAP (200)	Any application specific information which must be passed to the server for each transaction line, but is not contained within the transaction record format.
Application fields	Externally described record format for the transaction record.

27.10 Error Message Index Line (C00RIX)

The output error message index contains warning and error messages issued for each line in the user space. The following fields are from the #IIDXR Data Structure defined in the I00FS@@ copy module. The structure of the message index line is as follows:

Field (Length)	Explanation
#IDXAP (10)	The application identifier from the input parameter. Allows a program to access only its error messages.
#IDXID (15,0)	The line identifier from the input user space.
#IDXFN (10)	The data item portion of the field name.
#IDXER (4)	Contains the data dictionary error message code.
#IDXWN(1)	Line warning code 1 = Warning, 2 = Error.
#IDXMD (87)	Not used.

27.11 Example - Functional Server Program Sections

Figure 27-10 Functional Server Program Sections (part 1)

Description of "Figure 27-10 Functional Server Program Sections (part 1)"

Figure 27-11 Functional Server Program Sections (part 2)

Description of "Figure 27-11 Functional Server Program Sections (part 2)"

Figure 27-12 Functional Server Program Sections (part 3)

Description of "Figure 27-12 Functional Server Program Sections (part 3)"

Figure 27-13 Functional Server Program Sections (part 4)

Description of "Figure 27-13 Functional Server Program Sections (part 4)"

Figure 27-14 Functional Server Program Sections (part 5)

Description of "Figure 27-14 Functional Server Program Sections (part 5)"

Figure 27-15 Functional Server Program Sections (part 6)

Description of "Figure 27-15 Functional Server Program Sections (part 6)"

Figure 27-16 Functional Server Program Sections (part 7)

Description of "Figure 27-16 Functional Server Program Sections (part 7)"

Figure 27-17 Functional Server Program Sections (part 8)

Description of "Figure 27-17 Functional Server Program Sections (part 8)"

Figure 27-18 Functional Server Program Sections (part 9)

Description of "Figure 27-18 Functional Server Program Sections (part 9)"

Figure 27-19 Functional Server Program Sections (part 10)

Description of "Figure 27-19 Functional Server Program Sections (part 10)"

Figure 27-20 Functional Server Program Sections (part 11)

Description of "Figure 27-20 Functional Server Program Sections (part 11)"

Figure 27-21 Functional Server Program Sections (part 12)

Description of "Figure 27-21 Functional Server Program Sections (part 12)"

Figure 27-22 Functional Server Program Sections (part 13)

Description of "Figure 27-22 Functional Server Program Sections (part 13)"

27.12 Available Functional Servers

Functional Server	Description	Notes
XT0101Z1	Address Book
XT0311Z1	Accounts Receivable
XT0311Z1E	Accounts Receivable	User Exit
XT0411Z1	Accounts Payable
XT0411Z1E	Accounts Payable	User Exit
XT06116Z1	Payroll Time Entry
XT0901Z1	Account Master
XT0911Z1	Journal Entry
XT0911Z1E	Journal Entry	User Exit
XT4102Z1	Item Balance