Alpha Document Number Support (V8.5/V9.0)

V8.5/V9.0 offers support for alpha numeric document numbers. This gives the user more flexibility on the number of alphabetic characters in next document number.

For example, in the scenario of the following “Starting Invoice Number” in A/R Setup:
999999 – the next number will be set to 0, duplicate invoice can happen.
A99999 – the next number will be B00000.
AA9999 – The next number will be AB0000.
AAA999 – The next number will be AAB000.
AAZ999 – The next number will be ABA000.
AAAA99 – The next number will be AAAB00.
AAAAA9 – The next number will be AAAAB0.
AAAAAA – The next number will be AAAAAB.
AAAAAZ – the next number will be AAAABA

So the number of possible document numbers depends on the number of leading alpha digits user enter in the Starting Invoice Number in A/R Setup. The system will always maintain that many number of digits of alphabetic characters. For example, if a user enters AAA001 as the starting invoice number, then the left 3 digits will always be alphabetic from A – Z. The right 3 digits will always be numeric from 0 – 9. This is important for the following reasons:
  • It will be easier to read by establishing a convention of how many alpha digits and numeric digits and their position.
  • You will be confused between 0 (zero) and O (oh).

Users do not have to make alphabetic or numeric as either leading or trailing, but it should be consistent. For example, the user can enter the following as starting invoice number:
A1239Z – the next number will be A1240A. So the rules are: 
  • Add 1 to Z = A + Carry over 1 to the left digit.
  • Add 1 to 9 = 0 + Carry over 1 to the left digit.
The rule is the digit that’s alphabetic will always be alphabetic. The digit that’s numeric will always be numeric until someone manually change the starting invoice number.

To support this in the application code, a new “O” field type for document numbers is available in V8.5/V9.0. It supports moving automatic F1 = Next Document Number logic to the system layer versus in the application code. It also supports selectively allowing alphanumeric document numbers. 

Source Code Changes


All source code that reference a document number field should be changed from a numeric field to a character field. This includes:
Sales order numbers
Work order numbers
A/P voucher numbers
A/P manual check numbers
A/P computer check numbers
Invoice numbers
Inventory Transaction Processing document numbers
BOMP engineering change numbers
Purchase order numbers
Purchase order receiving document numbers
Contract numbers for contract pricing
New EDI import order numbers
Changed EDI import numbers
COP recurring order number
ACH batch numbers
Payroll check numbers
Credit card log numbers)
Web voucher numbers
Web production order numbers
Web sales order numbers
Ship-to purchase order numbers
Physical/cycle tag numbers
A/R cash receipts check numbers

Any document number field defined as PIC 9(6), PIC ZZZZZ9, PIC Z(6), etc. should be changed to PIC X(6) in the source code.

Any document number ranges should be changed from a numeric range expecting "All" values of zeroes and nines to LOW-VALUES and HIGH-VALUES.

DM1012 01 PASSED-WORK-FIELDS.
V85DOC   03 STARTING-ORDER-NO               PIC X(6).
V85DOC     88 ALL-ORDERS-SELECTED           VALUE LOW-VALUES.
V85DOC   03 ENDING-ORDER-NO                 PIC X(6).

The entry of the range should reflect the database change as well. The IN API will us a new type of "O" for the document number field. The entry also needs to use SCREEN-ALPHA-FIELD instead of SCREEN-NUMERIC-FIELD. Since SCREEN-ALPHA-FIELD supports the entry of up to 80 characters, the conditional check for "All" must to limited to the length of the document number field.

