Programming API Codes

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’ To Screen-Parameters
  •     Move ‘EDITOR’ To Screen-Literal
  •     Perform Screen-Routine

This returns the user’s preferred Editor in Screen-Alpha-Field.

The following values can be obtained with this API:

  • AUTOSKIP
  • COMPANY-NAME
  • COMPANY-NO (1st two digits in Screen-Alpha-Field)
  • DOS-USER-ID
  • EDITOR
  • EMAIL-TYPE (For Elliott V8 only.  Make sure you use VERSION to check if you are running version higher than V7 before using this API)
  • LOGIN-DATE
  • LOGIN-TIME
  • LOG-PATH
  • HELP-PATH
  • MACRO-PATH
  • MAX-USERS
  • MANIFEST
  • MCMD
  • MCNTRY
  • MDATA
  • MDRIVE
  • MHELP
  • MPROG
  • MROOT
  • MSYSTEM
  • NSI-CFG-PATH
  • Elliott-CFG-PATH
  • ElliottUSER-CFG-PATH
  • Elliott-MAX-USERS
  • PROCESS-EVENTS
  • PROCESS-ID (Unique nine-digit number identifying the running .EXE)
  • REG-ADDR-1
  • REG-ADDR-2
  • REG-ADDR-3
  • REG-COBOL-DEVELOPER
  • REG-Elliott
  • REG-LIC-NO
  • REG-NAME
  • ROOT-DIR
  • SET-COMPANY-NO   (Use first two digits in Screen-Alpha-Field to set the current Company No and to be returned by the COMPANY-NO API call)
  • SHUTDOWN-FLAG
  • STARTUP-PATH
  • SUPPORT-SEGMENTED-KEYS
  • SYSTEM-VERSION
  • USE-ED
  • USER-FONT
  • VERSION
  • WAVE-PATH
  • WIN-USER-ID
  • WIN-VERSION
  • EXENAME (Find out the current EXE, like EL800.EXE or EL800DP.EXE, etc.)

BT: Bar Text

This API call will set the left text area of the status bar to a Screen-Literal value. For example:

  •     Move “BT” To Screen-Parameters.
  •     Move “Hello” To Screen-Literal.
  •     Perform Screen-Routine.

This will result in “Hello” being displayed on the left side of the status bar. To clear it, repeat the example above and move spaces to the screen-literal. Since this API only works for Elliott, you should check for the OS type in your program and only do so if you are running under the MS-WINDOWS-OS.

DI: Device Interface

The DI API allows for operation of selected serial port devices. As devices are added, this interface will be expanded. Currently, we support the following device with this API call:

            Symbol CS 2000 Consumer Scanner

Screen Parameters

Comment

DI,dd,ff,pp

 

dd = device number:

01 = CS 2000 from Symbol Technologies

ff = function number; different for each device

pp=port number:

01 = COM1

02 = COM2

03 = COM3

04 = COM4

All functions return ‘N’ in SCREEN-ANSWER if there is a failure, with a negative return code in SCREEN-NUMERIC-FIELD, and an error message in SCREEN-LITERAL

Functions for CS 2000:

01 = Initialize the port and return number of barcodes in reader in SCREEN-NUMERIC-FIELD.

02 = Return barcode data in SCREEN-AREA for the barcode number identified in SCREEN-NUMERIC-FIELD. The first byte is a barcode type identifier.

03 = Clear memory in the barcode reader.

04 = Restore the Com port.

05 = Power down the barcode reader.

 

Sample Code for Symbol CS 2000 Consumer Scanner Interface:

This is a sample program that will read content on Symbol Consumer Scanner CS 2000. Run This program by SET MSPL=FIX

       Working-Storage Section.
 
        Copy SCREEN.WS.
        01 Bc-Cnt                     Pic 999.
 
       Procedure Division.
* Read Number of Barcodes and Value in Screen-Numeric-Field. The COMM Port will be initialized (& occupied by this app)
           Move 'DI,01,01,01'         To Screen-Parameters
           Perform Screen-Routine
*Read and Delete only if interface is successful.
           If Screen-Answer = "Y"
           Move Screen-Numeric-Field   To Bc-Cnt

*Read Individual Barcode.

             Perform varying Screen-Numeric-Field from 1 by 1
                   until   Screen-Numeric-Field > Bc-Cnt
                   or     Screen-answer = 'N'
               Move 02                 To Screen-Column
               Perform Screen-Routine
               Display Screen-Literal
             End-Perform

*Delete Scanner Memory

             Move 03                To Screen-Column
             Perform Screen-Routine
           End-If
 
* Power down the scanner to save battery

           Move 05 To Screen-Column
           Perform Screen-Routine

* Restore the COMM port so other application can use the COMM port

           Move 04 To Screen-Column
           Perform Screen-Routine
           Exit Program
           Stop Run       

