DN API (Document Number Handling)

DN API (Document Number Handling)

Release: 1/11/2021
Version: V8.5 and higher

DN API: Document Number Increase, Roll Back or Validate

In Elliott V8.5, the system supports alphabetic document numbers. The logic to sequentially assigning the next document number is complicated. For example, if the existing document number is AAZ999. Then the next document number will be ABA000. We use the algorithm so the alphabetic digits stay alphabetic and numeric stay numeric. Instead of imbedding this complicated logic in the application codes, it make sense to have a system-level API call to handle this complication.  

A new API is available in V8.5 and up 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 programmatically.

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 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 below 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-Field-Domain
    Move IMP-ORDER-NO To Screen-Alpha-Field
    Perform Screen-Routine
    If Screen-Answer = "Y"
        Move Screen-Alpha-Field To IMP-ORDER-NO
        ...
    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.

Note: Additionally, the application code can allow the DN,V code to properly align the input document number (e.g., right-justify and zero-fill a numeric document number) instead of coding that on the application side.  When that is the case, the application code must move Screen-Alpha-Field back to the source field after the DN,V call, because what is in Screen-Alpha-Field passed the validation, not the input source. For example, if the input value is "AB123," it will result in error since the value is alphabetic and hence the length must be 6 digits long. On the other hand, if the input value is numeric, then the length of the value is OK when it is less than or equal to 6 digits.

There is a special logic for domain PO-CTL-STARTING-PO-NO where systems can validate input with or without a dash.  For example, if the input is "9999," the system will deem this to be OK and return 0099999 by filling in leading zeroes on the left in the SCREEN-ALPHA-FIELD. On the other hand, if the input is "9-99," the system will validate this to be OK and return 000009-99 as the return value.

Validate Document Number Format

The DN API can also be used to validate a "next" document number like the next order number for COP:

    Move "DN,F" To Screen-Parameters
    Move "COP-CTL-START-ORDER-NO" To Screen-Field-Domain
    Move COP-CTL-NEXT-ORDER-NO To Screen-Alpha-Field
    Perform Screen-Routine
    If Screen-Answer = "Y"
        ...
    Else
        Move Screen-Literal to Error-Message  
    End-If

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.

Screen-Field-Domain Values

Following are the valid SCREEN-FIELD-DOMAIN values supported by DN calls:
  • 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)
  • WS-N39-PSI-NEXT-ORDER-NO

CLS/JEG

Updated: 6/8/23




    • Related Articles

    • 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: ...

    • Multi-Currency Exchange Handling in Elliott

      Release Date: 08/30/2017 Multi-Currency Exchange Handling in Elliott Introduction Elliott is not designed as a multi-currency package. However, there are common practices you can use that have been adopted by Elliott users to perform multi-currency ...

    • Programming API Codes

      This document is provided for Elliott software developers. If you are not an Elliott software developer, this document is not meaningful for you. AP: Get SMA Values This API returns various values from the Shared Memory Area. For example: Move ‘AP’ ...

    • ARCRCMNT Accounts Receivable Credit Card Transacting Handling

      Credit Card Transacting Handling Application Overview This application allows you to process credit card payments as a cash receipts function with postings and distributions as determined by the Credit Card Source File, (AR Maintenance). Run ...

    • FA API Changes (V9.0)

      FA: File Access (Without File Handling) This API can be used to retrieve an individual field from a specific record in a file without specifying the file in the program and without opening and closing the file. In its simplest form, one can, for ...