DM1012 ENTER-STARTING-ORDER-NO.
DM1012
V85DOC   IF STARTING-ORDER-NO = LOW-VALUES
V85DOC       MOVE SPACES TO STARTING-ORDER-NO
V85DOC   END-IF.
V85DOC   MOVE "IN,04,38,06,OE,E" TO SCREEN-PARAMETERS.
V85DOC   MOVE STARTING-ORDER-NO TO SCREEN-ALPHA-FIELD.
DM1012   PERFORM ENTRY-ROUTINE.
DM1012   IF NOT END-KEY-PRESSED
V83DOC       IF SCREEN-ALPHA-FIELD(1:LENGTH OF STARTING-ORDER-NO)
V83DOC       IS = ZEROS
DM1110         MOVE "DL,04,38,06,H" TO SCREEN-PARAMETERS,
DM1012         MOVE "All " TO SCREEN-LITERAL,
V85DOC          MOVE LOW-VALUES TO STARTING-ORDER-NO,
V85DOC          MOVE HIGH-VALUES TO ENDING-ORDER-NO,
DM1012         PERFORM DISPLAY-ROUTINE,
DM1110         MOVE "CF,04,45,06" TO SCREEN-PARAMETERS
DM1012         PERFORM DISPLAY-ROUTINE
DM1012       ELSE
V85DOC         MOVE SCREEN-ALPHA-FIELD TO STARTING-ORDER-NO
DM1012         PERFORM ENTER-ENDING-ORDER-NO
DM1012       END-IF
DM1012   END-IF.
DM1012
DM1012 ENTER-ENDING-ORDER-NO.
DM1012
V85DOC   IF STARTING-ORDER-NO IS = LOW-VALUES AND
DM1012       NOT NO-CHANGES
DM1012       NEXT SENTENCE
DM1012   ELSE
V85DOC       IF STARTING-ORDER-NO IS NOT = LOW-VALUES
V85DOC         IF ENDING-ORDER-NO = HIGH-VALUES OR
V85DOC             ENDING-ORDER-NO = SPACES
DM1012             MOVE STARTING-ORDER-NO TO ENDING-ORDER-NO
DM1012         END-IF
V85DOC         MOVE "IN,04,45,06,OE,A" TO SCREEN-PARAMETERS
V85DOC         MOVE ENDING-ORDER-NO TO SCREEN-ALPHA-FIELD
DM1012         PERFORM ENTRY-ROUTINE
DM1012         IF NOT ABORT-KEY-PRESSED
V85DOC             IF SCREEN-ALPHA-FIELD(1:LENGTH OF ENDING-ORDER-NO)
V85DOC             IS = ZEROS
DM1012               MOVE STARTING-ORDER-NO TO ENDING-ORDER-NO
V85DOC               MOVE "DF,04,45,06,O" TO SCREEN-PARAMETERS,
V85DOC               MOVE ENDING-ORDER-NO TO SCREEN-ALPHA-FIELD
DM1012               PERFORM DISPLAY-ROUTINE
DM1012             ELSE
V85DOC               MOVE SCREEN-ALPHA-FIELD TO ENDING-ORDER-NO
DM1012             END-IF
DM1012         END-IF
DM1012       END-IF
DM1012   END-IF.
DM1012

If the ending document number does not default to the starting document when a specific document number is entered, most likely the field was initialized with zeroes instead of spaces. For example, the bold code below
009570 INITIALIZE-FILES.
009580   MOVE SPACES TO ENTRY-FIELDS.
009590   MOVE ZERO TO ITEM-NUMBER-TO-CHANGE
009600                 STARTING-DATE
009610                 ENDING-DATE
009620                 STARTING-NO
009630                 ENDING-NO.

Should be changed to
009570 INITIALIZE-FILES.
009580   MOVE SPACES TO ENTRY-FIELDS.
009590   MOVE ZERO TO ITEM-NUMBER-TO-CHANGE
009600                 STARTING-DATE
009610                 ENDING-DATE.
009620   MOVE SPACES TO STARTING-NO
009630                   ENDING-NO.

If the issue is with a purchase order number, look for the definition of the range:

CC0308   03 STARTING-PO-NO.
V85DOC     88 ALL-POS-SELECTED             VALUE LOW-VALUES.
V85DOC     05 STARTING-ORDER-NO           PIC X(6).
CC0308     05 STARTING-RELEASE-NO         PIC 9(2).
CC0308   03 ENDING-PO-NO.
V85DOC     05 ENDING-ORDER-NO             PIC X(6).
CC0308     05 ENDING-RELEASE-NO           PIC 9(2).