DM: Display Message

This API has been expanded to provide for longer messages.

  • The normal DM call has the message passed to it in Screen-Literal and is therefore limited to 80 characters.
  • DM,99 has the message passed in the first 1024 bytes of Menu-Control and therefore allows a message of up to 1024 byes.

EM: E-Mail

This is a set of API calls introduced after Elliott 6.X.060. Use them collectively. They will send out e-mails through the MAPI interface. Developers who use these API calls do not need to know how MAPI works. The following are the options that you can use with these API calls:

Screen-Parameters

Required/

Optional

Comment

EM,BG,nn,x

Required

Begin E-mail Process

  • This is a required first call to begin the process of sending a message or using the Address Book. It logs on to the mail system. If the mail system is already connected, it uses that connection.
  • Screen-Column = nn (99 means Quiet mode)
  • x = M in position 10 of Screen-Control means start using interactive eMail client (MAPI).
  • Note that this replaces the former EM,IN API.
  • Screen-Literal
  • Input - Profile Name (opt). If a Profile Name is not supplied, Ini-Prompt-for-Profile is checked to see whether to prompt the user to select a profile or automatically use the system default MAPI profile.
  • Output - If the login fails, this will contain an error message.
  • Screen-Alpha-Field = Profile Password (opt)
  • Screen Numeric Field

  • Input - ParentWindow handle (opt)
Output - If the login fails, this will contain an error code that matches the error message in the Screen-Literal.
Screen Answer
  • Input - “Y” = Display Status Messages on the Parent window’s status Bar if supplied in Screen-Numeric-Field, or on the main Elliott StatusBar if not supplied (opt).
  • Output - “Y” = MAPI is supported and the logon was successful. “N” = MAPI is not supported or the logon was not successful.

  • Screen-Column = ‘99’ signifies Quiet Mode (opt). Error messages are suppressed and the default profile is automatically used if one is not specified.


EM,RR

Optional

Return Receipt Requested (7.4E only)

·         Screen-Answer = “Y” = Request a return receipt.

  • Screen-Answer = “N” = Do not request receipt.

EM,CA

Optional

Clear Address (7.4E only)

Clear any address sent so far. This is automatically done when a ‘BG’ call is made.

EM,MA

Optional

Maximum Number of Addresses (7.4E only)

·         The default is 100 if this API is not sent

  • Screen-Numeric-Field = Total Number of Addresses for TO, CC and BC.
  • Value under 100 will be ignored
  • This call can only be sent once and must precede any other address calls (TO, CC, BC).

EM,TO

Required

To Address or Name

·         Screen-Literal = Recipient Name or Address

·         Menu-Control = Address ID returned from GA or RN call

·         Screen-Numeric-Field = Length of Address ID

  • At least one e-mail address is required
  • You can execute this API call multiple times to send to multiple recipients. This is subject to the maximum email addresses allowed. The default is 100.

EM,CC

Optional

Carbon Copy (CC) Address or Name

·         Screen-Literal = CC Recipient Name or Address

·         Menu-Control = Address ID returned from GA or RN call

·         Screen-Numeric-Field = Length of Address ID

  • You can execute this API call multiple times. It is subject to the maximum e-mail addresses allowed.

EM,BC

Optional

Blind Carbon Copy(BCC) Address or Name

·         Screen-Literal = BCC Recipient Name or Address

·         Menu-Control = Address ID returned from GA or RN call

·         Screen-Numeric-Field = Length of Address ID

·         You execute this API call multiple times. It is subject to the maximum e-mail addresses allowed.

EM,RN

Optional

Resolve Name. It is used to resolve a possibly ambiguous name (7.4E only)

  • Input

Screen-Literal = recipient name

Screen-Numeric-Field = optional window handle of calling program

·         Output

Screen-Literal = resolved name

Menu-Control = Address ID from AddressBook

Screen-Numeric-Field = Length of Address ID

 

Note: This function will be removed in v7.7.

 

 

EM,AD

Optional

Show Address Book (7.4E only)

·         The API call the address book facility to change the address

  • Input

Screen-Literal = Optional caption for the address dialog.

  • Output

Screen-Numeric-Field = Total number of addresses

·         After this API, use the EM,GA API repeatedly until you have processed all the addresses the user selected.

EM,GA

Optional

Get Address (7.4E only)

·         This API gets the next address returned from the address book facility.

  • Output

Screen-Answer = “Y” means an addressee was returned. “N” means no addressee returned.

Screen-Literal = Addressee name

Screen-Alpha-Field = ‘FR’ means a “From” name returned. ‘TO’ means a “To” name returned. “CC” means a “CC” name returned. “BC” means a “BCC” name returned.

Menu-Control = Address ID from AddressBook