Purchase order number contains two components, an order number and a release number. If spaces are moved to the ENDING-PO-NO field during initialization, the release number will be evaluated as zeroes. This needs to be taken into consideration when determining if the starting purchase order number should be moved to the ending purchase order number when entering the range. Value checks should be done on the ENDING-ORDER-NO field instead of the ENDING-PO-NO-FIELD.

CC0308 ENTER-ENDING-PO-NO.
CC0308
V85DOC   IF STARTING-PO-NO = LOW-VALUES
CC0308       NEXT SENTENCE
CC0308   ELSE
V85DOC       IF ENDING-ORDER-NO = SPACES OR
V85DOC         ENDING-ORDER-NO = HIGH-VALUES
CC0308         MOVE STARTING-PO-NO TO ENDING-PO-NO
CC0308       END-IF

IN Input API: 


V8.5 Screen Parameters: IN,03,20,06,O ,E178

V9.0 Screen Parameters: IN,03,20,09,O ,E178

  

A new field type “O” is supported for document number fields. Code “O” in place of “*”.

Document numbers should be moved to and from SCREEN-ALPHA-FIELD instead of SCREEN-NUMERIC-FIELD.  Pressing return without entering any data will return zeroes to SCREEN-ALPHA-FIELD. 

Currently V7.5/V8.2 application will then check if SCREEN-NUMERIC-FIELD is zeroes. This check needs to be done on SCREEN-ALPHA-FIELD instead using a LENGTH of clause. For example:

Before ( V7.5/V8.2):

IF SCREEN-NUMERIC-FIELD = ZEROES

After (v8.5/V9.0):

IF SCREEN-ALPHA-FIELD(1:LENGTH OF ORDER-NO) = ZEROES

Two new fields are now used in conjunction with the IN API:

a.      SCREEN-FIELD-DOMAIN will identify the kind of document number being entered. This field must be provided if the F1 key will be used to obtain the next document number during entry. The following fields are supported at this time:

  • COP-CTL-START-ORDER-NO (for sales orders)
  • BM-CTL-NEXT-ORDER-NO (for legacy work orders)
  • BM-CTL-NEXT-MATER-ORDER-NO (for material work orders)
  • BM-CTL-NEXT-PLUS-ORDER-NO (for plus work orders)
  • AP-CTL-LAST-VOUCHER-NO (for vouchers)
  • WS-N29-NEXT-MANUAL-CHECK (for manual checks issued in Accounts Payable)
  • AR-CTL-START-INVOICE-NO (for invoice numbers)
  • IM-CTL-NEXT-DOC-NUMBER (for document numbers in Inventory Transaction Processing)
  • BM-CTL-NEXT-ENGR-CHG-NO (for engineering change numbers)
  • PO-CTL-STARTING-PO-NO (for purchase order numbers)
  • PO-CTL-NEXT-DOC-NO (for purchase order receiving document numbers)  
  • WS-NSB-STARTING-CONTRACT-NO (for contract pricing)  
  • WS-NSK-NEW-IMPORT-ORDER-NO (for importing new EDI orders)
  • WS-NSK-CHG-IMPORT-ORDER-NO
  • NS-CTL-LAST-INV-NO-USED (last invoice number used during invoice printing)
  • WS-NSK-START-RECUR-NO (for COP recurring orders)
  • WS-N30-ACH-LAST-BATCH-NO (for ACH batch numbers)
  • PR-CTL-LAST-CHECK-NUMBER (for payroll checks)
  • WS-NSB-NEXT-CREDIT-LOG-NO (for credit card log numbers)
  • AP-OPEN-CHECK-NO (A/P computer check) 
  • WS-NSF-LAST-WEB-VOUCHER-NO
  • WS-N22-NEXT-WEB-PROD-ORDER
  • WS-NSB-NEXT-WEB-ORDER-NO
  • SHIP-TO-STARTING-PO-NO
  • COUNT-TAG-NO (for physical/cycle tag number)
  • CASH-CHECK-NO (for A/R cash receipts)


b.      SCREEN-F1-NEXT-DOC-NO, when set to “Y” on an IN call with F1 enabled, will handle the user pressing F1. The next document number will be retrieved and returned in SCREEN-ALPHA-FIELD with F1-KEY-PRESSED set to TRUE.

After an IN call if using numeric document numbers, the resulting document number will be right-justified and zero-filled on the screen – no need for a follow-up DF call.

SCREEN-FIELD-DOMAIN and SCREEN-F1-NEXT-DOC-NO will be blanked out after the IN and DF calls.

If an IN call is made for the document number type:

  1. If SCREEN-DOMAIN-FIELD is not set, the System Manager will check if alpha document numbers are allowed. If not, only numeric entry will be allowed in the field. If they are allowed, any entry A-Z and 0-9 is allowed.
  2. If SCREEN-DOMAIN-FIELD is set to one of the values listed above and SCREEN-F1-NEXT-DOC-NO is not set to Y, the System Manager will check if alpha document numbers are allowed. If not,  only numeric entry will be allowed in the field. If they are allowed, the the setting for SCREEN-FIELD-DOMAIN will be checked against Global Setup. If that document type allows alpha entry,  any entry A-Z and 0-9 is allowed. If it does not, only numeric values can be entered.
  3. If SCREEN-DOMAIN-FIELD is set to one of the values listed above and SCREEN-F1-NEXT-DOC-NO is set to Y, the System Manager will check if alpha document numbers are allowed. If not, only numeric entry will be allowed in the field. If they are allowed, the setting for SCREEN-FIELD-DOMAIN will be checked against Global Setup. If that document type allows alpha entry, the system will allow entry with either format control, warning if format not used, or free form entry. If it does not allow alpha document numbers, only numeric values can be entered.  

Example 1: Enter order number without F1 and alphanumeric support:

Current code (V7.5/V8.2):   

MOVE “IN,03,20,06,* ,E78” TO SCREEN-PARAMETERS

MOVE ZEROES TO SCREEN-NUMERIC-FIELD

PERFORM SCREEN-ROUTINE

MOVE SCREEN-NUMERIC-FIELD TO ORDER-NO

New code (V8.5/V9.0):

MOVE “IN,03,20,09,O ,E78” TO SCREEN-PARAMETERS

MOVE SPACES TO SCREEN-ALPHA-FIELD

PERFORM SCREEN-ROUTINE

MOVE SCREEN-ALPHA-FIELD TO ORDER-NO

In the above example, SCREEN-FIELD-DOMAIN is not required, because we do not need it for F1 support, nor for alphanumeric support.

 

Example 2: Enter order number with F1 support and alphanumeric support:

Current code (V7.5/V8.2):   

MOVE “IN,03,20,06,* ,E178” TO SCREEN-PARAMETERS

MOVE ZEROES TO SCREEN-NUMERIC-FIELD

PERFORM SCREEN-ROUTINE

IF F1-KEY-PRESSED

  …

MOVE SCREEN-NUMERIC-FIELD TO ORDER-NO

New code (V8.5/V9.0):

MOVE “IN,03,20,09,O ,E178” TO SCREEN-PARAMETERS

MOVE SPACES TO SCREEN-ALPHA-FIELD

MOVE “COP-CTL-START-ORDER-NO” TO SCREEN-FIELD-DOMAIN

MOVE “Y” TO SCREEN-F1-NEXT-DOC-NO

PERFORM SCREEN-ROUTINE

MOVE SCREEN-ALPHA-FIELD TO ORDER-NO

In the above example, SCREEN-FIELD-DOMAIN and SCREEN-F1-NEXT-DOC-NO is be used for F1 support and SCREEN-FIELD-DOMAIN is used to retrieve the next order number.