Screen-Numeric-Field = Length of Address ID

 

 

EM,SB

Optional

Subject

·         Screen-Literal = Subject

EM,AT

Optional

Attached File

·         Screen-Area = Complete Path and File Name

**Note that the path is required and the attached file must exist.

·         Screen-Function-Values = Visible filename (opt)

If this area is used, the name of the file which will be visible to the recipient will be the value here followed by .TXT.

  • May be called up to 100 times per e-mail

EM,TX

Optional

Text Content of the Body of The E-mail

·         Screen-Area = Text Line

  • Screen-Area is a 160 bytes area with Screen-Literal make up the first 80 bytes and Screen-Alpha-Field make up the last 80 bytes
  • Screen-Numeric-Field = number of characters in the line to include. If Screen-Numeric-Field = Zeroes and Screen-Area is blank, a new-line character (X”0a”) will be provided.
  • You may call this API multiple times to construct a multi-line E-mail body.
  • The message body can’t exceed 1 MB.

EM,AB

Optional

Abort the E-mail

  • Abort constructing the current e-mail. The System will release all resources allocated for the current e-mail that is being constructed.

·         The message and all its characteristics are ignored.

·         Use only after a successful “EM,BG.”  You do not need to use this API if “EM,BG” was not executed successfully.

EM,SE

Required

Send E-mail Message

·         Returns ‘Y’ in Screen-Answer if the message was successful. Receiving ‘Y’ does not guarantee the e-mail is sent. It simply indicates that MAPI has accepted the e-mail, (i.e. e-mails may not sent because MAPI may not be able to connect to the e-mail transport server).

o       Screen-Numeric-Field will contain 0 if the message was sent; 1 if the message was cancelled by the user.

  • Return ‘N’ in Screen-Answer if the message was not successful
    • Screen-Numeric-Field will contain an error code
    • Screen-Literal will contain an error message.

EM,EX

Required

Exit E-Mail and Disconnect from E-mail Services

·         This does a logoff from the mail system.

·         This is automatically called by ElliottSCRN at shutdown.

  • Follow this call with Cancel “ElliottMAPI.”
  • Since the login process may be time consuming in certain environments, you may not want to call this API until all e-mails are sent. However, you should make this call as soon as possible after you are done sending e-mails.

 
Example:
 
MOVE “EM,BG” TO SCREEN-PARAMETERS.
PERFORM SCREEN-ROUTINE.
IF SCREEN-ANSWER = “N”
      PERFORM NO-MAPI-SUPPORT-MSG
      EXIT PARAGRAPH
END-IF.
 
MOVE “EM,TO” TO SCREEN-PARAMETERS.
MOVE “sales@netcellent.com” TO SCREEN-ALPHA-FIELD.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,SB” TO SCREEN-PARAMETERS.
MOVE “Sales Promotion” TO SCREEN-LITERAL.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,TX” TO SCREEN-PARAMETERS.
MOVE “Dear Business Partner:” TO SCREEN-AREA.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,TX” TO SCREEN-PARAMETERS.
MOVE “There’s a sales promotion going on at NETcellent.”
TO SCREEN-AREA.
PERFORM SCREEN-ROUTINE.
 
MOVE “EM,SE” TO SCREEN-PARAMETERS.
PERFORM SCREEN-ROUTINE.
IF SCREEN-ANSWER = “Y”
      PERFORM MESSAGE-SENT
ELSE
      PERFORM MESSAGE-NOT-SENT
END-IF.
 
If you need more examples of source code, please contact NETcellent. “EL800MAIL.CBL” can be provided to NETcellent’s developers with more detail to show you how to construct your own e-mail program.

 

Error Handling

 

Any invalid e-mail API calls will result in a message box on the screen and ‘N’ in the SCREEN-ANSWER field. However, the process will continue. For example, specifying too many recipients will result in a message box display, but the message may still be sent with the EM,SE call.

 

Depending on your situation, it might by desirable for you to write your code to check if SCREEN-ANWSER is equal to ‘N’ to determine if the situation needs special handling by the code.

 

Setting E-mail Values While Printing

 

It is possible to manipulate the values of an e-mail message during the process of sending print lines to the output file, assuming that the output is destined for an e-mail message.

 

To change an e-mail value, do the following:

 

·         Add the following COPY statements to your program:

 

      Copy SetEmail.WS.

      Copy SetEmail.PL.

 

·         MOVE   a value type as follows   TO   DETAIL-LINE:

     

TO

A primary recipient

CC

A carbon copy recipient

BC

A blind carbon copy recipient

SB

The subject line

TX

A line of text in the message body

 

·         MOVE   the value itself   TO   DETAIL-LINE(4:)

 

·         PERFORM SET-EMAIL-OPTION

 

Notes

 