DF API: Display Field


V8.5 Screen Parameters: DF,03,20,06,O 

V9.0 Screen Parameters: DF,03,20,09,O 

 

A new field type “O” is supported for document number fields. Code “O” in place of “*”.

Document numbers should be moved to and from SCREEN-ALPHA-FIELD instead of SCREEN-NUMERIC-FIELD.

Current code (V7.5/V8.2):   

MOVE “DF,03,20,06,*” TO SCREEN-PARAMETERS

MOVE DOC-NO TO SCREEN-NUMERIC-FIELD

PERFORM SCREEN-ROUTINE

New code (V8.5/V9.0):

MOVE “DF,03,20,06,O” TO SCREEN-PARAMETERS

MOVE DOC-NO TO SCREEN-ALPHA-FIELD

PERFORM SCREEN-ROUTINE


DN API: Document Number Increase, Rollback or Validate

A new API is available in V8.5/V9.0 to increment the document fields by 1 and to also check if we can roll back (reverse) the increment if no other user has incremented the number. This type of code would be used when there is no user interface and the document numbers are incremented programatically.

Reverse Document Number

Move “DN,-” To Screen-Parameters

Move “AP-CTL-LAST-VOUCHER-NO” To Screen-Field-Domain

Move Last-Voucher-No to Screen-Alpha-Field

Perform Screen-Routine

The new value in AP-CTL-LAST-VOUCHER-NO is returned in SCREEN-ALPHA-FIELD.  If an error occurs, SCREEN-ANSWER will contain "N".

Increase Document Number

Move “DN,+” To Screen-Parameters

Move “AP-CTL-LAST-VOUCHER-NO” To Screen-Field-Domain

Move Spaces to Screen-Alpha-Field

Perform Screen-Routine

Move Screen-Alpha-Field to New-AP-Voucher-No

Note:  If the domain name contains the string "-LAST", the DN,+ call will increment the number on the file and then return that number in Screen-Alpha-Field.  If the domain name does not contain "-LAST", that implies that the number in the file is the next available number, not the last used number.  Accordingly, the DN,+ call will return the number in the file, and then increment the number in the file.  This all means that the DN,+ call will always return the number you should use for a new document.

The DN API can also be used to increase or decrease an alpha document number without updating the a master number. This is useful in situations where there is no master number on file but the application code computes the next number by finding the last record on file in the database. An example of this situation is alpha tag number support. The next tag number is calculated based on the highest tag number on file. Once the highest tag number is retrieved, the application will add 1 to the last value. This is not possible when using alpha document numbers. The DN API takes the place of the add statement, performs the computation and returns the value in SCREEN-ALPHA-FIELD.  If an error occurs, SCREEN-ANSWER will contain "N".

Increase Document Number with No Master File Update

Move “DN,+” To Screen-Parameters

Move Spaces To Screen-Field-Domain

Move Last-Tag-No to Screen-Alpha-Field

Perform Screen-Routine

Move Screen-Alpha-Field to Count-Tag-No 

Move Screen-Alpha-Field to Last-Tag-No

Notes: 

  • For a DN,+ call, either the SCREEN-FIELD-DOMAIN must be set or the SCREEN-ALPHA-FIELD must contain the document number to be incremented.
  • For a DN,- call, SCREEN-ALPHA-FIELD must be set to the number that needs to be rolled back.
  • The value of SCREEN-FIELD-DOMAIN must be set before the DN API call is invoked. It can be set to one of the values listed above or if not applicable, it should be set to spaces. Failure to do so could result in the following type of error message:


Validate Document Number

The DN API can also be used to validate a document number. This can be used, for example, when importing data from an outside source:

    Move "DN,V" To Screen-Parameters

    Move "COP-CTL-START-ORDER-NO" To Screen-Domain-Name

    Move IMP-ORDER-NO To Screen-Alpha-Field

    Perform Screen-Routine

    If Screen-Answer = "Y"

        ...

    Else

        Move Screen-Literal to Error-Message  

    End-If