1.       You may specify as many TO, CC, and BC values as you wish.

2.       The presence of any TO, CC or BC value means that all the original recipients will be replaced by the new recipient(s).

3.       You may specify as many TX values as you wish. Each value will be followed by a CR/LF.

4.       The presence of any TX value means that all the original text in the message body will be replaced by the new text.

5.       The SET-EMAIL-OPTION paragraph will MOVE SPACES TO DETAIL-LINE after calling PRINT30 or PRINT240.

6.       If the user specifies output should go to the printer or to disk, these COBOL statements will be ignored.

EC: Encode

This API encodes a string in one of two ways:

 

  • EC,01   Takes the string in Screen-Literal and encodes it using a secure algorithm. Specify the length of the string to encode in Screen-Numeric-Field. The encoded string is returned in Screen-Alpha-Field and the encoded string will be twice as long as Screen-Numeric-Field.

 

  • EC,02   Takes the string in Screen-Literal and encodes it using a simpler algorithm that returns the encoded string in Screen-Alpha-Field. The encoded string is the same length as the input string.

 

NOTE: Application programs can use this API to encode a string. However, there is no API to decode a string that has been encoded with this API. Decoding of these strings is handled by the system layer. a TB,00\n or a CO,20 call is made.

\n \n \n \n \n

CO,30

\n \n \n

Return the default contact information for the contact identified in\n PASSING-NOTE-FILE-NAME and PASSING-NOTE-FILE-REF-NUMBER.

\n \n \n \n \n

 

\n \n \n

Upon return, SCREEN-ALPHA-FIELD will contain the e-mail address,\n SCREEN-LITERAL will contain the name, and SCREEN-NUMERIC-FIELD will contain\n the contact-ID. If no contact is\n found, these fields will contain SPACES or ZEROES as appropriate.

\n \n \n \n \n

CO,99

\n \n \n

Delete all contacts from the target.

\n \n \n\n\n

 

\n\n

 

\n\n

LK: Links

\n\n

 

\n\n

Default links are established by the TB\ncalls. The LK APIs provide\nadditional links functionality.

\n\n

 

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

LK,00

\n
\n

Launch the Link whose type is in SCREEN-ALPHA-FIELD.

\n
\n

LK,01

\n
\n

Add a temporary link. \n SCREEN-ALPHA-FIELD contains the type. SCREEN-MENU Contains the\n Template which may or may not contain variables of the format @@VARn@@.

\n
\n

LK,02,nn

\n
\n

Modify the temporary link (previous LK,01 call). SCREEN-ALPHA-FIELD contains the type. nn = the variable number to replace. SCREEN-LITERAL contains the value for the\n specified variable.

\n
\n

LK,91

\n
\n

Add a permanent link; otherwise, just like LK,01.

\n
\n

LK,92,nn

\n
\n

Add a permanent link; otherwise, just like LK,02,nn.

\n
\n

LK,99

\n
\n

Remove a permanent link created by LK,91 and LK,92. SCREEN-ALPHA-FIELD contains the type.

\n
\n\n

TK: Tracking

\n\n

 

\n\n

The TK APIs will provide shipping tracking\ninformation.

\n\n

 

\n\n\n \n \n \n \n \n \n \n \n \n \n
\n

TK,01

\n
\n

Passing a length in SCREEN-NUMERIC-FIELD, the system will return the\n possible Shippers (up to 8) in SCREEN-AREA (20 bytes each) and set the\n SCREEN-ANSWER TO “Y” or “N” based on if a valid shipper was found with the\n length. The number of shippers found is stored in SCREEN-NUMERIC-FIELD.  If the actual number o


    • Related Articles

    • Btrieve Error Codes 001 - 199

      MicroKernel (Btrieve) Database Engine Status Codes This section describes status codes that the MicroKernel returns. All status codes are provided in 3-digit formats since the search on this website cannot search 1 or 2-digit words correctly. That is ...

    • Preliminary Programming Changes for Elliott 8.6

      Eliminate DAT Files Users will have the option to eliminate DAT files in Elliott V8.6 so the only files that will be in the Elliott DATA directory will be the BTR files. Some of the known DAT files are control files like ARCTLFIL.DAT, ARPCTLFIL.DAT, ...

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

    • Avalara Source Code Integration - AV API Call

      Release Date: 11/16/21 Revised: 05/23/22 Version: 8.6 and Above This article is intended for Elliott Business Software developers. This API call will allow the programmer to pass a value to indicate which Avalara function is to be performed. The ...

    • Avalara - Item Tax Codes

      Release Date: 4/28/23 Version: 8.6 and Above Tax codes (_GOODSERVICES attribute) are used to determine what tax category an item belongs to for taxing purposes. Tax codes can be assigned at the product category, user-defined code, and item levels. ...