If the format of the input matches the required format for that document, Screen-Answer will contain "Y"; if not, Screen-Answer will contain "N" and Screen-Literal will contain a description of the error.

Check Screen-Answer After DN API Calls

Prior to v8.5, all the logic for incrementing and rolling back of a document number resided in the application program.  So, if there happened to be a non-recoverable I/O error, the application program's DECLARATIVES section would handle the displaying of the error to the user, closing any open files and exiting the program.  Now, that burden of reacting to any error, including non-recoverable I/O errors, falls to the application program. 

Following are the possible error messages returned in Screen-Literal if Screen-Answer = "N":
  • Error n/nnn xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Illegal Domain xxxxx
  • DN+ requires either a field domain or a document number
  • Document type xxxxx not supported
  • DN,- requires the document number to be reversed
  • Domain name missing
  • Document number must be numeric
  • NWDOCNBR function 99 is not supported
The first format requires the program to react to a non-recoverable I/O error.

The remaining messages most likely would occur during initial development.  Nevertheless, they should be coded for.


CLS

Developer Documentations

  1. Received Code 9999 with Web Services Call
  2. Received Return Status Code 3 When Using Elilogin Login Method
  3. Elliott Web Service Requirements
  4. Elliott eStore Checklist
  5. LN API
  6. FN API
  7. RN API
  8. IN and DF API Change (V9.0)
  9. FA API Changes (V9.0)
  10. VA API Changes (V9.0)
  11. CartService
  12. EliarachService
  13. ElicshtxService
  14. EliattrbService
  15. ElisyscdService
  16. EliNoteService
  17. El2rstimService
  18. EliOrderService
  19. ItemInquiry
  20. EliitmiqService
  21. EliShiptoService
  22. El2getfrService
  23. Steps Required to Test ReportWriter in V8.2
  24. Installation of ElliottService, NETcellent’s Web Services for Elliott
  25. ResellerFinder
  26. EliaptrxService
  27. VendorInquiry
  28. EliloginService
  29. ElislsmnService
  30. EliserhsService
  31. EliatpobService
  32. ElievprcService
  33. ElihdtrxService
  34. ElicuswlService
  35. QueryTurnaround
  36. InvoiceInquiry
  37. ElicustmService
  38. EligetcdService
  39. OrderInquiry
  40. EliordiqService
  41. EliecontService
  42. EliautdpService
  43. El2CrCrdService
  44. Log-Timer / ElliottTimer.Ini Support
  45. Alpha Document Number Support (V8.5/V9.0)
  46. ElliottService System.TypeInitializationException
  47. Feature - Printing API to Dynamically Set Number of Copies
  48. The Values and Meanings of Distribution Types - ARDISFIL, APDISFIL, IMDISFIL, BMDISFIL
  49. DD API Changes (V9.0)
  50. PA API (8.5)
  51. Validate License API
  52. AP API
  53. TP API: Temporary Path
  54. Data Structures for Report Desk Defaults and Enforcements
  55. COBOL to VB Interface Programs
  56. IN API: Option to Support Files and Folders Validation
  57. FF API: File Functions
  58. ID API
  59. LK: Links API
  60. FFLNearYou
  61. Report Desk Developing and Debugging
  62. Developing a New Elliott V8.6 Report Desk User Defined Report (UDR)
  63. CustomerInquiry
  64. Elliott API (JSON Web Service)
  65. Animating COBOL Code in Elliott V8.5
  66. Preliminary Programming Changes for Elliott 8.6
  67. CV API
  68. System Lock File Requirements
  69. How to Write Test Codes for C# ESS Projects
  70. Solving the Inability to Debug Elliott on a New Server
  71. Report Desk: Developing Custom Reports
  72. Report Desk Tables
  73. Report Desk Database Delivery Strategy

Feedback and Knowledge Base